跳到正文
Anthropic Engineering·· 2025-04-18精选AI 评分66

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

Claude Code: Best practices for agentic coding

AI 导读

Anthropic 工程团队发布 Claude Code 智能体编码最佳实践指南，核心约束是上下文窗口会随对话、文件读取和命令输出快速填满并导致性能下降。指南给出验证闭环、先探索再规划再编码、CLAUDE.md 配置、权限与沙箱、MCP 与 hooks、子智能体、并行会话和常见失败模式等做法，并建议同一问题纠正超过两次后 /clear 重开。

推荐理由

Anthropic 官方把 Claude Code 的上下文约束拆成可复用的配置与验证流程，适合对照自己的会话习惯逐条调整。

正文 · AI 翻译

Claude Code 是一个智能体式编程环境。与那种回答问题后就等待的聊天机器人不同，Claude Code 可以读取你的文件、运行命令、进行修改，并自主地解决问题，而你可以旁观、引导，或者完全离开。 这改变了你的工作方式。你不再需要自己编写代码然后让 Claude 审查，而是描述你想要什么，Claude 会弄清楚如何构建它。Claude 会探索、规划并实现。 但这种自主性仍然伴随着学习曲线。Claude 会在某些你需要理解的约束内工作。 本指南涵盖了在 Anthropic 内部团队以及在不同代码库、语言和环境中使用 Claude Code 的工程师中已被证明有效的模式。关于智能体循环如何运作，请参阅 Claude Code 如何工作。

大多数最佳实践都基于一个约束：Claude 的上下文窗口会很快被填满，而随着它被填满，性能会下降。 Claude 的上下文窗口保存你的整个对话，包括每条消息、Claude 读取的每个文件以及每条命令输出。然而，这会很快被填满。一次调试会话或代码库探索可能会生成并消耗数万个 token。 这很重要，因为随着上下文被填满，LLM 的性能会下降。当上下文窗口快满时，Claude 可能会开始“忘记”先前的指令或犯更多错误。上下文窗口是最重要的需要管理的资源。要了解会话在实践中如何被填满，请观看一个交互式演示，了解启动时加载了什么以及每次读取文件的成本。使用自定义状态行持续跟踪上下文使用情况，并查看减少 token 使用量以了解减少 token 使用量的策略。

给 Claude 一种验证其工作的方法

Claude 会在工作看起来完成时停止。如果没有它可以运行的检查，“看起来完成”就是唯一可用的信号，而你就成了验证循环：每个错误都等着你去发现。给 Claude 一些能产生通过或失败的东西，循环就会自行闭合。Claude 完成工作、运行检查、读取结果，并迭代直到检查通过。 检查可以是任何能返回 Claude 在对话中可读取信号的东西：测试套件、构建退出代码、linter、将输出与固定基准进行比对的脚本，或者与设计稿进行比对的浏览器截图。在 Claude 的检查通过后，你自己运行 /verify，以针对正在运行的应用确认更改。

策略之前之后
提供验证标准“实现一个验证电子邮件地址的函数”“编写一个 validateEmail 函数。示例测试用例：[email protected] 为 true，invalid 为 false，[email protected] 为 false。实现后运行测试”
以可视化方式验证 UI 更改“让仪表盘看起来更好”“[粘贴截图] 实现这个设计。对结果截图并将其与原始设计进行比较。列出差异并修复它们”
解决根本原因，而不是症状“构建失败了”“构建失败并出现此错误：[粘贴错误]。修复它并验证构建成功。解决根本原因，不要抑制错误”

一旦检查存在，就决定它对停止的约束有多强：

  • 在一条提示中：让 Claude 在同一条消息中运行检查并迭代，如上表所示。
  • 在整个会话中：将检查设置为 /goal 条件。单独的评估器会在每一轮之后重新检查它，Claude 会持续工作直到目标达成。如果 Claude 停滞不前，Claude Code 最终会在目标仍然设定的情况下停止运行——参见 /goal 评估的工作原理。
  • 作为确定性关卡：Stop hook 将你的检查作为脚本运行，并阻止该轮结束，直到检查通过。Stop 输入涵盖了连续阻止的上限。
  • 通过第二意见：验证子代理或动态工作流会检查自己的发现，让一个全新的模型尝试反驳结果，这样执行工作的代理就不是给它打分的那一个。

