Programming

【翻译】Claude Code：代理式编码的最佳实践

发布于 2025年4月18日，原文链接

Claude Code 是一款用于代理式编码（agentic coding）的命令行工具。本文将介绍一些在使用 Claude Code 过程中，跨越不同代码库、语言和环境都已证明行之有效的技巧和窍门。

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

Claude Code 的设计理念是刻意保持底层和无固定模式（low-level and unopinionated），提供近乎原始的模型访问能力，而不强制用户遵循特定的工作流程。这种设计哲学创造了一个灵活、可定制、可编写脚本且功能强大的安全工具。然而，尽管功能强大，这种灵活性也给初次接触代理式编码工具的工程师带来了一定的学习曲线——至少在他们形成自己的一套最佳实践之前是如此。

本文旨在概述一些已在 Anthropic 内部团队以及在各种代码库、语言和环境中使用的外部工程师中被证明是行之有效的通用模式。此列表中的任何内容都不是一成不变或普遍适用的；请将这些建议视为起点。我们鼓励您进行实验，找到最适合您的方式！

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

1. 自定义您的设置

Claude Code 是一个代理式编码助手，它会自动将上下文信息提取到提示中。这种上下文收集过程会消耗时间和 tokens，但您可以通过调整环境来优化它。

a. 创建 CLAUDE.md 文件

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

  • 常用的 bash 命令
  • 核心文件和实用函数
  • 代码风格指南
  • 测试说明
  • 代码仓库的规范（例如，分支命名、使用 merge 还是 rebase 等）
  • 开发者环境设置（例如，pyenv 的使用、哪些编译器可用）
  • 项目中特有的任何意外行为或警告
  • 您希望 Claude 记住的其他信息

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

1
2
3
4
5
6
7
8
9

# Bash commands
\- npm run build: Build the project
\- npm run typecheck: Run the typechecker
\# Code style
\- Use ES modules (import/export) syntax, not CommonJS (require)
\- Destructure imports when possible (eg. import { foo } from 'bar')
\# Workflow
\- Be sure to typecheck when you’re done making a series of code changes
\- Prefer running single tests, and not the whole test suite, for performance

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

  • 仓库的根目录，或您运行 claude 命令的任何位置（最常见的用法）。将其命名为 CLAUDE.md 并提交到 git 中，以便在不同会话和团队成员之间共享（推荐），或者命名为 CLAUDE.local.md 并将其添加到 .gitignore 中。
  • 运行 claude 命令所在目录的任何父目录。这对于 monorepos（单一代码库）项目最有用，您可能在 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” 来强调）以提高模型的遵循度。

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

默认情况下，对于任何可能修改您系统的操作，Claude Code 都会请求许可：文件写入、许多 bash 命令、MCP 工具等。我们设计 Claude Code 时采用了这种刻意保守的方法，以将安全性放在首位。您可以自定义允许列表（allowlist），以允许您确信安全的其他工具，或允许那些易于撤销的潜在不安全工具（例如，文件编辑、git commit）。

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

  • 在会话中被提示时选择 “Always allow”（始终允许）。
  • 启动 Claude Code 后使用 /permissions 命令来添加或移除允许列表中的工具。例如，您可以添加 Edit 来始终允许文件编辑，Bash(git commit:*) 来允许 git commit，或者 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 也有助于识别配置问题。

https://www-cdn.anthropic.com/images/4zrzovbb/website/6961243cc6409e41ba93895faded4f4bc1772366-1600x1231.png

c. 使用自定义斜杠命令

对于重复性的工作流——如调试循环、日志分析等——您可以将提示模板存储在 .claude/commands 文件夹中的 Markdown 文件里。当您键入 / 时，这些模板就会通过斜杠命令菜单可用。您可以将这些命令检入 git，使其对团队其他成员可用。

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

例如，这是一个可用于自动获取并修复 GitHub issue 的斜杠命令：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

