Claude Code: Best practices for agentic coding

本文翻译并润色自 Anthropic 官网，旨在介绍在各种代码库、编程语言和环境中高效使用 Claude Code 的技巧与实践。

我们最近发布了 Claude Code，一款智能编程命令行工具。作为一个研究项目，Claude Code 为 Anthropic 的工程师和研究人员提供了一种更原生的方式，将 Claude 无缝集成到他们的编程工作流中。

Claude Code 的设计刻意保持底层和灵活，提供近乎原始模型的访问能力，而不强制用户遵循特定的工作流。这种设计理念创造了一个强大、可定制、可脚本化且安全的工具。然而，这种灵感活性也意味着，对于初次接触智能编程工具的工程师来说，可能存在一定的学习曲线，直到他们摸索出自己的最佳实践。

本文概述了 Anthropic 内部团队以及外部工程师在各种代码库、语言和环境中证明行之有效的通用模式。这份清单并非一成不变或放之四海而皆准；请将这些建议视为一个起点，我们鼓励您大胆实验，找到最适合自己的方法！

想要了解更多信息？我们在 claude.ai/code 上的综合文档涵盖了本文提到的所有功能，并提供了更多示例、实现细节和高级技巧。

1. 自定义你的配置

Claude Code 是一款会自动将上下文加载到提示中的智能编程助手。这种上下文收集虽然会消耗时间和 token，但你可以通过优化环境来提升其效率。

a. 创建 CLAUDE.md 文件

CLAUDE.md 是一个特殊文件，Claude 在开启对话时会自动将其内容加载到上下文中。这使其成为记录以下信息的理想场所：

• 常用的 shell 命令
• 项目核心文件和工具函数
• 代码风格指南
• 测试说明
• 仓库规范（如分支命名、merge vs. rebase 策略等）
• 开发环境设置（如 pyenv use、可用的编译器等）
• 项目特有的注意事项或警告
• 其他你希望 Claude 记住的信息

CLAUDE.md 文件没有固定的格式要求，我们建议保持其简洁和易读。例如：

# Shell 命令
- `npm run build`: 构建项目
- `npm run typecheck`: 运行类型检查器

# 代码风格
- 使用 ES 模块 (`import`/`export`) 语法，而非 CommonJS (`require`)
- 尽可能解构导入 (例如 `import { foo } from 'bar'`)

# 工作流
- 完成一系列代码变更后，务必运行类型检查
- 出于性能考虑，优先运行单个测试，而不是整个测试套件

你可以在多个位置放置 CLAUDE.md 文件：

• 仓库根目录，或任何你运行 claude 的位置（最常见用法）。将其命名为 CLAUDE.md 并提交到 Git，以便跨会话和团队共享（推荐）；或命名为 CLAUDE.local.md 并加入 .gitignore。
• 任何父目录。这在单体仓库（monorepo）中尤其有用。例如，你从 root/foo 运行 claude，同时在 root/CLAUDE.md 和 root/foo/CLAUDE.md 中都存在配置文件，两者都会被加载。
• 任何子目录。这是上述的反向操作，当你处理子目录中的文件时，Claude 会按需加载该子目录下的 CLAUDE.md 文件。
• 你的主目录 (~/.claude/CLAUDE.md)，其中的配置会应用于所有 claude 会话。

当你运行 /init 命令时，Claude 会自动为你生成一个 CLAUDE.md 文件。

b. 调优你的 CLAUDE.md 文件

你的 CLAUDE.md 文件是 Claude 提示词的一部分，因此应当像对待任何高频使用的提示词一样去优化它。一个常见的错误是添加大量内容后，却不迭代验证其有效性。花些时间进行实验，找到能让模型最有效遵循指令的表达方式。

你可以手动向 CLAUDE.md 添加内容，或者按下 # 键向 Claude 发出指令，它会自动将该指令整合到相关的 CLAUDE.md 中。许多工程师在编码时会频繁使用 # 来记录命令、文件和风格指南，然后在提交时一并包含 CLAUDE.md 的更改，以便团队成员共享。