每一步都是用配置换取注意力。提示词版本如今适用于任何任务。/goal 和 Stop hook 版本才能让无人值守的运行在没有你的情况下正确完成。 让 Claude 展示证据，而不是断言成功：测试输出、它运行的命令及其返回结果，或者结果的截图。审查证据比自己重新运行验证更快，而且对于你没有在旁观看的会话也适用。

先探索，再规划，然后编码

让 Claude 直接跳到编码可能会产生解决错误问题的代码。使用规划模式将探索与执行分开。 推荐的工作流程有四个阶段：

1

2

3

4

在提示词中提供具体的上下文

Claude 可以推断意图，但它无法读心。引用具体文件、提及约束条件，并指向示例模式。

策略之前之后
界定任务范围。指定哪个文件、什么场景以及测试偏好。“为 foo.py 添加测试”“为 foo.py 编写一个测试，覆盖用户已登出的边缘情况。避免使用 mock。”
指向来源。引导 Claude 找到能回答问题的来源。“为什么 ExecutionFactory 的 api 这么奇怪？”“翻阅 ExecutionFactory 的 git 历史，总结它的 api 是如何演变成现在这样的”
引用现有模式。将 Claude 指向你代码库中的模式。“添加一个日历组件”“看看首页上现有组件是如何实现的，以理解这些模式。HotDogWidget.php 是一个很好的例子。遵循该模式实现一个新的日历组件，让用户可以选择月份并向前/向后翻页来选择年份。从头构建，除了代码库中已经使用的库之外不使用其他库。”
描述症状。提供症状、可能的位置，以及“修复”是什么样子。“修复登录 bug”“用户报告会话超时后登录失败。检查 src/auth/ 中的认证流程，尤其是 token 刷新。编写一个能复现该问题的失败测试，然后修复它”

当你正在探索并且能够承受纠正方向时，模糊的提示词可能很有用。像 "what would you improve in this file?" 这样的提示词可以揭示出你原本想不到要问的东西。

提供丰富的内容

你可以通过多种方式向 Claude 提供丰富的数据：

  • 用 @ 引用文件，而不是描述代码所在的位置。Claude 会在回应之前读取该文件。
  • 直接粘贴图片。将图片复制/粘贴或拖放到提示词中。
  • 提供 URL 用于文档和 API 参考。使用 /permissions 将常用域名加入允许列表。
  • 通过管道传入数据，运行 cat error.log | claude -p "explain this error" 直接发送文件内容。
  • 让 Claude 自行获取所需内容。告诉 Claude 使用 Bash 命令、MCP 工具或读取文件来自己拉取上下文。

配置你的环境

几个设置步骤就能让 Claude Code 在你所有的会话中显著更高效。有关扩展功能的完整概述以及何时使用每项功能，请参阅 扩展 Claude Code。

编写有效的 CLAUDE.md

CLAUDE.md 是一个特殊文件，Claude 会在每次对话开始时读取它。其中包含 Bash 命令、代码风格和工作流规则。这为 Claude 提供了它无法仅从代码中推断出的持久上下文。 CLAUDE.md 文件没有必需的格式，但要保持简短且易于人类阅读。例如：

CLAUDE.md

运行 /context 以确认 Claude 已加载该文件。CLAUDE.md 会在每次会话中加载，因此只应包含广泛适用的内容。对于仅有时相关的领域知识或工作流，请改用 skills。Claude 会按需加载它们，而不会让每次对话都变得臃肿。 保持简洁。对于每一行，问自己：“删掉这一行会导致 Claude 犯错吗？”如果不会，就删掉它。臃肿的 CLAUDE.md 文件会让 Claude 忽略你真正的指令！

