Claude Code：代理编码的最佳实践

Claude Code是一个用于代理编码的命令行工具。本文将介绍一些经过验证的技巧和窍门，这些技巧和窍门有助于在各种代码库、语言和环境中有效使用Claude Code。

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

Claude Code 刻意保持底层且不带有主观色彩，提供近乎原始的模型访问权限，而不强制执行特定的工作流程。这种设计理念创造了一个灵活、可定制、可编程且安全的有力工具。虽然功能强大，但这种灵活性对于刚接触代理编程工具的工程师来说，至少在他们形成自己的最佳实践之前，会带来一定的学习曲线。

本文概述了一些已被证明有效的一般模式，这些模式既适用于Anthropic的内部团队，也适用于在不同代码库、语言和环境中使用Claude Code的外部工程师。此列表中的内容并非一成不变或普遍适用；请将这些建议视为起点。我们鼓励您进行实验，找到最适合您的方法！

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

1. 自定义您的设置

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

a. 创建CLAUDE.md文件

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

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

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

# Bash 命令
- 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中
• 运行claude的目录的任何父目录。这在单体仓库（monorepos）中最为有用，你可能从root/foo运行claude，而CLAUDE.md文件既存在于root/CLAUDE.md中，也存在于root/foo/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文件，并经常调整指令（例如，用“重要”或“必须”来强调），以提高遵循度。

Claude Code工具白名单

c. 整理克劳德（Claude）的允许使用工具清单

默认情况下，Claude Code会请求权限以执行任何可能修改您系统的操作：文件写入、许多bash命令、MCP工具等。我们采用这种刻意保守的方法设计Claude Code，以优先考虑安全性。您可以自定义白名单，以允许您已知安全的额外工具，或允许易于撤销的潜在不安全工具（例如，文件编辑、git提交）。

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

• 在会话过程中出现提示时，选择“始终允许”。
• 启动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可以访问您的Shell环境，您可以在其中构建一系列便利的脚本和函数，就像为自己构建一样。它还可以通过MCP和REST API利用更复杂的工具。

a. 使用Claude配合bash工具

Claude Code继承了您的Bash环境，使其能够访问您的所有工具。虽然Claude知道常见的实用程序，如Unix工具和gh，但如果没有指示，它就无法识别您的自定义Bash工具：

告诉克劳德工具的名称以及使用示例
告诉克劳德运行--help以查看工具文档
在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问题：

请分析并修复GitHub问题：$ARGUMENTS。

请遵循以下步骤：
1. 使用`gh issue view`获取问题详情
2. 理解问题中描述的问题
3. 在代码库中搜索相关文件
4. 实施必要的更改以解决问题
5. 编写并运行测试以验证修复效果
6. 确保代码通过代码检查和类型检查
7. 编写具有描述性的提交说明
8. 推送并创建一个拉取请求（Pull Request，PR）
请记住，在执行所有与GitHub相关的任务时，请使用GitHub CLI（`gh`）。

复制
将上述内容放入 .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. 探索、规划、编码、提交

这种多功能的工作流程适用于许多问题：

让克劳德阅读相关的文件、图片或网址，提供一般性指示（“阅读处理日志的文件”）或具体的文件名（“阅读logging.py”），但要明确告诉它暂时不要编写任何代码。
这是工作流程中应重点考虑使用子代理的部分，尤其是对于复杂问题。告诉克劳德使用子代理来核实细节或调查其可能遇到的特定问题，尤其是在对话或任务的早期阶段，往往能保持上下文的可用性，而不会在效率方面造成太大损失。
请让克劳德（Claude）制定一个处理特定问题的方案。我们建议使用“思考”这个词来触发扩展思考模式，这会给克劳德额外的计算时间来更全面地评估各种方案。这些特定短语在系统中直接对应着不同程度的思考预算：“思考”<“深入思考”<“更深入思考”<“超深度思考”。每个级别都会为克劳德分配逐渐增加的更多思考预算。
如果这一步的结果看起来合理，你可以让克劳德（Claude）创建一个文档或一个GitHub问题，并附上其计划，这样如果实施（第三步）不符合你的预期，你就可以重置到这一步。
请克劳德用代码实现其解决方案。在此过程中，也是要求其在实现解决方案的各个部分时，明确验证其解决方案合理性的好时机。
请让克劳德提交结果并创建一个拉取请求。如果相关，这也是一个好时机，让克劳德更新任何README文件或变更日志，并解释它刚刚做了什么。
步骤#1-#2至关重要——如果没有这些步骤，克劳德往往会直接开始编写解决方案。虽然有时这正是你所希望的，但要求克劳德先进行研究并制定计划，对于那些需要预先进行深入思考的问题，会显著提高其解决效率。

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

