Claude Code CLI 使用教程：从安装到项目自动化实践

前言

Claude Code 是 Anthropic 面向开发者推出的命令行 AI 编程助手。它不是一个只能聊天的工具，而是可以在终端里理解项目、读取代码、修改文件、运行测试、调用工具、创建任务并辅助完成软件工程工作的 CLI Agent。

如果你已经习惯在 VS Code、JetBrains 或终端中工作，Claude Code 的价值在于：它可以直接进入你的项目目录，围绕当前代码上下文协作，而不是让你反复复制粘贴文件内容。本文将以实用教程的方式介绍 Claude Code CLI 的安装、登录、基础用法、常用命令、权限机制、项目配置、MCP 扩展、Hooks 自动化和日常最佳实践。

一、Claude Code CLI 是什么

Claude Code CLI 可以理解为一个运行在终端中的 AI 工程助手。它通常用于以下场景：

阅读陌生代码库，快速解释项目结构。
根据需求修改代码，并保持与现有风格一致。
运行测试、查看报错并定位问题。
生成提交说明、PR 描述和变更总结。
编写脚本、重构函数、补充测试用例。
通过 MCP 接入外部工具或内部系统。
通过 hooks 在工具调用前后执行自动检查。

与普通聊天机器人相比，Claude Code 的关键区别是"靠近代码执行环境"：它知道当前工作目录，可以调用受控工具，可以逐步完成任务，也可以在关键操作前请求确认。

二、安装与登录

2.1 安装前准备

建议先准备：

Node.js 环境。
一个可用的终端，例如 macOS Terminal、iTerm2、Windows Terminal、Linux shell。
可访问 Claude 或 Anthropic Console 的账号。
一个用于测试的本地项目目录。

2.2 安装 Claude Code

常见安装方式如下：

bash 复制代码

npm install -g @anthropic-ai/claude-code

安装完成后，可以检查命令是否可用：

bash 复制代码

claude --version

如果命令不存在，通常是 npm 全局 bin 路径没有加入 PATH。可以用下面命令查看 npm 全局路径：

bash 复制代码

npm bin -g

然后把对应路径加入 shell 配置文件，例如 ~/.zshrc 或 ~/.bashrc。

2.3 登录账号

首次运行可以直接输入：

bash 复制代码

claude

或者使用登录命令：

bash 复制代码

claude login

根据环境不同，可以选择 Claude.ai 账号登录，也可以使用 Anthropic Console/API 计费方式。团队环境中建议统一登录方式和权限策略，避免不同成员的运行行为不一致。

三、第一次使用 Claude Code

进入一个项目目录：

bash 复制代码

cd my-project
claude

启动后，你可以直接输入自然语言需求。例如：

text 复制代码

请帮我解释这个项目的目录结构，并指出入口文件在哪里。

或者：

text 复制代码

阅读登录相关代码，找出用户登录失败时错误提示是在哪里生成的。

Claude Code 会根据当前目录读取必要文件，必要时调用搜索工具，并给出解释。对于新项目，建议先让它做只读分析，不要一开始就要求大规模修改。

四、常用交互方式

4.1 让 Claude 解释代码

适合接手陌生项目：

text 复制代码

请按模块解释 src 目录下的主要职责，不要修改代码。

也可以指定文件：

text 复制代码

解释 src/auth/session.ts 的登录态管理逻辑，重点说明 token 是如何刷新和失效的。

4.2 让 Claude 修改代码

当需求明确时，可以直接描述目标：

text 复制代码

把用户设置页的邮箱校验改成必须包含 @ 和域名，并补充相关单元测试。

更好的写法是给出边界：

text 复制代码

只修改表单校验逻辑和对应测试，不要重构无关组件。

4.3 让 Claude 运行测试

可以要求它执行测试并根据结果修复：

text 复制代码

运行当前项目的测试。如果失败，请先解释失败原因，再做最小修改修复。

4.4 让 Claude 生成提交信息

当你完成改动后，可以让它总结：

text 复制代码

根据当前 git diff 生成一条简洁的 commit message，说明为什么修改。

如果你希望它直接提交，最好明确授权：

text 复制代码