在 Anthropic，我们偶尔会用提示词优化器来改进 CLAUDE.md 文件，并经常调整指令（例如使用 “IMPORTANT” 或 “YOU MUST” 来强调）以提高模型的遵循度。

c. 管理 Claude 的工具许可清单

默认情况下，Claude Code 会对任何可能修改你系统的操作请求授权：文件写入、许多 shell 命令、MCP 工具等。我们刻意采取这种保守的设计，以优先保障安全性。你可以自定义许可清单，允许你确信安全的工具，或是那些潜在不安全但操作易于撤销的工具（如文件编辑、git commit）。

有四种方法可以管理许可的工具：

1. 在会话期间，当 Claude 请求权限时选择“始终允许”。
2. 启动 Claude Code 后，使用 /permissions 命令添加或移除许可清单中的工具。例如，你可以添加 Edit 来始终允许文件编辑，Bash(git commit:*) 来允许 git 提交，或 mcp__puppeteer__puppeteer_navigate 来允许使用 Puppeteer MCP 服务器进行导航。
3. 手动编辑你的 .claude/settings.json 或 ~/.claude.json 文件（我们建议将前者提交到版本控制中与团队共享）。
4. 使用 --allowedTools CLI 标志为特定会话授予权限。

d. 如果使用 GitHub，请安装 gh CLI

Claude 知道如何使用 gh CLI 与 GitHub 交互，例如创建 issue、开启 pull request、阅读评论等。如果未安装 gh，Claude 仍可尝试使用 GitHub API 或 MCP 服务器（如果你已配置）。

2. 为 Claude 提供更多工具

Claude 可以访问你的 shell 环境，你可以像为自己一样为它构建便利的脚本和函数库。它还可以通过 MCP 和 REST API 利用更复杂的工具。

a. 使用 Claude 与 bash 工具

Claude Code 继承了你的 shell 环境，使其能够访问你所有的工具。虽然 Claude 熟悉如 Unix 工具和 gh 等常用程序，但若不加说明，它无法获知你自定义的工具。你可以：

• 告诉 Claude 工具的名称和用法示例。
• 告诉 Claude 运行 --help 来查看工具的文档。
• 在 CLAUDE.md 中记录常用的工具。

b. 使用 Claude 与 MCP

Claude Code 既可作为 MCP 服务器，也可作为 MCP 客户端。作为客户端，它可以通过三种方式连接到任意数量的 MCP 服务器以访问其工具：

• 在项目配置中（在该目录运行 Claude Code 时可用）。
• 在全局配置中（在所有项目中可用）。
• 在已提交到版本库的 .mcp.json 文件中（对所有使用你代码库的人可用）。例如，你可以将 Puppeteer 和 Sentry 服务器添加到 .mcp.json，这样团队中的每位工程师都能开箱即用。

使用 MCP 时，通过 --mcp-debug 标志启动 Claude 有助于识别配置问题。

c. 使用自定义斜杠命令

对于重复性的工作流——如调试循环、日志分析等——可以将提示模板存储在 .claude/commands 文件夹内的 Markdown 文件中。当你输入 / 时，这些命令就会出现在斜杠命令菜单中。你可以将这些命令提交到 Git，以便团队其他成员使用。

自定义斜杠命令可以包含特殊关键字 $ARGUMENTS，以接收从命令调用中传递的参数。

例如，这是一个可用于自动拉取并修复 GitHub issue 的斜杠命令：

请分析并修复 GitHub issue：`$ARGUMENTS`。

遵循以下步骤：

1. 使用 `gh issue view` 获取 issue 详情。
2. 理解 issue 中描述的问题。
3. 搜索代码库以定位相关文件。
4. 实施必要的更改以修复 issue。
5. 编写并运行测试以验证修复效果。
6. 确保代码通过 linting 和类型检查。
7. 撰写描述清晰的提交信息。
8. 推送代码并创建 Pull Request。

请记住，所有 GitHub 相关任务都应使用 GitHub CLI (`gh`)。