✅ 包含❌ 排除
Claude 猜不到的 Bash 命令Claude 通过阅读代码就能弄清楚的任何内容
与默认值不同的代码风格规则Claude 已经知道的标准语言约定
测试说明和首选测试运行器详细的 API 文档（改为链接到文档）
仓库礼仪（分支命名、PR 约定）频繁变化的信息
你项目特有的架构决策冗长的解释或教程
开发环境怪癖（必需的环境变量）逐文件描述代码库
不显而易见的常见陷阱或行为像“编写整洁代码”这样不言自明的做法

如果 Claude 尽管有规则禁止，却仍然做你不想让它做的事，那这个文件可能太长了，规则被淹没了。如果 Claude 问你一些 CLAUDE.md 中已有答案的问题，那可能是措辞含糊。把 CLAUDE.md 当作代码来对待：出问题时审查它，定期精简它，并通过观察 Claude 的行为是否真的改变来测试改动。对于已检入的 CLAUDE.md，运行 /doctor，Claude 会针对它可以从代码库中推导出的内容提出删减建议。 如果 Claude 总是跳过某一条指令，只给那一行加上诸如“IMPORTANT”之类的强调。如果你强调了很多行，它们就都不突出了。把 CLAUDE.md 检入 git，这样你的团队就能共同贡献。这个文件的价值会随时间不断累积。 CLAUDE.md 文件可以使用 @path/to/import 语法导入其他文件。有关导入规则以及 CLAUDE.md 文件可以放在哪里，请参阅 CLAUDE.md 文件。

配置权限

在 Claude Code v2.1.283 或更高版本中，自动模式是交互式终端和 VS Code 会话的内置起始权限模式：由一个独立的分类器模型审查大多数操作，而不是由你来审查，只拦截看起来有风险的操作，例如权限范围升级、未知基础设施或恶意内容驱动的操作。在更早的版本中，自动模式仅在 Pro、Max 和 Team 计划中作为内置起始权限模式。 在手动模式下，Claude Code 会在可能修改系统的操作前询问你：文件写入、Bash 命令、MCP 工具。这很安全，但很繁琐。第十次批准之后，你只是在点击通过，而不是在审查。有两个工具可以减少手动模式下的这些中断，并且在自动模式下同样适用：

  • 权限允许列表：允许你已知安全的特定工具，例如 npm run lint 或 git commit
  • 沙箱：启用操作系统级隔离，限制文件系统和网络访问，让 Claude 在定义的边界内更自由地工作

阅读更多关于权限模式、权限规则和沙箱的内容。

使用 CLI 工具

CLI 工具是与外部服务交互时最节省上下文的方式。如果你使用 GitHub，请安装 gh CLI。Claude 知道如何使用它来创建 issue、发起 pull request 和阅读评论。没有 gh 时，Claude 仍然可以使用 GitHub API，但未认证的请求经常会触发速率限制。 Claude 也擅长学习它尚不熟悉的 CLI 工具。试试这样的提示 Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C.

连接 MCP 服务器

借助 MCP 服务器，你可以让 Claude 从 issue 跟踪器实现功能、查询数据库、分析监控数据、集成来自 Figma 的设计，并自动化工作流。

设置 hooks

Hooks 会在 Claude 工作流的特定节点自动运行脚本。与 CLAUDE.md 中建议性的指令不同，hooks 是确定性的，能保证操作一定发生。 Claude 可以为你编写 hooks。试试这样的提示：“编写一个在每次文件编辑后运行 eslint 的 hook”或“编写一个阻止写入 migrations 文件夹的 hook。”直接编辑 .claude/settings.json 即可手动配置 hooks，运行 /hooks 可浏览已配置的内容。

创建 skills

