Anthropic 推出 Claude Code 智能编程最佳实践指南（中文版）

Claude Code是用在智能编码(agentic coding)的命令行工具。本文涵盖了经过验证有效的技巧和方法，用于在各种代码库、语言和环境中使用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使用、可用的编译器)。
• 项目特定的任何意外行为或警告。
• 您希望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的目录的任何子目录。这与上述情况相反，在这种情况下，当您处理子目录中的文件时，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文件，经常调整指令（例如用”重要”或”必须”添加强调）以提高遵循度。

c.管理Claude允许使用的工具列表

默认情况下，Claude Code会对任何可能修改系统的操作请求权限：文件写入、大多数bash命令、MCP工具等。我们特意采用这种保守的设计来优先考虑安全性。您可以自定义允许列表来添加您确认安全的工具，或允许容易撤销的潜在不安全操作（如文件编辑、git提交）。

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

• 在会话出现提示时选择”始终允许”。
• 启动Claude Code后使用/allowed-tools命令添加或移除允许列表中的工具。例如：
• 添加Edit以始终允许文件编辑。
• 添加Bash(git commit:*)以允许git提交。
• 添加mcp__puppeteer__puppeteer_navigate以允许使用Puppeteer MCP服务器导航。
• 手动编辑.claude/settings.json或~/.claude.json文件（建议将前者纳入版本控制以便团队共享）。
• 使用–allowedTools命令行参数设置会话特定权限。

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问题：

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

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

• 让Claude阅读相关文件、图像或URL，可以提供一般性指引（”读取处理日志的文件”）或具体文件名（”读取logging.py”），但要明确告诉它暂时不要编写任何代码。 这是工作流程中应该考虑大量使用子代理的部分，特别是对于复杂问题。
• 告诉Claude使用子代理来验证细节或调查它可能有的特定问题，特别是在对话或任务的早期阶段，有助于保持上下文的可用性，而不会在效率方面造成太大损失。 让Claude制定解决特定问题的计划。我们建议使用”think”这个词来触发扩展思考模式，这会给Claude更多的计算时间来更彻底地评估替代方案。这些特定短语直接对应系统中逐渐增加的思考预算级别：”think” < “think hard” < “think harder” < “ultrathink”。每个级别都会分配更多的思考预算供Claude使用。 如果这一步的结果看起来合理，您可以让Claude创建一个文档或GitHub问题来记录其计划，以便在实现（第3步）不符合您的要求时可以回到这一点。
• 让Claude用代码实现其解决方案。这也是一个好时机，要求它在实现解决方案的各个部分时明确验证其解决方案的合理性。
• 让Claude提交结果并创建一个pull request。如果相关，这也是一个好时机，让Claude更新任何README或变更日志，解释它刚刚做了什么。

第1步到第2步至关重要——没有它们，Claude往往会直接跳到编写解决方案代码。虽然这正是您想要的，但让Claude先进行研究和计划可以显著提高深入思考问题的性能。

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

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

• 让Claude根据预期的输入/输出对编写测试。明确说明您正在进行测试驱动开发，这样它可以避免创建模拟实现，即使对于代码库中尚不存在的功能也是如此。
• 告诉Claude运行测试并确认它们是否失败。明确告诉它在这个阶段不要编写任何实现代码通常很有帮助。 当您对测试满意时，让Claude提交测试。 让Claude编写通过测试的代码，命令它不要修改测试。
• 告诉Claude继续直到所有测试通过。通常需要几次迭代，Claude才能编写代码、运行测试、调整代码并再次运行测试。在这个阶段，要求它用独立的子代理验证实现是否过度拟合测试可能会有所帮助
• 让Claude提交代码，当您对更改满意时。

当Claude有一个清晰的目标进行迭代时，它的表现会更好。这个目标可以是视觉草图、测试案例或者是任何具体的目标。这意味着，如果有一个明确的目标或方向，Claude能更好地发挥其潜力，提供更好的结果或解决方案

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

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

• 为Claude提供一种截取浏览器截图的方法（例如使用Puppeteer MCP、 iOS simulator MCP 服务器或手动将截图复制/粘贴到Claude中）。
• 通过复制/粘贴或拖放图像，或给Claude图像文件路径，为Claude提供一个视觉模拟。
• 让Claude用代码实现设计，截取结果的截图，并迭代直到其结果与模拟匹配。
• 当您满意时，让Claude提交。

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

