跳到正文
实时
Anthropic Research·· 2025-04-18精选62

Anthropic 发布 Claude Code 智能体编码最佳实践

Claude Code: Best practices for agentic coding

要点速览

Anthropic 发布 Claude Code 智能体编码最佳实践，覆盖 CLAUDE.md 配置、工具权限管理、MCP 接入、常见工作流与多 Claude 并行等做法。文中建议先用子智能体探索和规划再写代码，并给出测试驱动、截图迭代、无头模式自动化等具体流程。该文已迁移至官方文档，原博客不再维护。

Why it matters

Anthropic 官方系统整理了 Claude Code 的配置、工作流与多实例并行方法，可作为搭建智能体编码流程的参考。

正文 · AI 翻译

  • 2026年1月26日

    Claude Code最佳实践已迁移至文档

    这篇博客不再维护。如需获取最新的Claude Code最佳实践，请参考官方文档（https://code.claude.com/docs/en/best-practices），该文档会随着Claude Code的演进而保持更新。

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

Claude Code有意设计得低级且不带有偏见，提供接近原始模型访问的方式，而不会强制特定的工作流程。这种设计理念创造了一个灵活、可定制、可脚本化且安全的强大工具。虽然功能强大，但这种灵活性对于刚开始使用代理编码工具的工程师来说，至少在形成他们自己的最佳实践之前，会带来一个学习曲线。

本文概述了一些经过验证的通用模式，这些模式对Anthropic的内部团队以及使用Claude Code的外部工程师在各种代码库、语言和环境中都有效。列表中的任何内容都不是固定不变的，也不是普遍适用的；请将这些建议视为起点。我们鼓励你进行实验，找到最适合你的方法！

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

1. 自定义你的设置

Claude Code是一个代理编码助手，它会自动将上下文拉入提示中。这种上下文收集会消耗时间和token，但你可以通过环境调优来优化它。

a. 创建CLAUDE.md文件

CLAUDE.md是一个特殊文件，Claude在开始对话时会自动将其拉入上下文中。这使得它成为记录以下内容的理想场所：

  • 常见的bash命令
  • 核心文件和实用函数
  • 代码风格指南
  • 测试说明
  • 仓库礼仪（例如，分支命名、合并与变基等）
  • 开发者环境设置（例如，pyenv use，哪些编译器可用）
  • 项目特有的任何意外行为或警告
  • 你想让Claude记住的其他信息

CLAUDE.md文件没有要求的格式。我们建议保持它们简洁且易于人类阅读。例如：

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

  • 你的仓库根目录，或者你运行claude的位置（最常见的用法）。将其命名为CLAUDE.md并提交到git，以便你可以在会话之间共享它并与你的团队共享（推荐），或者将其命名为CLAUDE.local.md并.gitignore它
  • 你运行claude的任何父目录。这对于单仓库最有用，你可能会从root/foo运行claude，并且在root/CLAUDE.md和root/foo/CLAUDE.md中都有CLAUDE.md文件。这两者都会被自动拉入上下文中
  • 你运行claude的任何子目录。这是上述内容的逆操作，在这种情况下，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 会请求任何可能修改您系统的操作的权限：文件写入、许多 bash 命令、MCP 工具等。我们故意设计了 Claude Code 这种保守的方法来优先考虑安全性。您可以自定义允许列表，以允许您知道是安全的附加工具，或允许容易撤销的潜在不安全工具（例如，文件编辑、git commit）。

管理允许工具有四种方法：

  • 在会话期间提示时选择 "始终允许"。
  • 在启动 Claude Code 后使用 /permissions 命令向允许列表中添加或删除工具。例如，您可以添加 Edit 以始终允许文件编辑，Bash(git commit:*) 以允许 git 提交，或 mcp__puppeteer__puppeteer_navigate 以允许使用 Puppeteer MCP 服务器进行导航。
  • 手动编辑您的 .claude/settings.json 或 ~/.claude.json（我们建议将前者提交到源代码控制以便与您的团队共享）.
  • 使用 --allowedTools CLI 标志进行会话特定的权限设置。

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

Claude 知道如何使用 gh CLI 与 GitHub 交互，用于创建问题、打开拉取请求、读取评论等。如果没有安装 gh，Claude 仍然可以使用 GitHub API 或 MCP 服务器（如果您已安装）。

2. 给 Claude 更多工具

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

a. 使用 Claude 与 bash 工具