将上述内容保存到 .claude/commands/fix-github-issue.md，即可在 Claude Code 中通过 /project:fix-github-issue 命令使用它。例如，你可以运行 /project:fix-github-issue 1234 来让 Claude 修复 issue #1234。同样，你也可以将个人命令添加到 ~/.claude/commands 文件夹，以便在所有会话中使用。

3. 尝试常见工作流

Claude Code 不强制特定的工作流，让你能灵活地按自己的方式工作。在这种灵活性中，我们的用户社区涌现出了几种成功的模式：

a. 探索、规划、编码、提交

这种多功能工作流适用于许多场景：

1. 探索：要求 Claude 阅读相关文件、图片或 URL。你可以给出宽泛的指引（“阅读处理日志的文件”）或特定文件名（“阅读 logging.py”），但明确告诉它暂时不要编写任何代码。
   • 在这一步，尤其对于复杂问题，应重点考虑使用子代理（sub-agents）。让 Claude 使用子代理来验证细节或研究特定问题，通常能在不显著牺牲效率的前提下，保留宝贵的上下文空间。
2. 规划：要求 Claude 制定解决问题的计划。我们建议使用 “think” 一词来触发其扩展思考模式，这会给予 Claude 额外的计算时间来更周全地评估方案。特定的短语对应着递增的思考预算：“think” < “think hard” < “think harder” < “ultrathink”。
   • 如果计划看起来合理，你可以让 Claude 将其记录到文档或 GitHub issue 中。这样，如果后续的实现不理想，你可以回退到这个规划好的节点。
3. 编码：要求 Claude 在代码中实现其解决方案。这也是一个很好的时机，要求它在实现过程中明确验证其方案的合理性。
4. 提交：要求 Claude 提交结果并创建 pull request。如果需要，也可以让 Claude 更新相关的 README 或变更日志，以解释它所做的更改。

步骤 #1 和 #2 至关重要。没有它们，Claude 倾向于直接跳到编码。虽然有时这正是你想要的，但对于需要深入思考的问题，先让 Claude 研究和规划可以显著提升最终结果的质量。

b. 编写测试，提交；编码，迭代，提交

这是 Anthropic 内部最推崇的工作流之一，尤其适用于那些可以通过单元、集成或端到端测试轻松验证的变更。测试驱动开发（TDD）在智能编程时代变得更加强大：

1. 编写测试：要求 Claude 基于预期的输入/输出编写测试。明确指出你正在进行 TDD，这样它就不会为尚不存在的功能创建模拟实现。
2. 验证失败：告诉 Claude 运行测试并确认它们如预期般失败。在此阶段，明确告诉它不要编写任何实现代码通常很有帮助。
3. 提交测试：当你对测试满意时，要求 Claude 提交这些测试。
4. 编码实现：要求 Claude 编写能通过测试的代码，并指示它不要修改测试本身。告诉 Claude 持续迭代，直到所有测试通过。Claude 通常需要几次迭代（编写代码、运行测试、调整代码、再次测试）才能成功。
   • 在此阶段，可以要求它使用独立的子代理来验证实现方案是否对测试用例产生了过拟合。
5. 提交代码：一旦你对更改满意，要求 Claude 提交代码。

当有明确的迭代目标时（如视觉模型、测试用例或其他输出），Claude 的表现最佳。通过提供预期的输出，Claude 可以进行修改、评估结果，并逐步改进直至成功。

c. 编写代码，截图比对，迭代

与测试工作流类似，你可以为 Claude 提供视觉目标：

1. 提供截图工具：为 Claude 提供一种截取浏览器屏幕的方法（例如，使用 Puppeteer MCP 服务器、iOS 模拟器 MCP 服务器，或手动将截图复制粘贴给 Claude）。
2. 提供视觉参考：通过复制粘贴、拖放图片，或提供图片文件路径，为 Claude 提供一个视觉参考图。
3. 迭代实现：要求 Claude 在代码中实现该设计，截取结果图，并与参考图进行比对，不断迭代直至两者匹配。
4. 提交：当你满意时，要求 Claude 提交代码。

