跳到正文
北京时间
原文
Anthropic：Newsroom·· 2025-04-18精选AI 评分81

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

Claude Code: Best practices for agentic coding

AI 导读

Anthropic 发布 Claude Code 最佳实践指南，介绍这款命令行智能体编码工具的使用模式。内容涵盖 CLAUDE.md 配置、工具白名单与自定义斜杠命令，以及探索规划编码提交、TDD、git worktrees 多实例并行等常见工作流，并给出 headless 模式自动化等进阶用法。

推荐理由

Anthropic 内部团队沉淀的 Claude Code 使用模式，从 CLAUDE.md 配置到多实例并行工作流，可直接迁移到自己的智能体编码实践。

正文 · 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 命令
  • 核心文件和实用函数
  • 代码风格指南
  • 测试说明
  • 仓库规范（例如分支命名、merge 与 rebase 等）
  • 开发者环境设置（例如 pyenv 的使用、哪些编译器可用）
  • 项目特有的任何意外行为或警告
  • 你希望 Claude 记住的其他信息

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

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

  • 仓库根目录，或你运行 claude 的任何位置（最常见用法）。将其命名为 CLAUDE.md 并提交到 git，以便跨会话和与团队共享（推荐），或将其命名为 CLAUDE.local.md 并 .gitignore 它
  • 运行 claude 所在目录的任意父目录。这对 monorepo 最有用，例如你可能从 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，我们偶尔会用 prompt improver 处理 CLAUDE.md 文件，并经常调整指令（例如用“IMPORTANT”或“YOU MUST”来强调）以提高遵循度。

Claude Code tool allowlist

c. 整理 Claude 的允许工具列表

默认情况下，Claude Code 会对任何可能修改你系统的操作请求许可：文件写入、许多 bash 命令、MCP 工具等。我们在设计 Claude Code 时有意采用这种保守方式，以优先保障安全。你可以自定义允许列表，以允许你确定安全的额外工具，或允许那些容易撤销的潜在不安全工具（例如文件编辑、git commit）。

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

  • 在会话中收到提示时选择“Always allow”。
  • 启动 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 交互，以创建 issue、发起 pull request、阅读评论等。即使未安装 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 issue：

将上述内容放入 .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 并不强制规定特定的工作流程，让您可以灵活地按自己的方式使用它。在这种灵活性所提供的空间内，我们的用户社区中已经涌现出若干有效使用 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 issue 来记录其计划，这样如果实现（第 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. 在此阶段，让 Claude 通过独立的子代理验证实现没有过度拟合测试会有所帮助
  5. 当您对更改满意后，让 Claude 提交代码。

当 Claude 有一个清晰的迭代目标——视觉稿、测试用例或其他类型的输出——时，它的表现最佳。通过提供测试等预期输出，Claude 可以进行修改、评估结果，并逐步改进直至成功。

c. 编写代码、截图结果、迭代

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

  1. 给 Claude 一种截取浏览器截图的方法（例如，使用 Puppeteer MCP server、iOS simulator MCP server，或手动将截图复制/粘贴给 Claude）。
  2. 给 Claude 一个视觉稿，方法是复制/粘贴或拖放图片，或者把图片文件路径给 Claude。
  3. 让 Claude 用代码实现该设计，对结果截图，并迭代直到结果与视觉稿一致。
  4. 当你满意时，让 Claude 提交。

和人类一样，Claude 的输出往往会随着迭代显著改善。第一版可能已经不错，但经过 2-3 次迭代后通常会好得多。给 Claude 查看其输出的工具，以获得最佳结果。

Safe yolo mode

d. 安全的 YOLO 模式

与其监督 Claude，你可以使用 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 就会探索代码来寻找答案。

Use Claude to interact with git

f. 使用 Claude 与 git 交互

Claude 能有效处理许多 git 操作。许多 Anthropic 工程师在 90% 以上的 git 交互中使用 Claude：

  • 搜索 git 历史以回答诸如“v1.2.3 中包含了哪些更改？”、“谁负责这个特定功能？”或“为什么这个 API 要这样设计？”之类的问题。明确提示 Claude 查阅 git 历史来回答这类问题会有所帮助。
  • 编写提交信息。 Claude 会自动查看你的更改和近期历史，在考虑所有相关上下文的情况下撰写提交信息
  • 处理复杂的 git 操作，如还原文件、解决 rebase 冲突，以及比较和移植补丁