请检查当前 diff，确认没有敏感文件后创建一个 git commit。

五、常用 Slash Commands

Claude Code 支持在交互界面中使用斜杠命令。常见命令包括：

命令	用途
/help	查看帮助信息
/clear	清空当前会话上下文，适合重新开始任务
/model	查看或切换模型相关设置
/login	登录账号
/logout	退出登录
/doctor	检查 Claude Code 安装和环境健康状态
/config	查看或调整配置
/mcp	管理 MCP 服务器
/hooks	查看 hooks 配置
/init	初始化项目级 Claude Code 配置

不同版本的 Claude Code 命令可能会变化，建议以本地 /help 和官方文档为准。

六、命令行常用参数

除了进入交互式界面，也可以在命令行里直接传入任务：

bash 复制代码

claude "解释这个仓库的测试结构"

常见参数类型包括：

参数	作用
--help	查看 CLI 帮助
--version	查看版本
--settings	指定额外 settings 配置
--mcp-config	指定 MCP 配置文件
--strict-mcp-config	只使用指定 MCP 配置，忽略其他 MCP 来源

示例：

bash 复制代码

claude --settings ./settings.json "检查当前项目有哪些测试命令"

对于团队项目，建议把重要配置放到项目级配置文件中，而不是只依赖个人全局配置。

七、CLAUDE.md：给项目写一份说明书

很多项目都有自己的目录结构、测试命令、代码风格和注意事项。与其每次都告诉 Claude，不如在项目中维护一个 CLAUDE.md 文件。

示例：

markdown 复制代码

# Project Guide for Claude

## Commands

- Install dependencies: npm install
- Run tests: npm test
- Run typecheck: npm run typecheck
- Start dev server: npm run dev

## Code Style

- Prefer TypeScript strict types.
- Do not introduce new dependencies unless necessary.
- Keep UI components small and focused.

## Testing

- Add unit tests for pure logic.
- For UI changes, verify the main flow manually.

这样 Claude Code 在处理任务时可以更好地遵循项目约定。

八、权限与安全机制

Claude Code 可以执行工具调用，因此权限边界非常重要。一般可以把操作分成几类：

操作类型	示例	建议策略
只读操作	读取文件、搜索代码、查看 git diff	通常可允许
本地可逆操作	编辑文件、运行测试、格式化代码	视项目情况允许
破坏性操作	删除文件、reset 分支、清理目录	必须确认
外部可见操作	push、发 PR、发布文章、调用线上 API	必须明确授权
敏感操作	读取密钥、修改权限、访问生产数据	默认拒绝或严格审批

实用建议：

不要把生产密钥放在项目目录中。
不要让 Agent 自动执行高风险命令。
在提交前检查 git diff。
对发布、推送、删除等动作保持人工确认。
用 hooks 或脚本阻止敏感文件被读取或提交。

九、settings.json 配置

Claude Code 支持通过 settings.json 进行配置。配置通常可以存在于用户级或项目级位置，用于控制权限、工具、hooks、模型和其他行为。

一个简化示例：

json 复制代码

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run typecheck)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Read(.env*)"
    ]
  }
}

注意：具体配置字段会随版本演进，实际项目中应以官方 settings 文档和本地 /config 显示为准。

十、MCP：把外部工具接入 Claude Code

MCP 全称是 Model Context Protocol，可以让 Claude Code 连接外部工具、数据源或服务。例如：

文件系统扩展。
数据库查询工具。
GitHub、Linear、Jira 等研发系统。
浏览器自动化工具。
内部知识库检索服务。

常见命令形式：

bash 复制代码

claude mcp add server-name -- command arg1 arg2

这里的 -- 用来分隔 Claude Code 自己的参数和 MCP server 的启动命令。例如：

bash 复制代码

claude mcp add my-tool -- node ./mcp-server.js

添加后可以通过：

bash 复制代码

claude mcp list

查看已配置的 MCP 服务。

MCP 的最佳实践：

一个 MCP server 只做清晰的职责。
对有副作用的工具做权限控制。
给工具返回结构化结果，减少模型误解。
团队项目使用项目级 MCP 配置，便于共享。

十一、Hooks：把规则变成自动化