如同人类一样，Claude 的输出通过迭代会显著改善。虽然第一个版本可能不错，但经过 2-3 次迭代后，结果通常会好得多。为 Claude 提供查看其工作成果的工具，以获得最佳结果。

d. 安全的 YOLO 模式

你可以使用 claude --dangerously-skip-permissions 跳过所有权限检查，让 Claude 在无人监督的情况下不间断地工作直至任务完成。此模式非常适用于修复 lint 错误或生成样板代码等任务。

警告：让 Claude 运行任意命令存在风险，可能导致数据丢失、系统损坏，甚至数据泄露（例如，通过提示注入攻击）。为了将风险降至最低，请在没有网络访问的容器中使用 --dangerously-skip-permissions。你可以参照这个 Docker Dev Containers 实现来操作。

e. 代码库问答

当接触一个新代码库时，使用 Claude Code 进行学习和探索。你可以像与另一位工程师结对编程时那样向 Claude 提问。Claude 可以智能地搜索代码库来回答各种问题，例如：

• “日志记录系统是如何工作的？”
• “我应该如何创建一个新的 API 端点？”
• “foo.rs 第 134 行的 async move { ... } 是做什么的？”
• “CustomerOnboardingFlowImpl 处理了哪些边缘情况？”
• “为什么我们在第 333 行调用 foo() 而不是 bar()？”
• “baz.py 第 334 行的代码在 Java 中等价于什么？”

在 Anthropic，以这种方式使用 Claude Code 已成为我们的核心入职流程，它显著缩短了新成员的上手时间，并减轻了团队其他工程师的指导负担。不需要特殊的提示！只需提问，Claude 就会探索代码库为你找到答案。

f. 使用 Claude 与 git 交互

Claude 可以高效地处理许多 git 操作。许多 Anthropic 工程师使用 Claude 来处理超过 90% 的 git 交互：

• 搜索 git 历史来回答诸如“v1.2.3 版本包含了哪些更改？”、“谁负责这个特定功能？”或“为什么这个 API 是这样设计的？”等问题。明确提示 Claude 查看 git 历史记录有助于回答这类查询。
• 编写提交信息。Claude 会自动查看你的更改和最近的历史记录，并结合所有相关上下文来撰写信息。
• 处理复杂的 git 操作，如恢复文件、解决 rebase 冲突以及比较和移植补丁。

g. 使用 Claude 与 GitHub 交互

Claude Code 可以管理许多 GitHub 交互：

• 创建 pull request：Claude 能理解简写 “pr”，并会基于代码差异和上下文生成合适的提交信息。
• 修复 Code Review 评论：只需告诉它修复你 PR 上的某条评论（可选择性地给予更具体的指令），并在完成后推送回 PR 分支。
• 修复失败的构建或 linter 警告。
• 分类和分级 issue：通过要求 Claude 循环处理开放的 GitHub issue 来完成。

这让你无需记住 gh 的命令行语法，同时还能自动化处理日常任务。

h. 使用 Claude 处理 Jupyter Notebooks

Anthropic 的研究人员和数据科学家使用 Claude Code 来读写 Jupyter Notebooks。Claude 能够解释输出，包括图像，提供了一种快速探索和与数据交互的方式。虽然没有必需的工作流，但我们推荐在 VS Code 中并排打开 Claude Code 和 .ipynb 文件。

你还可以要求 Claude 在向同事展示之前，对你的 Jupyter notebook 进行清理或美化。明确告诉它要使 notebook 或其数据可视化“更具美感”，这有助于提醒它优化的目标是提升人类的阅读体验。

4. 优化你的工作流

以下建议适用于所有工作流：

a. 在指令中保持具体

指令越具体，Claude Code 的成功率就越高，尤其是在首次尝试时。预先给出明确的指示，可以减少后续路线修正的需要。

Claude 能够推断意图，但它不会读心。具体性才能更好地确保结果符合预期。

b. 给 Claude 图像

Claude 可以通过多种方式出色地处理图像和图表：

• 粘贴截图（专业提示：在 macOS 中按 cmd+ctrl+shift+4 将截图存入剪贴板，然后按 ctrl+v 粘贴。请注意，这里不是 macOS 常用的 cmd+v，且该快捷键在远程连接时无效。）
• 直接将图像拖放到提示输入区。
• 提供图像的文件路径。