Skills 用特定于你的项目、团队或领域的信息扩展 Claude 的知识。Claude 会在相关时自动应用它们，你也可以用 /skill-name 直接调用它们。 通过向 .claude/skills/ 添加一个包含 SKILL.md 的目录来创建 skill：

.claude/skills/api-conventions/SKILL.md

Skills 还可以定义你可直接调用的可重复工作流：

.claude/skills/fix-issue/SKILL.md

运行 /fix-issue 1234 来调用它。对于有副作用、你希望手动触发的工作流，请使用 disable-model-invocation: true。

创建自定义子代理

子代理在它们自己的上下文中运行，拥有自己的一组允许工具。它们适用于读取大量文件或需要专门关注而不弄乱主对话的任务。

.claude/agents/security-reviewer.md

明确告诉 Claude 使用子代理：“使用子代理审查此代码的安全问题。”

安装插件

插件将技能、钩子、子代理和 MCP 服务器打包成一个可安装的单元，来自社区和 Anthropic。如果你使用带类型的语言，请安装一个代码智能插件，为 Claude 提供精确的符号导航和编辑后的自动错误检测。 关于如何在技能、子代理、钩子和 MCP 之间进行选择，请参阅扩展 Claude Code。

有效沟通

像问另一位工程师那样向 Claude 提问，对于较大的功能，让 Claude 采访你并在你开始实现之前写一份规格说明。

询问代码库相关问题

在熟悉新代码库时，使用 Claude Code 进行学习和探索。你可以像问另一位工程师那样向 Claude 提出同样类型的问题：

  • 日志是如何工作的？
  • 我如何创建一个新的 API 端点？
  • foo.rs 第 134 行的 async move { ... } 是做什么的？
  • CustomerOnboardingFlowImpl 处理哪些边界情况？
  • 为什么这段代码在第 333 行调用 foo() 而不是 bar()？

以这种方式使用 Claude Code 是一种有效的入职工作流程，可以缩短上手时间并减轻其他工程师的负担。无需特殊的提示：直接提问即可。

让 Claude 采访你

Claude 会询问你可能尚未考虑的事项，包括技术实现、UI/UX、边界情况和权衡取舍。在发送提示之前，将 [brief description] 替换为你的功能。

规格说明完成后，开始一个新会话来执行它。新会话拥有完全专注于实现的干净上下文，并且你有书面规格说明可供参考。 最有用的规格说明是自包含的：它们列出涉及的文件和接口，说明哪些不在范围内，并以一个端到端验证步骤结尾，证明该功能可以正常工作。花时间让规格说明精确，比花时间盯着实现更有回报。

管理你的会话

对话是持久且可逆的。利用这一点！

尽早且频繁地纠正方向

最好的结果来自紧密的反馈循环。尽管 Claude 偶尔会第一次尝试就完美解决问题，但快速纠正它通常能更快地产生更好的解决方案。

  • Esc：用 Esc 键在操作中途停止 Claude。上下文会被保留，因此你可以重新引导。
  • Esc + Esc 或 /rewind：按两次 Esc 或运行 /rewind 打开回退菜单，恢复之前的对话和代码状态，或从选定的消息进行总结。
  • "Undo that"：让 Claude 还原其更改。
  • /clear：在不相关的任务之间重置上下文。带有无关上下文的长会话可能会降低性能。

如果你在一次会话中就同一问题纠正 Claude 超过两次，说明上下文中充满了失败的尝试。运行 /clear 并带着更具体的提示重新开始，将你学到的东西纳入其中。带有更好提示的干净会话几乎总是胜过积累了大量纠正的长会话。

积极地管理上下文