Hooks 可以在 Claude Code 的生命周期事件中执行命令或检查逻辑。例如：

用户提交请求前做内容检查。
工具调用前拦截危险命令。
工具调用后记录日志。
会话结束时生成摘要。
文件修改后触发格式化或检查。

一个典型场景是阻止危险命令：

json 复制代码

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/block-dangerous-command.py"
          }
        ]
      }
    ]
  }
}

Hooks 很强大，但也要谨慎：

hook 脚本本身也可能有安全风险。
不要在 hook 中无提示地执行破坏性操作。
团队项目需要把 hook 行为写清楚，避免成员困惑。

十二、日常工作流示例

12.1 接手新仓库

text 复制代码

请只读分析当前仓库：说明技术栈、入口文件、测试命令、主要模块和潜在风险点。

12.2 修复 bug

text 复制代码

用户反馈登录后偶尔跳回登录页。请定位可能原因，先不要改代码，先给出排查结论。

确认方向后：

text 复制代码

按刚才的结论做最小修复，并补充测试。

12.3 增加功能

text 复制代码

给用户设置页增加手机号字段。要求：表单校验、保存接口参数、单元测试都要覆盖，不要改无关 UI。

12.4 代码审查

text 复制代码

请审查当前 git diff，重点关注安全问题、破坏兼容性的改动和测试遗漏。

12.5 发布前检查

text 复制代码

请运行 lint、typecheck 和测试；如果通过，总结本次变更和风险点。

十三、常见问题

13.1 Claude Code 会不会乱改文件？

它可以修改文件，但通常会通过工具调用和权限机制执行。建议在重要项目中保持 git 工作区干净，并在每次修改后查看 diff。

13.2 是否需要每次都复制代码给它？

不需要。Claude Code 可以在当前项目目录读取相关文件。你只需要清楚描述目标和约束。

13.3 它能不能自动提交和推送？

可以辅助生成提交，甚至执行 git 命令，但 push、发 PR、发布等外部可见操作建议明确授权后再执行。

13.4 为什么它有时需要我确认？

这是安全设计。涉及写文件、执行命令或外部操作时，确认机制可以避免误操作。

13.5 上下文太长怎么办？

可以使用 /clear 重新开始，或者让 Claude 先总结当前进展，再进入下一阶段。对于大型项目，最好把长期规则写入 CLAUDE.md。

十四、最佳实践清单

先让 Claude 做只读分析，再让它修改代码。
每次需求都说明范围：哪些能改，哪些不能改。
修改后要求它运行测试或说明无法测试的原因。
对删除、覆盖、push、发布等动作保持人工确认。
维护 CLAUDE.md，让项目规则长期可见。
使用 settings.json 管理权限和团队约定。
使用 MCP 接入必要工具，不要把所有能力塞进一个万能脚本。
使用 hooks 自动化安全检查和流程约束。
提交前查看 git diff，避免带入临时文件或密钥。
把 Claude Code 当作结对工程师，而不是完全无人值守的脚本。

十五、总结

Claude Code CLI 的核心价值，是把大模型能力带到开发者每天工作的终端和代码仓库中。它既能解释代码，也能修改代码；既能运行测试，也能通过 MCP 和 hooks 扩展到更复杂的工程流程。

对个人开发者来说，它可以提升阅读代码、修 bug、写测试和整理文档的效率。对团队来说，更重要的是通过 CLAUDE.md、settings.json、权限策略、MCP 和 hooks 建立统一的 AI 协作规范。

如果你刚开始使用 Claude Code，建议从三个动作开始：进入项目目录、让它只读分析项目、让它完成一个小而明确的修改。熟悉之后，再逐步接入测试、提交、MCP 和自动化流程。

参考资料

Claude Code CLI reference：https://docs.claude.com/en/docs/claude-code/cli-reference
Claude Code Slash commands：https://docs.claude.com/en/docs/claude-code/slash-commands
Claude Code Settings：https://docs.claude.com/en/docs/claude-code/settings
Claude Code MCP：https://docs.claude.com/en/docs/claude-code/mcp
Claude Code Hooks：https://docs.claude.com/en/docs/claude-code/hooks