这在 UI 开发中将设计稿作为参考，或在分析调试时使用可视化图表时尤其有用。即便你没有提供视觉材料，明确告诉 Claude 最终结果需要“视觉上吸引人”也是有帮助的。

c. 提及你希望 Claude 查看或处理的文件

使用 tab 键自动补全，可以快速引用仓库中任何位置的文件或文件夹，帮助 Claude 找到或更新正确的资源。

d. 给 Claude URL

在提示旁边粘贴特定的 URL，Claude 就可以获取并阅读其内容。为了避免对同一域名（如 docs.foo.com）重复授权，可以使用 /permissions 将该域名添加到你的许可清单中。

e. 尽早并经常进行路线修正

虽然自动接受模式（auto-accept mode）可以让 Claude 自主工作，但当你作为一名积极的协作者，主动引导 Claude 的思路时，通常会得到更好的结果。你可以在开始时就向 Claude 详尽地解释任务，也可以在任何时候纠正它的路线。

这四个工具有助于进行路线修正：

1. 在编码前要求 Claude 制定计划。明确告诉它，在你确认计划可行之前不要开始编码。
2. 在任何阶段（思考、工具调用、文件编辑）按下 Escape 键来中断 Claude，同时保留当前上下文，以便你重定向或补充指令。
3. 双击 Escape 键可以回溯历史记录，编辑之前的提示，并探索不同的方向。你可以反复编辑提示，直到获得满意的结果。
4. 要求 Claude 撤销更改，这通常与选项 #2 结合使用，以尝试不同的方法。

虽然 Claude Code 偶尔能在第一次尝试时就完美解决问题，但善用这些修正工具通常能更快地产生更优的解决方案。

f. 使用 /clear 保持上下文集中

在长时间的会话中，Claude 的上下文窗口可能会被不相关的对话、文件内容和命令填满。这可能会降低其表现，有时还会分散它的注意力。在不同任务之间，请经常使用 /clear 命令来重置上下文窗口。

g. 对复杂工作流使用清单和草稿本

对于具有多个步骤或需要详尽解决方案的大型任务——如代码迁移、修复大量 lint 错误或运行复杂的构建脚本——可以让 Claude 使用一个 Markdown 文件（甚至是一个 GitHub issue）作为清单和工作草稿本，以提升其表现。

例如，要修复大量的 lint 问题，你可以：

1. 告诉 Claude 运行 lint 命令，并将所有错误（包括文件名和行号）写入一个 Markdown 清单。
2. 指示 Claude 逐一解决清单上的问题，每修复一个便进行验证，然后再处理下一个。

h. 将数据传递给 Claude

有几种方法可以向 Claude 提供数据：

• 直接复制粘贴到提示中（最常用）。
• 通过管道 (pipe) 传入 Claude Code（例如 cat foo.txt | claude），尤其适用于日志、CSV 和大数据集。
• 告诉 Claude 通过 bash 命令、MCP 工具或自定义斜杠命令来拉取数据。
• 要求 Claude 读取文件或获取 URL（也适用于图像）。

大多数会话会结合使用这些方法。例如，你可以通过管道传入一个日志文件，然后让 Claude 使用工具拉取额外的上下文来调试该日志。

5. 使用无头模式自动化你的基础设施

Claude Code 包含一个用于非交互式场景（如 CI、预提交钩子、构建脚本和自动化任务）的无头模式。使用带提示的 -p 标志启用无头模式，并使用 --output-format stream-json 获取流式 JSON 输出。

注意：无头模式的状态不会在会话间持久化，你必须在每次调用时触发它。

a. 使用 Claude 进行 issue 分类

无头模式可以为由 GitHub 事件触发的自动化提供动力，例如当你的仓库中创建新 issue 时。公共的 Claude Code 仓库就使用 Claude 来检查新 issue 并分配适当的标签。

b. 使用 Claude 作为 linter