Claude Code 继承了您的 bash 环境，使其可以访问所有您的工具。虽然 Claude 知道常见的实用工具，如 unix 工具和 gh，但如果未经说明，它不会知道您的自定义 bash 工具：

  1. 告诉 Claude 工具名称及使用示例
  2. 告诉 Claude 运行 --help 以查看工具文档
  3. 在 CLAUDE.md 中记录常用工具

b. 使用 Claude 与 MCP

Claude Code 充当 MCP 服务器和客户端。作为客户端，它可以连接到任意数量的 MCP 服务器，以三种方式访问它们的工具：

  • 在项目配置中（在运行 Claude Code 的该目录中可用）
  • 在全局配置中（在所有项目中可用）
  • 在提交的 .mcp.json 文件中（可供您代码库中的任何人使用）。例如，您可以将 Puppeteer 和 Sentry 服务器添加到您的 .mcp.json 中，以便您的每个工程师在处理您的存储库时都能直接使用这些工具。

在处理 MCP 时，使用 --mcp-debug 标志启动 Claude 也可能有助于识别配置问题。

c. 使用自定义斜杠命令

对于重复的工作流程——调试循环、日志分析等——将提示模板保存在 .claude/commands 文件夹内的 Markdown 文件中。当您输入 / 时，这些模板会通过斜杠命令菜单变得可用。您可以将这些命令提交到 git 中，以便您的整个团队都可以使用它们。

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

例如，这是一个您可以用来自动拉取和修复 Github 问题的斜杠命令：

将上述内容放入 .claude/commands/fix-github-issue.md 中，使其在 Claude Code 中作为 /project:fix-github-issue 命令可用。然后，例如，您可以使用 /project:fix-github-issue 1234 让 Claude 修复问题 #1234。类似地，您可以将您自己的个人命令添加到 ~/.claude/commands 文件夹中，以便在您的所有会话中都可用。

3. 尝试常见的工作流程

Claude Code 没有强制特定的流程，为您提供使用它的灵活性。在这个灵活性所提供的空间内，我们用户社区中已经出现了一些成功模式，可以有效地使用 Claude Code：

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

这种多用途的工作流程适合许多问题：

  1. Ask Claude to read relevant files, images, or URLs, providing either general pointers ("read the file that handles logging") or specific filenames ("read logging.py"), but explicitly tell it not to write any code just yet.
    1. 这是工作流程中考虑使用子代理的部分，特别是对于复杂问题。告诉 Claude 使用子代理来验证细节或调查它可能有的特定问题，尤其是在对话或任务的早期，这通常可以保持上下文的可用性，而不会在效率方面失去太多。
  2. Ask Claude to make a plan for how to approach a specific problem. We recommend using the word "think" to trigger extended thinking mode, which gives Claude additional computation time to evaluate alternatives more thoroughly. These specific phrases are mapped directly to increasing levels of thinking budget in the system: "think" < "think hard" < "think harder" < "ultrathink." Each level allocates progressively more thinking budget for Claude to use.
    1. 如果这一步的结果看起来合理，您可以让 Claude 创建一个文档或一个 GitHub 问题，其中包含它的计划，以便如果实施（步骤 3）不是您想要的，您可以重置到这个位置。
  3. 让 Claude 用代码实现它的解决方案。这也是一个好地方，可以要求它明确验证其解决方案的合理性，因为它正在实施解决方案的各个部分。
  4. 让 Claude 提交结果并创建拉取请求。如果相关，这也是一个让 Claude 更新任何 README 或变更日志，解释它刚刚做了什么的良好时机。

步骤 #1-#2 至关重要——如果没有它们，Claude 往往会直接开始编写解决方案。虽然有时这是您想要的，但要求 Claude 首先进行研究和计划可以显著提高需要预先深入思考的问题的性能。

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

这是 Anthropic 偏爱的用于可以通过单元测试、集成测试或端到端测试轻松验证更改的工作流程。在代理式编码中，测试驱动开发（TDD）变得更加强大：

  1. 让 Claude 根据预期的输入/输出对编写测试。明确指出您正在进行测试驱动开发，这样它就可以避免创建模拟实现，即使代码库中还没有此功能的实现。
  2. 告诉 Claude 运行测试并确认它们失败。明确告诉它在这个阶段不要编写任何实现代码通常很有帮助。
  3. 当您对测试满意时，让 Claude 提交测试 。
  4. Ask Claude to write code that passes the tests, instructing it not to modify the tests. Tell Claude to keep going until all tests pass. It will usually take a few iterations for Claude to write code, run the tests, adjust the code, and run the tests again.
    1. 在这个阶段，要求它使用独立的子代理来验证实现是否没有过度拟合测试可能会有所帮助。
  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，你可以使用 claude --dangerously-skip-permissions 跳过所有权限检查，让 Claude 不间断地工作直到完成。这对于修复格式错误或生成样板代码的工作流程效果很好。