Please analyze and fix the GitHub issue: $ARGUMENTS.
Follow these steps:
1\. Use \`gh issue view\` to get the issue details
2\. Understand the problem described in the issue
3\. Search the codebase for relevant files
4\. Implement the necessary changes to fix the issue
5\. Write and run tests to verify the fix
6\. Ensure code passes linting and type checking
7\. Create a descriptive commit message
8\. Push and create a PR
Remember to use the GitHub CLI (\`gh\`) for all GitHub-related tasks.

将上述内容放入 .claude/commands/fix-github-issue.md 文件中，即可在 Claude Code 中通过 /project:fix-github-issue 命令使用它。然后，您可以使用 /project:fix-github-issue 1234 来让 Claude 修复编号为 1234 的 issue。同样，您可以将个人命令添加到 ~/.claude/commands 文件夹中，以便在所有会话中使用。

3. 尝试常见工作流

Claude Code 不会强加特定的工作流，这让您可以灵活地按自己喜欢的方式使用它。在这种灵活性所提供的空间内，我们的用户社区中涌现出了几种成功有效使用 Claude Code 的模式：

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

这个通用的工作流适用于许多问题：

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

步骤 #1-#2 至关重要——没有它们，Claude 往往会直接跳到编码解决方案。虽然有时这正是您想要的，但对于需要更深入前期思考的问题，要求 Claude 先进行研究和规划会显著提高其表现。

https://www-cdn.anthropic.com/images/4zrzovbb/website/6ea59a36fe82c2b300bceaf3b880a4b4852c552d-1600x1143.png

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

这是一个 Anthropic 内部最喜欢的工作流，适用于那些可以通过单元测试、集成测试或端到端测试轻松验证的变更。测试驱动开发（TDD）在代理式编码的加持下变得更加强大：

  1. 要求 Claude 根据预期的输入/输出对编写测试。明确指出您正在进行测试驱动开发，这样它就会避免创建模拟实现，即使对于代码库中尚不存在的功能也是如此。
  2. 告诉 Claude 运行测试并确认它们失败。在此阶段明确告诉它不要编写任何实现代码通常很有帮助。
  3. 当您对测试满意时，要求 Claude 提交测试。
  4. 要求 Claude 编写能够通过测试的代码，并指示它不要修改测试。告诉 Claude 继续尝试，直到所有测试都通过。通常，Claude 需要几次迭代才能完成编写代码、运行测试、调整代码、再运行测试的循环。
    1. 在此阶段，要求它使用独立的子代理来验证实现是否对测试过拟合，这会很有帮助。
  5. 一旦您对更改满意，要求 Claude 提交代码。

当 Claude 有一个明确的目标可以迭代时——比如一个视觉模型、一个测试用例或其他类型的输出——它的表现最好。通过提供像测试这样的预期输出，Claude 可以进行更改、评估结果，并逐步改进直到成功。

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

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

  1. 为 Claude 提供一种截取浏览器屏幕截图的方法（例如，使用 Puppeteer MCP 服务器、(https://github.com/joshuayoes/ios-simulator-mcp)，或者手动复制/粘贴截图给 Claude）。
  2. 通过复制/粘贴或拖放图片，或者提供图片文件路径，给 Claude 一个视觉模型。
  3. 要求 Claude 用代码实现该设计，截取结果的屏幕截图，并进行迭代，直到其结果与模型匹配。
  4. 当您满意时，要求 Claude 提交。

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

https://www-cdn.anthropic.com/images/4zrzovbb/website/75e1b57a0b696e7aafeca1ed5fa6ba7c601a5953-1360x1126.png

d. 安全的 YOLO 模式

您可以不监督 Claude，而是使用 claude --dangerously-skip-permissions 来绕过所有权限检查，让 Claude 不间断地工作直到完成。这对于修复 lint 错误或生成样板代码等工作流非常有效。

让 Claude 运行任意命令是有风险的，可能导致数据丢失、系统损坏或…

\[译者注：原文此处句子不完整\]

4. 与 Claude 协作

最重要的实践是将 Claude 视为一个智能的协作者，而不仅仅是一个自动补全工具或搜索引擎。当您提供清晰、具体的指令并保持对话式的方法时，Claude 在处理复杂的多步骤任务时表现出色。

a. 具体明确

Claude 能够推断意图，但它无法读懂您的心思。具体性能够使其更好地与您的期望对齐。

不好的指令好的指令
为 foo.py 写测试为 foo.py 写一个新的测试用例，覆盖用户未登录时的边缘情况。避免使用 mock。
为什么 ExecutionFactory 的 API 这么奇怪？查看 ExecutionFactory 的 git 历史，总结一下它的 API 是如何演变至今的。
添加一个日历小部件查看主页上现有小部件的实现方式，以理解其模式，特别是代码和接口是如何分离的。HotDogWidget.php 是一个很好的入门示例。然后，遵循该模式实现一个新的日历小部件，允许用户选择月份并通过向前/向后翻页来选择年份。除了代码库中已使用的库之外，不要使用其他库，从头开始构建。

b. 给 Claude 提供图片

Claude 可以通过多种方式出色地处理图片和图表：

  • 粘贴截图（专业提示：在 macOS 中按 cmd+ctrl+shift+4 可以将截图复制到剪贴板，然后按 ctrl+v 粘贴。请注意，这与您通常在 Mac 上使用的 cmd+v 不同，并且在远程操作时无效。）
  • 拖放图片到提示输入框中。
  • 提供图片的文件路径。

这在进行 UI 开发时以设计模型为参考点，以及在分析和调试时使用可视化图表时特别有用。即使您不向上下文中添加视觉材料，明确告诉 Claude 最终结果在视觉上需要具有吸引力的重要性，仍然很有帮助。

https://www-cdn.anthropic.com/images/4zrzovbb/website/7372868757dd17b6f2d3fef98d499d7991d89800-1450x1164.png

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

使用 Tab 键自动补全功能，可以快速引用您仓库中任何位置的文件或文件夹，帮助 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 偶尔会在第一次尝试时就完美解决问题，但使用这些修正工具通常能更快地产生更好的解决方案。

https://www-cdn.anthropic.com/images/4zrzovbb/website/e071de707f209bbaa7f16b593cc7ed0739875dae-1306x1088.png

f. 使用 /clear 保持上下文的专注

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

g. 对复杂工作流使用清单和草稿板

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

5. 脚本与自动化

  1. 批处理允许您自动执行重复性任务：
    1. 创建一个包含您的提示的 shell 脚本。
    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. 管道操作 (Pipelining) 将 Claude 集成到现有的数据/处理管道中：
    1. 调用 claude -p “<your prompt>” --json | your_command，其中 your_command 是您处理管道的下一步。
    2. 就是这样！JSON 输出（可选）可以帮助提供结构，以便于自动化处理。

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

您在使用 Claude Code 方面有什么技巧和最佳实践吗？请标记 @AnthropicAI，让我们看看您正在构建什么！

致谢

作者：Boris Cherny。这项工作借鉴了广大 Claude Code 用户社区的最佳实践，他们富有创造力的方法和工作流程持续激励着我们。特别感谢 Daisy Hollman、Ashwin Bhat、Cat Wu、Sid Bidasaria、Cal Rueb、Nodir Turakulov、Barry Zhang、Drew Hodun 以及许多其他 Anthropic 工程师，他们宝贵的见解和使用 Claude Code 的实践经验帮助塑造了这些建议。

想了解更多？

通过 Anthropic Academy 的课程，掌握 API 开发、模型上下文协议（Model Context Protocol）和 Claude Code。完成课程后可获得证书。

探索课程

© 2025 Anthropic PBC

comments powered by Disqus
© 2018 - 2025 morsuning's Blog
Intelligence all rights reserved.
使用 Hugo 构建
主题 Stack 由 Jimmy 设计