当你接近上下文限制时，Claude Code 会自动压缩对话历史，从而保留重要的代码和决策，同时释放空间。 在长会话中，Claude 的上下文窗口可能会被无关的对话、文件内容和命令填满。这可能会降低性能，有时还会分散 Claude 的注意力。

  • 在任务之间频繁使用 /clear 来完全重置上下文窗口
  • 当自动压缩触发时，Claude 会总结最重要的内容，包括代码模式、文件状态和关键决策
  • 如需更多控制，可运行 /compact <instructions>，例如 /compact Focus on the API changes
  • 若只想压缩对话的一部分，可使用 Esc + Esc 或 /rewind，选择一个消息检查点，然后选择 Summarize from here 或 Summarize up to here。前者压缩从该点起的消息，同时保留更早的上下文不变；后者压缩更早的消息，同时完整保留近期消息。参见 回退菜单的总结选项。
  • 在 CLAUDE.md 中自定义压缩行为，使用类似 "When compacting, always preserve the full list of modified files and any test commands" 的指令，以确保关键上下文在总结后得以保留
  • 对于不需要留在上下文中的问题，可使用 /btw。答案永远不会进入对话历史，因此你可以在不增长上下文的情况下查看某个细节。

使用子代理进行调查

既然上下文是你的根本约束，就用子代理把研究排除在上下文之外。当 Claude 研究代码库时，它会读取大量文件，这些都会消耗你的上下文。子代理在独立的上下文窗口中运行，并回报摘要：

你也可以在 Claude 实现某功能后使用子代理进行验证。参见 添加对抗性审查步骤。

使用检查点回退

Claude 会在每次更改前自动对文件做快照，以便检查点可以恢复它们。双击 Escape 或运行 /rewind 打开回退菜单。你可以仅恢复对话、仅恢复代码、两者都恢复，或从选定的消息进行总结。详情参见 检查点。 与其仔细规划每一步，你可以让 Claude 尝试一些有风险的做法。如果行不通，就回退并尝试另一种方法。检查点会随对话一起保存，因此你可以关闭终端，稍后恢复会话，仍然可以回退。

恢复对话

Claude Code 会在本地保存对话，因此当一项任务跨越多次会话时，你不必重新解释上下文。运行 claude --continue 从上次中断处继续，或使用 claude --resume 从列表中选择。给会话起描述性名称，如 oauth-migration，以便日后查找。完整的恢复、分支和命名控制参见 管理会话。

自动化与扩展

一旦你能高效使用一个 Claude，就可以通过并行会话、非交互模式和扇出模式来倍增你的产出。

运行非交互模式

使用 claude -p "your prompt"，你可以非交互地运行 Claude，无需交互式提示。除非传入 --no-session-persistence，否则该次运行仍会创建一个可恢复的会话。非交互模式是你将 Claude 集成到 CI 流水线、pre-commit 钩子或任何自动化工作流中的方式。输出格式让你可以以编程方式解析结果：纯文本、JSON 或流式 JSON。

第一条命令打印纯文本。json 格式返回一个带有 result 字段的单个 JSON 对象。stream-json 格式每行打印一个 JSON 对象，以 init 事件开始。

运行多个 Claude 会话

选择适合你自己愿意做多少协调的并行方式，并在会话之间需要传递发现时添加消息传递：

  • 工作树：在隔离的 git 检出中运行独立的 CLI 会话，这样编辑不会相互冲突
  • 跨会话消息传递：让你自己运行的会话之间互相传递发现
  • 桌面应用：以可视化方式管理多个本地会话，可选让每个会话位于各自的工作树中
  • 在云端使用 Claude Code：默认在 Anthropic 管理的基础设施上运行会话
  • Agent 视图：研究预览版。运行 claude agents 来派发在后台持续运行的会话，并在一个屏幕上查看它们
  • Agent 团队：实验性功能，默认禁用。自动协调多个会话，共享任务、消息传递，并设有一名团队负责人

除了并行处理工作之外，多个会话还能实现以质量为中心的工作流。全新的上下文能改进代码审查，因为 Claude 不会偏向于它刚刚编写的代码。 例如，使用 Writer/Reviewer 模式：

会话 A（Writer）会话 B（Reviewer）
Implement a rate limiter for our API endpoints
Review the rate limiter implementation in @src/middleware/rateLimiter.ts. Look for edge cases, race conditions, and consistency with our existing middleware patterns.
Here's the review feedback: [Session B output]. Address these issues.