g. 使用 Claude 与 GitHub 交互

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

  • 创建拉取请求：Claude 理解简写“pr”，并会根据 diff 和周边上下文生成合适的提交信息。
  • 实现一次性解决简单的代码审查评论：只需告诉它修复你 PR 上的评论（可选地，给出更具体的指令），完成后推送到 PR 分支。
  • 修复失败的构建或 linter 警告
  • 对未解决问题进行分类和分诊，让 Claude 遍历未解决的 GitHub issue

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

h. 使用 Claude 处理 Jupyter notebook

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

你也可以让 Claude 在向同事展示之前清理或美化你的 Jupyter notebook。明确告诉它让 notebook 或其数据可视化“美观悦目”，往往有助于提醒它是在为人类观看体验做优化。

4. 优化你的工作流

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

a. 在指令中要具体

Claude Code 的成功率会随着指令更具体而显著提高，尤其是在首次尝试时。提前给出清晰的方向可以减少后续纠偏的需要。

例如：

Claude 可以推断意图，但无法读心。具体性有助于更好地符合预期。

Give Claude images

b. 给 Claude 提供图像

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

  • 粘贴截图（专业提示：在 macOS 上按 cmd+ctrl+shift+4 截图到剪贴板，然后按 ctrl+v 粘贴。注意这不是你通常在 Mac 上粘贴用的 cmd+v，且无法远程使用。）
  • 拖放图像直接到提示词输入框
  • 提供文件路径用于图像

这在将设计稿作为 UI 开发的参考点，以及将可视化图表用于分析和调试时特别有用。如果你没有向上下文添加视觉内容，向 Claude 明确说明结果在视觉上美观有多重要仍然会有帮助。

Mention files you want Claude to look at or work on

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

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

Give Claude URLs

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. 为复杂工作流使用检查清单和草稿本

对于包含多个步骤或需要详尽解决方案的大型任务——例如代码迁移、修复大量 lint 错误或运行复杂的构建脚本——让 Claude 使用 Markdown 文件（甚至 GitHub issue！）作为检查清单和工作草稿本，可以提升性能：

例如，要修复大量 lint 问题，你可以这样做：

  1. 让 Claude 运行 lint 命令，并将所有产生的错误（包括文件名和行号）写入一个 Markdown 检查清单
  2. 指示 Claude 逐一处理每个问题，在勾选并继续下一个之前进行修复和验证

h. 将数据传入 Claude

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

  • 复制粘贴到你的提示词中（最常见的方式）
  • 通过管道传入 Claude Code（例如 cat foo.txt | claude），对日志、CSV 和大型数据特别有用
  • 让 Claude 拉取数据，通过 bash 命令、MCP 工具或自定义斜杠命令
  • 让 Claude 读取文件或获取 URL（也适用于图片）

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

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

Claude Code 包含无头模式，适用于 CI、pre-commit 钩子、构建脚本和自动化等非交互式场景。在提示词中使用 -p 标志来启用无头模式，使用 --output-format stream-json 来流式输出 JSON。

请注意，无头模式不会在会话之间持久化。你必须在每个会话中触发它。

a. 使用 Claude 进行问题分类

无头模式可以驱动由 GitHub 事件触发的自动化，例如当你的仓库中创建新 issue 时。例如，公开的 Claude Code 仓库使用 Claude 在收到新 issue 时进行检查并分配适当的标签。

b. 将 Claude 用作 linter

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

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 worktree

这种方法在多个独立任务场景下表现出色，是多重检出副本的一种更轻量替代方案。Git worktree 允许你把同一仓库的多个分支检出到不同目录中。每个 worktree 都有自己的工作目录和隔离文件，同时共享相同的 Git 历史和 reflog。

使用 git worktree 可以让你在项目的不同部分同时运行多个 Claude 会话，每个会话专注于自己的独立任务。例如，你可以让一个 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. 使用无头模式和自定义 harness

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

1. 扇出处理大规模迁移或分析（例如，分析数百条日志中的情感，或分析数千个 CSV 文件）：

  1. 让 Claude 编写一个脚本来生成任务列表。例如，生成一个包含 2k 个需要从框架 A 迁移到框架 B 的文件列表。
  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：Newsroom · anthropic.com

#教程/实践#编码#Agent#Anthropic