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

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

Claude Code 故意保持低级和无主见，提供接近原始模型的访问，而无需强制使用特定的工作流程。这种设计理念创建了一个灵活、可自定义、可编写脚本且安全的 Power Tool。虽然功能强大，但这种灵活性为刚接触代理编码工具的工程师提供了一个学习曲线，至少在他们开发自己的最佳实践之前是这样。

这篇文章概述了已被证明有效的一般模式，无论是对于 Anthropic 的内部团队，还是对于在各种代码库、语言和环境中使用 Claude Code 的外部工程师。此列表中的任何内容都不是一成不变的，也不是普遍适用的;将这些建议视为起点。我们鼓励您尝试并找到最适合您的方法！

寻找更多详细信息？我们在 claude.ai/code 上的综合文档涵盖了本文中提到的所有功能，并提供了其他示例、实现细节和高级技术。

1. 自定义您的设置

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

一个。创建文件CLAUDE.md

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

• 常见的 bash 命令
• 核心文件和实用程序函数
• 代码样式准则
• 测试说明
• 仓库礼仪（例如，分支命名、merge 与 rebase 等）
• 开发人员环境设置（例如，pyenv use，哪些编译器可以工作）
• 特定于项目的任何意外行为或警告
• 您希望 Claude 记住的其他信息

文件没有必需的格式。我们建议保持它们简洁易读。例如：CLAUDE.md

# 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

• 存储库的根目录，或者您从何处运行（最常见的用法）。为它命名并将其签入 git，以便您可以在会话之间和与您的团队共享它（推荐），或者为它命名claudeCLAUDE.mdCLAUDE.local.md.gitignore
• 运行 .这对于 monorepo 最有用，因为您可以从 中运行，并在 和 中都有文件。这两者都会自动拉入上下文claudeclauderoot/fooCLAUDE.mdroot/CLAUDE.mdroot/foo/CLAUDE.md
• 运行 .这与上述情况相反，在这种情况下，当您处理子目录中的文件时，Claude 将按需提取文件claudeCLAUDE.md
• 您的主文件夹 （），用于将其应用于所有 claude 会话~/.claude/CLAUDE.md

当您运行该命令时，Claude 将为您自动生成一个。/initCLAUDE.md

b.优化您的文件CLAUDE.md

您的文件将成为 Claude 提示的一部分，因此应像任何常用提示一样对其进行优化。一个常见的错误是添加大量内容而不迭代其有效性。花点时间试验并确定什么能从模型中产生最佳指令。CLAUDE.md

您可以手动将内容添加到您的内容中，也可以按 键向 Claude 提供指令，它将自动合并到相关的 .许多工程师在编码时经常使用来记录命令、文件和样式指南，然后在提交中包含更改，以便团队成员也能受益。CLAUDE.md#CLAUDE.md#CLAUDE.md

在 Anthropic，我们偶尔会通过提示改进器运行文件，并经常调整说明（例如，用“IMPORTANT”或“YOU MUST”添加强调）以提高依从性。CLAUDE.md

c. 策划 Claude 允许的工具列表

默认情况下，Claude Code 请求对可能修改系统的任何作的权限：文件写入、许多 bash 命令、MCP 工具等。我们设计 Claude Code 时采用了这种刻意保守的方法，以优先考虑安全。您可以自定义允许列表以允许使用您知道安全的其他工具，或允许使用易于撤消的潜在不安全工具（例如，文件编辑等）。git commit

有四种方法可以管理允许的工具：

• 在会话期间出现提示时选择 “Always allow”（始终允许）。
• 启动 Claude Code 后，使用 /allowed-tools 命令在允许列表中添加或删除工具。例如，您可以添加以始终允许文件编辑，允许git提交或允许使用Puppeteer MCP服务器进行导航。EditBash(git commit:*)mcp__puppeteer__puppeteer_navigate
• Manually edit your or (we recommend checking the former into source control to share with your team)..claude/settings.json~/.claude.json
• Use the --allowedTools CLI flag for session-specific permissions.

d. If using GitHub, install the gh CLI

Claude knows how to use the CLI to interact with GitHub for creating issues, opening pull requests, reading comments, and more. Without installed, Claude can still use the GitHub API or MCP server (if you have it installed).ghgh

