Claude Code 完全指南：从首次安装到日常工作流

Claude Code 是 Anthropic 出品的具备 Agent 能力的编码工具——你用自然语言描述需求，它来改文件、跑命令、搜代码库、把功能交付出来。和纯聊天助手不同，它直接在你的仓库上操作，所以配置细节很关键。本指南带你走一遍安装 Claude Code、用 /init 给项目打底、写 CLAUDE.md 记忆文件、配置权限、你真正会用的命令，以及一个在真实代码库上经得起考验的日常工作流。

安装 Claude Code

Claude Code 是一个以 npm 包形式分发的终端工具。你需要先装好 Node.js（任意较新的 LTS 版本都行），然后：

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

这会全局安装 claude 命令。确认它在你的 PATH 上：

claude --version

首次启动时，claude 会引导你用 Anthropic 账号（或一个 API key，或受支持的 Bedrock / Vertex 后端）完成认证。认证完成后，进入项目目录，不带任何参数运行 claude 即可启动交互式会话。Claude Code 的设计是从仓库根目录运行，这样它能把整个项目读进上下文。

它不需要单独的 IDE 插件。Claude Code 在任何终端里都能用，也有针对 VS Code、JetBrains 这类编辑器的可选集成，可以从编辑器内启动会话。终端是它的主战场。

用 /init 给项目打底

在一个新项目里最值得跑的第一条命令是 /init。它让 Claude 探索你的代码库，生成一份 CLAUDE.md，把新贡献者需要知道的要点抓出来：构建和测试命令、目录布局、约定，以及任何值得知道的坑。产出的是一份草稿，你再把它删到真正有用的部分。

> /init

/init 跑完后，打开 CLAUDE.md，把任何错的或本来就显而易见的东西删掉。目标是短而准确的文件，而不是面面俱到的文件。一份好的 CLAUDE.md 大约两屏：怎么跑测试、入口在哪、Claude 写代码时要遵守的约定。其他都是每一轮都要烧 token 的噪音。

/init 不是强制的。你可以手写 CLAUDE.md、跳过草稿。但在新项目里跑一次是最快的启动方式，因为 Claude 读的是真实代码，而不是瞎猜。

CLAUDE.md 记忆文件

CLAUDE.md 是 Claude Code 里最重要的配置文件。它是一个纯 Markdown 文件，Claude 在每次会话开始时读取它，所以里面的任何东西都成了持久上下文。把它当成你交给一个从没见过这个代码库的新同事的说明。

Claude Code 从几个地方加载 CLAUDE.md，全部合并：

• 项目记忆 —— 仓库根目录的 ./CLAUDE.md（以及子目录里嵌套的 CLAUDE.md，当 Claude 在那个目录工作时加载）。提交到 git，团队共享。
• 用户记忆 —— ~/.claude/CLAUDE.md，跨所有项目的个人偏好。
• 本地覆盖 —— ./CLAUDE.local.md，被 gitignore 掉，用于机器特定或私密的笔记。

随时运行 /memory，可以查看当前会话到底加载了哪些文件。当 Claude 表现得像忘了什么时，这个命令非常有用——通常是你编辑的那个文件并不在已加载列表里。

CLAUDE.md 里该放什么？高价值的内容是：构建和测试命令、代码风格和命名约定、新代码该放哪、怎么跑 linter、以及任何项目特定的规则（「绝不要改生成的 dist 目录」「总要先加一条 changelog」）。保持简短、用祈使句。又长又散的 CLAUDE.md，模型会像人一样跳着读。

权限：allow 和 deny

因为 Claude Code 会跑命令、改文件，权限是你防止它做你不想做的事的手段。Claude Code 会把每次工具调用拿去跟你设置里的规则比对，并在第一次尝试规则没覆盖的动作时征求批准。

在一个会话里可以在四种权限模式间切换：

• default —— 在可能有破坏性的动作前征求批准（正常模式）。
• acceptEdits —— 自动批准文件编辑，命令仍会问。
• plan —— 只读探索；Claude 提出方案但不做改动。
• bypassPermissions —— 跳过所有批准提示（谨慎使用，通常只在沙箱环境）。

持久规则放在 settings.json 里（项目级在 .claude/settings.json，用户级在 ~/.claude/settings.json）的 permissions.allow 和 permissions.deny 下：

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint)",
      "Read(./src/**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Read(./secrets/**)"
    ]
  }
}

两条实践中重要的规则：deny 永远优先于 allow（即使匹配了 allow，被 deny 的动作仍会被阻止），以及 hooks 在规则之前运行（PreToolUse hook 可以无视规则阻止或批准一次调用）。Read 和 Edit 的 deny 规则还会延伸到 Claude 在 Bash 里识别的文件命令——cat、head、tail、sed——所以你不会因为走 shell 而意外读到一个密钥文件。

调权限的目标是在「批准疲劳」和「完全放手」之间找平衡。一套典型设置：允许测试和 lint 命令、允许读源码树、拒绝任何碰密钥或强推的操作，其余的都留在默认的询问上。