这是一个备受人类青睐的工作流程，适用于那些可通过单元测试、集成测试或端到端测试轻松验证的变更。在代理编码中，测试驱动开发（TDD）的作用更为显著：

让克劳德根据预期的输入/输出对编写测试。明确说明你们正在进行的是测试驱动开发，这样即使代码库中尚不存在某些功能，也能避免创建模拟实现。
告诉克劳德（Claude）运行测试并确认它们失败。明确告诉它在这个阶段不要编写任何实现代码通常会有所帮助。
当你对测试结果满意时，请让克劳德提交这些测试。
让克劳德编写能通过测试的代码，并指示他不要修改测试。告诉克劳德继续编写，直到所有测试都通过。通常，克劳德需要经过几次迭代，即编写代码、运行测试、调整代码，然后再运行测试。
在此阶段，要求它与独立的子代理进行验证，以确保实现不会对测试产生过拟合，这将有所帮助
当你对修改满意后，请让克劳德提交代码。
当克劳德（Claude）有一个明确的目标可供迭代时，它的表现最佳——这个目标可以是视觉模拟、测试用例或其他类型的输出。通过提供测试等预期输出，克劳德可以进行更改、评估结果，并逐步改进，直至成功。

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

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

为Claude提供一种浏览器截图的方式（例如，使用Puppeteer MCP服务器、iOS模拟器MCP服务器，或手动将截图复制/粘贴到Claude中）。
通过复制/粘贴或拖放图像，或者向克劳德提供图像文件路径，为克劳德提供一个视觉模拟。
让克劳德用代码实现设计，对结果进行截图，并不断迭代，直到其结果与模拟图相匹配。
当你满意时，请让克劳德做出承诺。
和人类一样，克劳德的输出往往会在迭代过程中显著提升。虽然第一个版本可能不错，但经过2-3次迭代后，其效果通常会显著提升。为了让克劳德获得最佳结果，请为其提供查看输出的工具。

d. 安全YOLO模式

你可以使用claude --dangerously-skip-permissions来绕过所有权限检查，让Claude不受干扰地工作直至完成，而不是对其进行监督。这种方法非常适用于修复lint错误或生成样板代码等工作流程。

让克劳德（Claude）执行任意命令是有风险的，可能会导致数据丢失、系统崩溃，甚至数据泄露（例如，通过提示注入攻击）。为了将这些风险降至最低，请在无法访问互联网的容器中使用--dangerously-skip-permissions。您可以按照此参考实现使用Docker开发容器。

e. 代码库问答

在接触新代码库时，使用Claude Code进行学习和探索。你可以像在结对编程时询问项目中的其他工程师一样，向Claude提出同样类型的问题。Claude能够智能地搜索代码库，并回答以下一般性问题：

日志记录是如何工作的？
我如何创建一个新的API端点？
在 foo.rs 的第 134 行，async { ... } 做了什么？
CustomerOnboardingFlowImpl处理哪些边缘情况？
为什么在第333行我们调用的是foo()而不是bar()？
在Java中，baz.py的第334行等价于什么？
在Anthropic，以这种方式使用Claude Code已成为我们的核心入职工作流程，显著缩短了上手时间，并减轻了其他工程师的负担。无需特别提示！只需提出问题，Claude就会自动探索代码以找到答案。

使用Claude与Git进行交互

f. 使用Claude与Git进行交互