你也可以对测试做类似的事情：让一个 Claude 编写测试，然后让另一个 Claude 编写代码来通过测试。

跨文件扇出

对于大型迁移或分析，你可以将工作分配到许多并行的 Claude 调用中。运行 /batch <instruction> 让 Claude 将变更拆分到 5 到 30 个子代理中。每个子代理在各自的工作树中工作。若要改为从你自己的脚本驱动扇出，请循环遍历 claude -p：

1

2

3

你还可以将 Claude 集成到现有的数据/处理流水线中：

使用自动模式自主运行

若要在后台安全检查下不间断执行，请使用 自动模式。一个分类器模型会在命令运行前审查它们，阻止范围升级、未知基础设施以及由恶意内容驱动的操作，同时让常规工作无需提示即可继续。

当分类器在带有 -p 标志的非交互式运行中反复阻止操作时，Claude Code 不会停止该运行。请参阅 自动模式何时回退，了解取而代之会发生什么以及相关阈值。

添加对抗性审查步骤

Claude 无人值守工作的时间越长，在你认定工作完成之前，独立检查就越重要。在全新 子代理上下文中运行的审查者只能看到 diff 和你给它的标准，而看不到产生该变更的推理过程，因此它会独立地评估结果。 若要进行正确性检查，请运行内置的 /code-review 技能，它会在全新子代理中审查当前 diff 中的 bug，并将发现返回给会话。若要改为对照你的计划检查 diff，请自行编写审查提示词。指明要检查的工作、要对照检查的计划，以及什么算作一个发现：

由于审查者以子代理身份运行，实施会话会直接收到这些缺口，并可以修复它们并重新审查，而无需你在窗口之间复制发现。

避免常见失败模式

这些是常见错误。尽早识别它们可以节省时间：

  • The kitchen sink session. You start with one task, then ask Claude something unrelated, then go back to the first task. Context is full of irrelevant information.
    修复：在不相关的任务之间 /clear。
  • Correcting over and over. Claude does something wrong, you correct it, it’s still wrong, you correct again. Context is polluted with failed approaches.
    修复：在两次失败的纠正之后，/clear 并编写一个更好的初始提示词，纳入你学到的内容。
  • The over-specified CLAUDE.md. If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise.
    修复：无情地精简。如果 Claude 在没有该指令的情况下已经能正确完成某事，就删除它或将其转换为 hook。
  • The trust-then-verify gap. Claude produces a plausible-looking implementation that doesn’t handle edge cases.
    修复：始终提供验证（测试、脚本、截图）。如果你无法验证它，就不要发布它。
  • The infinite exploration. You ask Claude to “investigate” something without scoping it. Claude reads hundreds of files, filling the context.
    修复：将调查范围缩小，或使用子代理，这样探索就不会消耗你的主上下文。

培养你的直觉

本指南中的模式并非一成不变。它们是通用的良好起点，但未必对每种情况都是最优的。 有时你应该让上下文累积，因为你正深入一个复杂问题，历史记录很有价值。有时你应该跳过规划，让 Claude 自行解决，因为任务是探索性的。有时模糊的提示恰恰合适，因为你想在约束问题之前先看看 Claude 如何理解它。 留意哪些做法有效。当 Claude 产出优秀结果时，注意你做了什么：提示结构、你提供的上下文、你所在的模式。当 Claude 遇到困难时，问问为什么。上下文太嘈杂？提示太模糊？任务太大，一次无法完成？ 随着时间推移，你会培养出任何指南都无法捕捉的直觉。你会知道何时该具体、何时该开放，何时该规划、何时该探索，何时该清空上下文、何时该让它累积。

来源：Anthropic Engineering · anthropic.com

Anthropic / ClaudeAgent 智能体AI 编码部署工程教程实践#教程/实践#Agent#编码#部署/工程#Anthropic