d.YOLO安全模式

您可以使用claude –dangerously-skip-permissions绕过所有权限检查，让Claude不受干扰地工作直至完成，而不需要监督。这种方式特别适合修复lint错误或生成样板代码等工作流程。

但请注意，允许Claude运行任意命令存在风险，可能导致数据丢失、系统损坏甚至数据泄露（例如通过提示注入攻击）。为最大限度降低这些风险，请在没有网络连接的容器中使用–dangerously-skip-permissions。您可以参考这个使用Docker开发容器的实现方案。

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的许多工程师90%以上的git交互都使用Claude：

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

g.使用Claude进行GitHub交互

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

• 创建pull request，Claude理解”pr”缩写，会根据diff和周边上下文生成合适的提交信息。
• 实现简单代码审查意见的一次性修复：只需告诉它修复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查看或处理的文件

使用Tab键自动补全功能快速引用代码库中的任意文件或文件夹，帮助Claude准确定位或更新目标资源。

d.为Claude提供URL链接

在提示词中粘贴特定URL，Claude将自动获取并阅读内容。为避免重复请求相同域名（如docs.foo.com）的权限，可使用/allowed-tools命令将域名加入允许列表。

e.及时修正与频繁调整

虽然自动接受模式（通过shift+tab切换）能让Claude自主工作，但通过主动协作引导Claude通常能获得更好结果。最佳实践是在任务开始时向Claude完整说明需求，但您也可随时进行以下修正操作：

四项核心修正工具：

• 预先规划：要求Claude先制定计划，明确指示其未经确认不得开始编码。
• 即时中断（按Esc键）：可在Claude思考、调用工具或编辑文件时暂停当前操作，保留上下文以便调整指令。
• 历史回溯（双击Esc键）：回退至历史节点，修改先前提示以探索不同方案。
• 撤销变更：常与第2项配合使用，要求Claude撤回更改并尝试新方案。

虽然Claude Code偶而能首次就完美解决问题，但配合这些修正工具通常能更快获得更优解决方案。

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

在长时间会话中，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、预提交钩子、构建脚本和自动化等非交互式场景。使用-p标志和提示来启用无头模式，并使用–output-format stream-json获取流式JSON输出。

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

a.使用Claude进行问题分类

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

b.使用Claude作为linter

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

6.通过多Claude工作流升级

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

a.让一个Claude编写代码，另一个Claude验证

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

使用Claude编写代码 运行/clear或在另一个终端启动第二个Claude 让第二个Claude审查第一个Claude的工作 启动另一个Claude（或再次/clear）来阅读代码和审查反馈 让这个Claude根据反馈修改代码 您可以用测试做类似的事情：让一个Claude编写测试，然后让另一个Claude编写代码使测试通过。您甚至可以让您的Claude实例通过给它们单独的工作草稿板并告诉它们哪个要写入和哪个要读取来相互通信。

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

b.创建仓库的多个检出

Anthropic的许多工程师不是等待Claude完成每一步，而是这样做：

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

c.使用git worktree

这种方法适用于多个独立任务，提供了比多个检出更轻量级的替代方案。Git worktree允许您将同一仓库的多个分支检出到单独的目录中。每个worktree都有自己的工作目录和隔离的文件，同时共享相同的Git历史和reflog。

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

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

一些技巧：

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

d.将无头模式与自定义工具结合使用

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

• 1.分散处理适用于大规模迁移或分析（例如分析数百个日志的情感或分析数千个CSV）：
  • 让Claude编写一个脚本来生成任务列表。例如，生成需要从框架A迁移到框架B的2k个文件列表。
  • 循环处理任务，以编程方式为每个任务调用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调用可能会有帮助。我们通常建议在生产环境中关闭详细模式以获得更清晰的输出。

致谢

由Boris Cherny撰写。这项工作借鉴了整个Claude Code用户社区的最佳实践，他们的创造性方法和工作流程不断激励着我们。还要特别感谢Daisy Hollman、Ashwin Bhat、Cat Wu、Sid Bidasaria、Cal Rueb、Nodir Turakulov、Barry Zhang、Drew Hodun和许多其他Anthropic工程师，他们对Claude Code的宝贵见解和实际经验帮助塑造了这些建议。

原文链接：https://www.anthropic.com/engineering/claude-code-best-practices