Claude能够高效处理许多Git操作。在Anthropic，许多工程师90%以上的Git交互都是通过Claude完成的：

搜索Git历史记录以回答诸如“哪些更改被纳入v1.2.3版本？”，“这个特定功能归谁所有？”，或“为什么这个API是这样设计的？”等问题。明确提示Claude查看Git历史记录以回答此类问题会有所帮助。
撰写提交说明。克劳德会自动查看你的更改和最近的历史记录，并综合考虑所有相关上下文来撰写一条说明
处理复杂的Git操作，如撤销文件、解决基线冲突以及比较和合并补丁

g. 使用Claude与GitHub进行交互

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

创建拉取请求：Claude理解“pr”这一简写，并将根据差异和上下文生成适当的提交消息。
为简单的代码审查评论实施一键修复：只需告诉它修复你拉取请求（PR）中的评论（可选地，给出更具体的指令），并在完成后将其推送到PR分支。
修复构建失败或代码检查警告
通过让Claude浏览GitHub上的开放问题，对这些问题进行分类和优先级排序
这样，在自动化执行日常任务时，就不需要记住gh命令行的语法了。

h. 使用Claude来处理Jupyter笔记本

Anthropic的研究人员和数据科学家使用Claude Code来读写Jupyter笔记本。Claude能够解释包括图像在内的输出，为探索数据和与数据交互提供了一种快速方式。虽然不存在必需的提示或工作流程，但我们推荐的一种工作流程是在VS Code中同时打开Claude Code和一个.ipynb文件。

在将Jupyter笔记本展示给同事之前，你也可以让Claude进行清理或进行美学改进。具体来说，告诉它让笔记本或其数据可视化“美观”，往往有助于提醒它，它是在为人类的观看体验而优化。

4. 优化你的工作流程

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

a. 给出具体明确的指示
随着指令的日益具体，克劳德·科德的成功率显著提高，尤其是在首次尝试时。提前给出明确的方向可以减少后续进行路线修正的需要。

例如：

克劳德能够推断意图，但无法读取思想。具体性有助于更好地与期望相契合。

给克劳德一些图片

b. 给克劳德一些图片

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

粘贴截图（专业提示：在macOS系统中，同时按下cmd+ctrl+shift+4可将截图保存到剪贴板，然后按下ctrl+v进行粘贴。请注意，这与您通常在mac上使用的粘贴方式（cmd+v）不同，且无法远程操作。）
将图片直接拖放到提示输入框中
提供图像的文件路径
当使用设计模拟作为UI开发的参考点以及使用视觉图表进行分析和调试时，这一点尤其有用。如果你没有为上下文添加视觉元素，那么与克劳德（Claude）明确沟通结果在视觉上吸引人的重要性仍然是有帮助的。

提及你想要克劳德查看或处理的文件

c. 提及你想让Claude查看或处理的文件

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

给克劳德提供网址

d. 给克劳德提供网址

在您的提示旁边粘贴特定的网址，以便Claude获取并读取。为避免对相同域（例如docs.foo.com）的权限提示，请使用/permissions将域添加到您的白名单中。

e. 尽早且经常调整方向

虽然自动接受模式（通过shift+tab切换）能让Claude自主工作，但作为积极的合作者并引导Claude的方法，你通常会获得更好的结果。你可以在一开始就向Claude详细解释任务，从而获得最佳结果，但你也可以随时纠正Claude的错误。

这四个工具有助于进行方向调整：

让克劳德在编码前制定一个计划。明确告诉他，在你确认他的计划看起来不错之前，不要开始编码。
在任何阶段（思考、调用工具、编辑文件）中，按Escape键可中断Claude，同时保留上下文，以便您可以重定向或扩展指令。
双击退出可返回历史记录，编辑之前的提示，并探索不同的方向。您可以编辑提示并重复操作，直到得到您想要的结果。
让克劳德撤销更改，通常结合选项#2采取不同的方法。
尽管克劳德·科德偶尔能在第一次尝试时就完美地解决问题，但使用这些修正工具通常能更快地得出更好的解决方案。

f. 使用/clear保持上下文聚焦