你真正会用的命令

Claude Code 有一组用于会话控制的斜杠命令。日常会用到的有：

• /init —— 生成 CLAUDE.md 草稿。
• /memory —— 显示当前加载了哪些记忆文件。
• /permissions —— 查看和编辑当前生效的权限规则。
• /clear —— 重置对话上下文，保留同一个会话。
• /compact —— 把到目前为止的对话总结一下，腾出上下文窗口。
• /mcp —— 列出已连接的 MCP 服务器及其工具。
• /model —— 切换底层模型。
• /help —— 列出所有可用命令。

斜杠命令之外，主要的交互就是用自然语言打字提需求。你也可以管道输入：cat error.log | claude -p "这个错误是什么原因？" 会让 Claude 非交互地处理管道内容并打印响应，这是把 Claude Code 接进脚本和 CI 的方式。

一个经得起考验的日常工作流

在真实代码库上效果较好的工作流：

1. 从仓库根目录开始，这样 Claude 能把整个项目纳入视野。运行 /memory 确认正确的 CLAUDE.md 已加载。
2. 先用 plan 模式探索。 对任何非琐碎任务，先用 plan 模式，让 Claude 读代码、提方案，再动手改文件。审一遍方案、调整，然后切回 default 模式执行。
3. 改动的同一轮要测试。 当你提一个功能或修复需求时，在同一轮里把测试也要了。改动和测试一起写，Claude Code 才最靠谱。
4. 让它跑测试。 允许 npm test（或你的等价命令），这样 Claude 能验证自己的改动。Agent 自己确认过通过测试套件的改动，远比没确认的可信。
5. 接受前审每个 diff。 机械改动用 acceptEdits 提速，但遇到微妙之处就切回 default 模式。模型写的代码得你来维护。
6. 小块提交。 让 Claude 把改动按逻辑分组暂存并描述，而不是一个大提交。如果你在 CLAUDE.md 里写明了格式，Conventional Commits 风格的消息会很干净。

贯穿所有这些的模式：决策上保持人在环里，让 Claude 干打字的活。Claude Code 在机械工作上很快——读目录、写样板改动、跑测试、重生 fixture——而在无人监督下做产品判断时最弱。扬长避短。

用技能、命令和 hooks 做定制

基础打通后，定制层是 Claude Code 在特定项目上变强大的地方。

• 技能（Skills） 把可复用的流程打包成一个按需加载的 SKILL.md——详见我们的 Claude Code Skills 指南。
• 自定义斜杠命令 放在 .claude/commands/ 下，是 Markdown 提示词文件；输入 /project:你的命令 即可运行。
• Hooks 在生命周期事件（PreToolUse、PostToolUse、Stop）上跑脚本，用于像「每次编辑后自动格式化」或「阻止危险命令」这类事。

它们可以组合。一套成熟的配置可能有：一个用于代码审查清单的技能、一个用于部署流程的斜杠命令、一个在 Claude 每次写文件后跑格式化器的 PostToolUse hook。回报是 Claude 会按你团队期望的方式行事，而你不必每个会话都重新解释一遍。

常见问题

什么是 CLAUDE.md，怎么创建？

CLAUDE.md 是一个纯 Markdown 文件，Claude Code 在每次会话开始时读取它，使其内容成为持久上下文。最快的创建方式是在项目根目录运行 /init——Claude 会探索代码库，生成一份草稿，涵盖构建命令、布局和约定，你再删到有用的部分。你也可以手写。随时运行 /memory 可查看当前加载了哪些 CLAUDE.md 文件。

Claude Code 有哪四种权限模式？

default 在可能有破坏性的动作前征求批准；acceptEdits 自动批准文件编辑但命令仍会问；plan 是只读探索，Claude 提方案但不改东西；bypassPermissions 跳过所有批准提示。你可以在一个会话里切换，持久的 allow/deny 规则放在 settings.json 里。

allow 和 deny 权限规则如何相互作用？

deny 永远优先。如果一个动作同时匹配 allow 和 deny 规则，它会被阻止。Read 和 Edit 的 deny 规则还会延伸到 Claude 在 Bash 里识别的文件命令，如 cat、head、tail、sed，所以你不会因为走 shell 而读到一个被拒绝的文件。hooks 在规则之前运行，所以 PreToolUse hook 可以无视权限规则阻止或批准一次调用。

我能在脚本或 CI 里非交互地用 Claude Code 吗？

能。-p 标志让 Claude 非交互地处理管道输入并打印响应，例如 cat error.log | claude -p "这个错误是什么原因？"。这是把 Claude Code 接进 shell 脚本、git hook 和 CI 流水线的方式。要用到生产自动化，Agent SDK 提供同样的能力，且是可编程的。

官方参考资料

• Claude Code 概览
• Claude Code 记忆管理（CLAUDE.md）
• Claude Code 权限
• Claude Code CLI 参考
• Anthropic 官方 Claude Code

本文基于截至 2026 年 7 月的公开信息，相关 API 可能演进。