Claude Code 可以提供超越传统 linting 工具的代码审查，识别诸如拼写错误、过时的注释、有误导性的函数或变量名等主观问题。

6. 使用多 Claude 工作流提升效率

除独立使用外，一些最强大的应用场景涉及并行运行多个 Claude 实例：

a. 让一个 Claude 编写代码；使用另一个 Claude 验证

一个简单而有效的方法是：让一个 Claude 实例编写代码，同时让另一个实例审查或测试它。类似于与多位工程师协作，有时独立的上下文是有益的：

1. 使用一个 Claude 实例编写代码。
2. 运行 /clear 或在另一个终端中启动第二个 Claude 实例。
3. 让第二个实例审查第一个实例的工作。
4. 启动第三个实例（或再次 /clear），让它阅读代码和审查反馈。
5. 让这个实例根据反馈编辑代码。

你也可以对测试采取类似的方法：让一个 Claude 编写测试，然后让另一个编写代码以通过这些测试。你甚至可以通过给它们分配独立的草稿本文件，并告诉它们各自读写哪个文件，来实现 Claude 实例间的通信。

这种职责分离通常比让单个 Claude 处理所有事情产生更好的结果。

b. 拥有你的仓库的多个检出

许多 Anthropic 工程师的做法是，与其等待 Claude 完成每一步，不如：

1. 在不同的目录下创建 3-4 个独立的 git 工作区（checkout）。
2. 在不同的终端标签页中打开每个目录。
3. 在每个目录中启动一个 Claude 实例来执行不同的任务。
4. 循环检查每个实例的进度并批准/拒绝权限请求。

c. 使用 git worktree

这种方法对于处理多个独立任务非常出色，是多个检出（checkout）的轻量级替代方案。git worktree 允许你从同一个仓库将多个分支检出到不同的目录中。每个 worktree 都有自己独立的工作目录，同时共享相同的 Git 历史。

使用 git worktree，你可以在项目的不同部分同时运行多个 Claude 会话，每个会话专注于其独立的任务。例如，你可以让一个 Claude 重构认证系统，而另一个构建一个完全不相关的数据可视化组件。由于任务不重叠，每个 Claude 都可以全速工作，无需等待对方或处理合并冲突。

1. 创建 worktree：git worktree add ../project-feature-a feature-a
2. 在 worktree 中启动 Claude：cd ../project-feature-a && claude
3. 根据需要创建更多 worktree（在新的终端标签页中重复步骤 1-2）。

一些提示：

• 使用一致的命名约定。
• 为每个 worktree 维护一个独立的终端标签页。
• 如果你在 Mac 上使用 iTerm2，可以设置当 Claude 需要你关注时的通知。
• 为不同的 worktree 使用独立的 IDE 窗口。
• 完成后清理：git worktree remove ../project-feature-a。

d. 使用带有自定义工具的无头模式

claude -p（无头模式）能以编程方式将 Claude Code 集成到更大的工作流中，同时利用其内置工具和系统提示。使用无头模式主要有两种模式：

1. 扇出模式，用于处理大规模迁移或分析（例如，分析数百个日志的情绪或数千个 CSV 文件）：
   • 让 Claude 编写一个脚本来生成任务列表。例如，生成一个包含 2000 个需要从框架 A 迁移到框架 B 的文件列表。
   • 循环遍历任务列表，为每个任务以编程方式调用 Claude，并赋予它一个任务和一组可用的工具。例如：claude -p "将 foo.py 从 React 迁移到 Vue。完成后，如果成功必须返回字符串 OK，如果失败则返回 FAIL。" --allowedTools Edit Bash(git commit:*)
   • 多次运行脚本并优化你的提示，以获得期望的结果。
2. 流水线模式，将 Claude 集成到现有的数据/处理流程中：
   • 调用 claude -p "<你的提示>" --json | your_command，其中 your_command 是你处理流程的下一步。
   • JSON 输出（可选）有助于结构化数据，简化自动化处理。

对于这两种用例，使用 --verbose 标志来调试 Claude 的调用可能会很有帮助。我们通常建议在生产环境中关闭详细模式，以获得更简洁的输出。