在长时间会话中，克劳德的上下文窗口可能会充斥着无关的对话、文件内容和命令。这可能会降低性能，有时还会分散克劳德的注意力。在任务之间，请频繁使用/clear命令来重置上下文窗口。

g. 对于复杂的工作流程，使用核对清单和便签纸

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

例如，要修复大量 lint 问题，您可以执行以下操作：

告诉克劳德运行lint命令，并将所有产生的错误（包括文件名和行号）写入Markdown清单中
指示克劳德逐一处理每个问题，先进行修复和验证，然后再核对并移至下一个问题

h. 将数据传入Claude

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

直接复制粘贴到你的提示中（最常见的方法）
通过管道输入到Claude Code（例如，cat foo.txt | claude），尤其适用于日志、CSV文件和大数据
告诉克劳德通过bash命令、MCP工具或自定义斜杠命令来提取数据
让克劳德读取文件或获取网址（也适用于图片）
大多数会话都会综合运用这些方法。例如，你可以导入一个日志文件，然后指示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来编写代码
运行 /clear 命令或在另一个终端中启动第二个 Claude
让第二个克劳德审查第一个克劳德的工作
再启动一个Claude（或/清除后重新启动）来阅读代码并查看反馈
让克劳德根据反馈来编辑代码
你也可以用测试来做类似的事情：让一个克劳德编写测试，然后让另一个克劳德编写代码使测试通过。你甚至可以让你的克劳德实例之间进行通信，方法是给它们分配单独的工作暂存区，并告诉它们哪个用于写入，哪个用于读取。

这种分工往往比让单个克劳德处理所有事情能取得更好的结果。

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

在Anthropic，许多工程师的做法是：不等克劳德（Claude）完成每一步，而是：

在单独的文件夹中创建3-4个Git检出
在单独的终端标签页中打开每个文件夹
在每个文件夹中启动Claude，并为其分配不同的任务
循环检查进度并批准/拒绝权限请求

c. 使用Git工作树

这种方法在处理多个独立任务时表现出色，为多次签出提供了更轻量级的替代方案。Git工作树允许您从同一存储库中签出多个分支到不同的目录中。每个工作树都有其自己的工作目录，其中包含隔离的文件，同时共享相同的Git历史记录和引用日志。

使用Git工作树，您可以在项目的不同部分同时运行多个Claude会话，每个会话都专注于其独立的任务。例如，您可能有一个Claude正在重构您的身份验证系统，而另一个Claude正在构建一个完全不相关的数据可视化组件。由于任务不重叠，每个Claude都可以全速工作，无需等待其他Claude的更改或处理合并冲突：

创建工作树：git worktree add ../project-feature-a feature-a
在每个工作树中启动Claude：cd ../project-feature-a && claude
根据需要创建额外的工作树（在新的终端标签页中重复步骤1-2）
一些提示：

使用一致的命名约定
每个工作树保持一个终端标签页
如果你在Mac上使用iTerm2，请设置通知，以便在Claude需要关注时提醒你
为不同的工作树使用单独的集成开发环境（IDE）窗口
完成后清理：git worktree remove ../project-feature-a

d. 使用带有定制线束的无头模式

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

1. 分支处理大型迁移或分析任务（例如，分析数百条日志中的情绪或分析数千个CSV文件）：

让克劳德写一个脚本，生成一个任务列表。例如，生成一个包含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调用可能会有所帮助。我们通常建议在生产环境中关闭详细模式，以获得更清晰的输出。

你使用Claude Code的技巧和最佳实践是什么？请@AnthropicAI，让我们看看你正在开发什么！

致谢

本文由鲍里斯·切尔尼撰写。本作品借鉴了更广泛的Claude Code用户群体的最佳实践，他们的创新方法和工作流程持续激励着我们。特别感谢黛熙·霍尔曼、阿什温·巴特、吴凯、西德·比达萨里亚、卡尔·吕布、诺迪尔·图拉库洛夫、巴里·张、德鲁·霍顿以及许多其他Anthropic工程师，他们对Claude Code的宝贵见解和实践经验帮助我们形成了这些建议。