2. Give Claude more tools

Claude has access to your shell environment, where you can build up sets of convenience scripts and functions for it just like you would for yourself. It can also leverage more complex tools through MCP and REST APIs.

a. Use Claude with bash tools

Claude Code inherits your bash environment, giving it access to all your tools. While Claude knows common utilities like unix tools and , it won't know about your custom bash tools without instructions:gh

1. Tell Claude the tool name with usage examples
2. Tell Claude to run to see tool documentation--help
3. Document frequently used tools in CLAUDE.md

b. Use Claude with MCP

Claude Code functions as both an MCP server and client. As a client, it can connect to any number of MCP servers to access their tools in three ways:

• 在 project config 中（在该目录中运行 Claude Code 时可用）
• 在全局配置中（在所有项目中都可用）
• 在签入的 .mcp.json 文件中（适用于在代码库中工作的任何人）。例如，您可以将 Puppeteer 和 Sentry 服务器添加到您的 中，以便处理您的存储库的每个工程师都可以开箱即用地使用它们。.mcp.json

使用 MCP 时，使用标志启动 Claude 以帮助识别配置问题也很有帮助。--mcp-debug

c. 使用自定义斜杠命令

对于重复的工作流程（调试循环、日志分析等），请将提示模板存储在文件夹内的 Markdown 文件中。当您键入 时，这些选项将通过斜杠命令菜单提供。您可以将这些命令签入 git 中，以便它们可供团队的其他成员使用。.claude/commands/

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

例如，这是一个 slash 命令，您可以使用它来自动提取和修复 Github 问题：

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 Code 中作为命令使用。然后，例如，您可以使用 Claude 修复问题 #1234。同样，您可以将自己的个人命令添加到您希望在所有会话中可用的命令的文件夹中。.claude/commands/fix-github-issue.md/project:fix-github-issue/project:fix-github-issue 1234~/.claude/commands

3. 尝试常见的工作流程

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

一个。探索、规划、编码、提交

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

1. 让 Claude 读取相关文件、图像或 URL，提供通用指针（“读取处理日志记录的文件”）或特定文件名（“读取 logging.py”），但明确告诉它暂时不要编写任何代码。
   1. 这是工作流中应考虑大量使用子代理的部分，尤其是对于复杂问题。告诉 Claude 使用子代理来验证细节或调查它可能存在的特定问题，尤其是在对话或任务的早期，往往会保持上下文可用性，而不会在效率损失方面有太大的负面影响。
2. 让 Claude 制定如何处理特定问题的计划。我们建议使用 “think” 这个词来触发扩展思维模式，这为 Claude 提供了额外的计算时间来更彻底地评估替代方案。这些特定的短语直接映射到系统中不断增加的思维预算水平：“think” < “think hard” < “think harder” < “ultrathink”。每个级别都会逐渐分配更多的思考预算供 Claude 使用。
   1. 如果此步骤的结果看起来合理，您可以让 Claude 创建一个文档或 GitHub 问题及其计划，以便在实现（步骤 3）不是您想要的时重置到此位置。
3. 让 Claude 在代码中实现其解决方案。这也是要求它在实现解决方案的各个部分时显式验证其解决方案的合理性的好地方。
4. 让 Claude 提交结果并创建拉取请求。如果相关，这也是让 Claude 更新任何 README 或更改日志并解释它刚刚做什么的好时机。

步骤 #1-#2 至关重要 — 没有它们，Claude 往往会直接跳到编写解决方案。虽然有时这就是你想要的，但让 Claude 先研究和规划可以显著提高需要提前深入思考的问题的性能。

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

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

1. 让 Claude 根据预期的输入/输出对编写测试。明确说明您正在进行测试驱动开发的事实，以便避免创建模拟实现，即使对于代码库中尚不存在的功能也是如此。
2. 告诉 Claude 运行测试并确认它们失败。在此阶段明确告诉它不要编写任何实现代码通常会有所帮助。
3. 当您对测试感到满意时，请让 Claude 提交测试。
4. 让 Claude 编写通过测试的代码，指示它不要修改测试。告诉 Claude 继续前进，直到所有测试都通过。Claude 通常需要几次迭代来编写代码、运行测试、调整代码并再次运行测试。
   1. 在此阶段，要求 IT 部门使用独立的 subagent 验证 implementation 是否未过度拟合测试会有所帮助