让 Claude 运行任意命令是有风险的，可能导致数据丢失、系统损坏，甚至数据泄露（例如，通过提示注入攻击）。为了最大程度地降低这些风险，请在无互联网访问的容器中使用 --dangerously-skip-permissions。你可以遵循这个 参考实现 使用 Docker Dev Containers。

e. 代码库 Q&A

在入职新的代码库时，使用 Claude Code 进行学习和探索。你可以问 Claude 你在项目对等编程时会对另一位工程师问的问题。Claude 可以代理搜索代码库来回答一般性问题，例如：

  • 日志如何工作？
  • 我如何创建一个新的 API 端点？
  • async move { ... } 在 foo.rs 的第 134 行做什么？
  • 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 交互：

  • 创建拉取请求：Claude 理解缩写“pr”，并将根据差异和周围上下文生成适当的提交信息。
  • 实现一次性解决方案用于简单的代码审查评论：只需告诉它修复你的 PR 上的评论（可选，给出更具体的指令），并在完成后将其推回 PR 分支。
  • 修复失败的构建或 linter 警告
  • 通过让 Claude 遍历 GitHub 上的开放问题来对开放问题进行分类和分诊

这消除了记住 gh 命令行语法的需求，同时自动化了常规任务。

h. 使用 Claude 处理 Jupyter 笔记本

Anthropic 的研究人员和数据科学家使用 Claude Code 读取和写入 Jupyter 笔记本。Claude 可以解释输出，包括图像，提供了一种快速探索和交互数据的方式。没有必需的提示或工作流程，但我们推荐的工作流程是在 VS Code 中将 Claude Code 和一个 .ipynb 文件并排打开。

你也可以要求 Claude 在向同事展示你的 Jupyter 笔记本之前对其进行清理或进行美观改进。具体告诉它使笔记本或其数据可视化“美观”通常会帮助它记住它正在针对人类观看体验进行优化。

4. 优化你的工作流程

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

a. 在你的指令中保持具体

Claude Code 的成功率随着更具体的指令而显著提高，尤其是在第一次尝试时。提前给出清晰的指示可以减少后期需要进行的修正。

例如：

Claude 可以推断意图，但它无法读心。具体性有助于更好地与预期保持一致。

b. 给 Claude 图像

Claude 通过多种方法在图像和图表方面表现出色：

  • 粘贴屏幕截图 (小技巧：在 macOS 中按 cmd+ctrl+shift+4 截图到剪贴板，然后按 ctrl+v 粘贴。请注意，这与你通常在 Mac 上用于粘贴的 cmd+v 不同，并且无法远程工作。)
  • 直接将图像拖放到提示输入框中
  • 为图像提供文件路径

这在使用设计原型作为 UI 开发参考点以及用于分析和调试的视觉图表时特别有用。如果你没有向上下文中添加视觉效果，仍然可以明确地告诉 Claude 结果需要具有视觉吸引力。

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

使用标签补全功能快速引用存储在仓库中任何位置的文件或文件夹，帮助 Claude 找到或更新正确的资源。

d. 给 Claude URL

将特定的 URL 与你的提示一起粘贴，供 Claude 获取和读取。为了避免针对相同域（例如，docs.foo.com）的权限提示，使用 /permissions 将域添加到你的允许列表中。

e. 早期和频繁地进行修正

虽然自动接受模式（按住 shift+tab 切换）允许 Claude 自主工作，但通过积极参与并指导 Claude 的方法，你通常会得到更好的结果。通过在开始时向 Claude 详细解释任务，你可以获得最佳结果，但你也可以随时修正 Claude。

这四个工具有助于修正：

  • 在编码之前要求 Claude 制定计划。明确告诉它，在确认其计划看起来良好之前不要编码。
  • 按 Escape 键中断 Claude 在任何阶段（思考、工具调用、文件编辑）的操作，保留上下文，以便你可以重新定向或扩展指令。
  • 双击 Escape 键返回历史记录，编辑之前的提示，并探索不同的方向。您可以编辑提示并重复操作，直到得到您想要的结果。
  • 让 Claude 撤销更改，通常与选项 #2 结合使用以采取不同的方法。