5. 如果您对更改感到满意，请让 Claude 提交代码。

当 Claude 具有明确的迭代目标（视觉模拟、测试用例或其他类型的输出）时，它的性能最佳。通过提供预期的输出（如测试），Claude 可以进行更改、评估结果并逐步改进，直到成功。

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

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

1. 为 Claude 提供一种截取浏览器屏幕截图的方法（例如，使用 Puppeteer MCP 服务器、iOS 模拟器 MCP 服务器，或手动将屏幕截图复制/粘贴到 Claude 中）。
2. 通过复制/粘贴或拖放图像，或为 Claude 提供图像文件路径，为 Claude 提供视觉模拟。
3. 让 Claude 在代码中实现设计，截取结果的屏幕截图，然后迭代，直到其结果与模拟匹配。
4. 当您满意时，请 Claude 承诺。

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

d. 安全的 YOLO 模式

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

让 Claude 运行任意命令是有风险的，并可能导致数据丢失、系统损坏，甚至数据泄露（例如，通过提示注入攻击）。为了最大限度地降低这些风险，请在无法访问 Internet 的容器中使用。您可以使用 Docker Dev Containers 遵循此参考实施。--dangerously-skip-permissions

e. 代码库 Q&A

在加入新代码库时，请使用 Claude Code 进行学习和探索。你可以问 Claude 的问题，就像在结对编程时问项目中的其他工程师一样。Claude 可以代理搜索代码库以回答一般问题，例如：

• 日志记录的工作原理是什么？
• 如何创建新的 API 终端节点？
• 第 134 行 是做什么的？async move { ... }foo.rs
• 可以处理哪些边缘情况？CustomerOnboardingFlowImpl
• 为什么我们打电话而不是拨打 333 号线？foo()bar()
• Java 中的第 334 行相当于什么？baz.py

在 Anthropic，以这种方式使用 Claude Code 已成为我们的核心入职工作流程，显著缩短了启动时间并减轻了其他工程师的负担。不需要特别提示！只需提出问题，Claude 就会探索代码以找到答案。

f. 使用 Claude 与 git 交互

Claude 可以有效地处理许多 git作。许多 Anthropic 工程师使用 Claude 进行 90%+ 的 git 交互：

• 搜索 git 历史记录以回答诸如“v1.2.3 中有哪些变化”、“谁拥有此特定功能”或“为什么此 API 是这样设计的？它有助于显式提示 Claude 查看 git history 来回答此类查询。
• 编写提交消息。 Claude 将自动查看您的更改和最近的历史记录，以在考虑所有相关上下文的情况下撰写消息
• 处理复杂的 git作，例如还原文件、解决变基冲突以及比较和嫁接补丁

g. 使用 Claude 与 GitHub 交互

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

• 创建拉取请求：Claude 理解简写 “pr” ，并将根据差异和周围上下文生成适当的提交消息。
• 为简单的代码审查注释实现一次性解决方案：只需告诉它修复 PR 上的注释（可选地给它更具体的说明），并在完成后推送回 PR 分支。
• 修复失败的构建或 Linter 警告
• 通过要求 Claude 循环访问未解决的 GitHub 问题，对未解决的问题进行分类和分类

这样就无需在自动执行日常任务时记住命令行语法。gh

h. 使用 Claude 处理 Jupyter 笔记本

Anthropic 的研究人员和数据科学家使用 Claude Code 来读取和写入 Jupyter 笔记本。Claude 可以解释输出（包括图像），从而提供一种快速浏览数据并与之交互的方法。没有必需的提示或工作流，但我们推荐的工作流是在 VS Code 中并排打开 Claude Code 和文件。.ipynb

您还可以要求 Claude 在向同事展示 Jupyter 笔记本之前对其进行清理或美学改进。明确地告诉它使笔记本或其数据可视化“美观”，这往往有助于提醒它，它正在针对人类的观看体验进行优化。

4. 优化您的工作流程

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

一个。在说明中具体

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。

这四个工具有助于修正路线：

• 让 Claude 在编码之前制定一个计划。明确告诉它不要编码，直到你确认它的计划看起来不错。
• 按 Esc 键可中断在任何阶段（思考、工具调用、文件编辑）保持 Claude，保留上下文以便重定向或扩展说明。
• 双击 Escape 可跳回历史记录、编辑上一个提示并探索不同的方向。您可以编辑提示并重复作，直到获得所需的结果。
• 要求 Claude 撤消更改，通常与选项 #2 结合使用，以采用不同的方法。

尽管 Claude Code 偶尔会在第一次尝试时完美地解决问题，但使用这些更正工具通常会更快地产生更好的解决方案。

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

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

g.将清单和暂存器用于复杂的工作流程

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

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

1. 告诉 Claude 运行 lint 命令并将所有结果错误（包括文件名和行号）写入 Markdown 清单
2. 指示 Claude 逐一解决每个问题，修复和验证，然后再检查并进入下一个问题

h.将数据传入 Claude

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

• 直接复制并粘贴到您的提示中（最常见的方法）
• 管道到 Claude Code （例如，），特别适用于日志、CSV 和大数据cat foo.txt | claude
• 告诉 Claude 通过 bash 命令、MCP 工具或自定义斜杠命令拉取数据
• 让 Claude 读取文件或获取 URL（也适用于图像）

大多数会议都涉及这些方法的组合。例如，您可以通过管道传入日志文件，然后告诉 Claude 使用工具提取其他上下文来调试日志。

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

Claude Code 包括用于非交互式上下文（如 CI、预提交钩子、构建脚本和自动化）的无头模式。将标志与提示一起使用以启用 Headless 模式，并用于流式处理 JSON 输出。-p--output-format stream-json

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

a. 使用 Claude 进行问题分类

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

b. 使用 Claude 作为 Linter

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

6. 使用多 Claude 工作流程升级

除了独立使用之外，一些最强大的应用程序还涉及并行运行多个 Claude 实例：

一个。让一个 Claude 编写代码;使用另一个 Claude 进行验证

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

1. 使用 Claude 编写代码
2. 在另一个终端中运行或启动第二个 Claude/clear
3. 让第二个 Claude 审阅第一个 Claude 的作品
4. 启动另一个 Claude（或再次）以读取代码和查看反馈/clear
5. 让这个 Claude 根据反馈编辑代码

您可以对测试执行类似的作：让一个 Claude 编写测试，然后让另一个 Claude 编写代码以使测试通过。您甚至可以让 Claude 实例相互通信，方法是为它们提供单独的工作便笺簿，并告诉它们要写入哪个实例和从哪个实例读取。

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

b.对存储库进行多次签出

Anthropic 的许多工程师不是等待 Claude 完成每个步骤，而是要做的是：

1. 在单独的文件夹中创建 3-4 个 git 签出
2. 在单独的终端选项卡中打开每个文件夹
3. 在每个文件夹中启动 Claude，其中包含不同的任务
4. 循环检查进度并批准/拒绝权限请求

c. 使用 git worktrees

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

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

1. 创建工作树：git worktree add ../project-feature-a feature-a
2. 在每个工作树中启动 Claude：cd ../project-feature-a && claude
3. 根据需要创建其他工作树（在新的终端选项卡中重复步骤 1-2）

一些提示：

• 使用一致的命名约定
• 为每个工作树维护一个终端选项卡
• 如果您在 Mac 上使用 iTerm2，请设置 Claude 需要注意时的通知
• 为不同的工作树使用单独的 IDE 窗口
• 完成后清理：git worktree remove ../project-feature-a

d. 将 Headless 模式与自定义线束结合使用

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

1. 扇出处理大型迁移或分析（例如，分析数百个日志中的情绪或分析数千个 CSV）：

1. 让 Claude 编写一个脚本来生成任务列表。例如，生成一个需要从框架 A 迁移到框架 B 的 2k 文件的列表。
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_commandyour_command
2. 就是这样！JSON 输出（可选）有助于提供结构，以便更轻松地进行自动化处理。

对于这两个使用案例，使用 flag 调试 Claude 调用可能会有所帮助。我们通常建议在生产环境中关闭详细模式以获得更清晰的输出。

内容中包含的图片若涉及版权问题，请及时与我们联系删除