尽管 Claude Code 偶尔在第一次尝试中就能完美解决问题，但使用这些修正工具通常能更快地产生更好的解决方案。

f. 使用 /clear 来聚焦上下文

在长时间会话中，Claude 的上下文窗口可能会被不相关的对话、文件内容和命令填满。这可能会降低性能，有时也会分散 Claude 的注意力。在任务之间频繁使用 /clear 命令来重置上下文窗口。

g. 使用清单和草稿板处理复杂的流程

对于具有多个步骤或需要详尽解决方案的大型任务——例如代码迁移、修复多个语法错误或运行复杂的构建脚本——通过让 Claude 使用 Markdown 文件（甚至是一个 GitHub 问题！）作为清单和工作草稿板来提高性能：

例如，要修复大量语法错误，您可以执行以下操作：

  1. 让 Claude 运行语法检查命令并将所有结果错误（包括文件名和行号）写入 Markdown 清单
  2. 指示 Claude 逐个处理每个问题，在标记为完成并移动到下一个之前进行修复和验证。

h. 将数据传递给 Claude

提供数据给 Claude 有几种方法：

  • 直接复制粘贴到您的提示中（最常见的方法）
  • 通过管道传递给 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 进行问题分类

无头模式可以驱动由 GitHub 事件触发的自动化，例如当您的存储库中创建新问题时。例如，公共的 Claude Code 存储库 使用 Claude 来检查新问题并分配适当的标签。

b. 使用 Claude 作为语法检查器

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

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

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

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

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

  1. 使用 Claude 编写代码
  2. 运行 /clear 或在另一个终端启动第二个 Claude
  3. 让第二个 Claude 审查第一个 Claude 的工作
  4. 启动另一个 Claude (或 /clear 再次) 来阅读代码和反馈意见
  5. 让这个 Claude 根据反馈意见编辑代码

你可以用类似的方法处理测试：让一个 Claude 编写测试，然后让另一个 Claude 编写代码来让测试通过。你甚至可以让你的 Claude 实例相互通信，方法是给它们分别提供工作草稿纸，并告诉它们要写入哪个和要读取哪个。

这种分离通常比让单个 Claude 处理所有事情得到更好的结果。

b. 对你的仓库进行多次签出

与其等待 Claude 完成每一步（许多 Anthropic 的工程师会这样做）:

  1. 在不同的文件夹中创建 3-4 个 git 签出
  2. 在不同的终端标签页中打开每个文件夹
  3. 在每个文件夹中启动 Claude 并分配不同的任务
  4. 循环切换 来检查进度并批准/拒绝权限请求

c. 使用 git worktrees

这种方法在多个独立任务中表现出色，为多次签出提供了一种更轻量级的替代方案。Git worktrees 允许你从同一个仓库签出多个分支到不同的目录中。每个 worktree 都有自己的工作目录，文件是隔离的，同时共享相同的 Git 历史记录和 reflog。

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

  1. 创建 worktrees: git worktree add ../project-feature-a feature-a
  2. 在每个 worktree 中启动 Claude: cd ../project-feature-a && claude
  3. 根据需要创建额外的 worktrees (在新终端标签页中重复步骤 1-2)

一些提示:

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

d. 使用带有自定义 harness 的 headless 模式

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

1. 分叉 处理大型迁移或分析（例如，分析数百个日志中的情感或分析数千个 CSV 文件）:

  1. 让 Claude 编写一个生成任务列表的脚本。例如，生成一个需要从框架 A 迁移到框架 B 的 2k 文件列表。
  2. 遍历任务，为每个任务调用 Claude 并给它一个任务和它可以使用的一组工具。例如: claude -p “migrate foo.py from React to Vue. When you are done, you MUST return the string OK if you succeeded, or FAIL if the task failed.” --allowedTools Edit Bash(git commit:*)
  3. 多次运行脚本并优化你的提示以获得期望的结果。

2. 管道化 将 Claude 集成到现有的数据/处理管道中:

  1. 调用 claude -p “<your prompt>” --json | your_command，其中 your_command 是你处理管道的下一步。
  2. 就这样！可选的 JSON 输出可以帮助提供结构，以便更容易地进行自动化处理。

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

你对使用 Claude Code 的工作有什么技巧和最佳实践？标签 @AnthropicAI，这样我们就能看到你在构建什么！

来源: Anthropic Research · anthropic.com

Anthropic / ClaudeAgent 智能体AI 编码MCP 与工具调用教程实践#教程实践#Agent#AI 编码#MCP 与工具调用#Anthropic