Logo智人飞扬
Claude Code、最佳实践·

Claude Code 最佳实践 [译]

了解如何利用 Claude Code 提高编码效率和工作流程，通过最佳实践和创新技巧优化您的开发体验。
Aa Boris Cherny

Engineering at Anthropic

我们最近发布了 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 记住的其他信息

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，并在 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，我们偶尔会通过提示改进器运行 CLAUDE.md 文件，通常会调整指令（例如，通过"重要"或"您必须"等术语增加强调）以提高顺应性。

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

默认情况下，Claude Code 会请求任何可能修改系统的操作的权限，例如文件写入、许多 bash 命令、MCP 工具等。我们故意以这种保守的方式设计 Claude Code，以优先考虑安全性。您可以自定义允许列表，以允许您知道是安全的附加工具，或者允许易于撤销的潜在不安全工具（例如，文件编辑、git commit）。

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

  • 在会话期间被提示时选择「始终允许」。
  • 在启动 Claude Code 后使用 /permissions 命令，向允许列表添加或删除工具。例如，您可以添加 Edit 以始终允许文件编辑，或 Bash(git commit:*) 以允许 git 提交，或 mcp__puppeteer__puppeteer_navigate 以允许使用 Puppeteer MCP 服务器进行导航。
  • 手动编辑您的 .claude/settings.json 或 ~/.claude.json（我们建议将前者纳入源控制以供团队共享）。
  • 在 CLI 中使用 --allowedTools 标志以获得特定会话的权限。

d. 如果使用 GitHub，则安装 gh CLI

Claude 知道如何使用 gh CLI 与 GitHub 交互，以创建问题、打开拉取请求、读取评论等。没有安装 gh，Claude 仍然可以使用 GitHub API 或 MCP 服务器（如果您已安装它）。

2. 为 Claude 提供更多工具

Claude 可以访问您的 shell 环境，您可以为其构建一系列便利的脚本和功能，就像为自己一样。它还可以通过 MCP 和 REST API 利用更复杂的工具。

a. 使用 bash 工具与 Claude 一起工作

Claude Code 继承了您的 bash 环境，使其可以访问所有工具。虽然 Claude 知道常见的工具，例如 unix 工具和 gh，但如果没有指令，它不会知道您的自定义 bash 工具：

  1. 告诉 Claude 工具名称和使用示例
  2. 告诉 Claude 运行 --help 查看工具文档
  3. 在 CLAUDE.md 中记录经常使用的工具

b. 使用 MCP 与 Claude 一起工作

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. 确保代码通过 lint 检查和类型检查
7. 创建描述性提交信息
8. 提交并创建 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 不强加具体的工作流程，使您能够灵活使用。在这种灵活性所允许的范围内，多个成功的使用模式已在我们的用户社区中浮现：

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

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

  1. 请 Claude 阅读相关的文件、图像或网址，提供一般提示（如「阅读处理日志的文件」）或特定文件名（如「阅读 logging.py」），但明确告诉它暂时不要写代码。
    • 这是工作流程中的一个部分，您应该考虑强烈使用子代理，尤其是对于复杂问题。告诉 Claude 使用子代理来验证细节或调查它可能会有的特定问题，特别是在对话或任务的早期阶段，通常能保持上下文的可用性，而不会在效率上造成太大损失。
  2. 请 Claude 制定特定问题的计划。我们建议使用「思考」一词来触发扩展思维模式，这将为 Claude 提供更多的计算时间，以更全面地评估替代方案。这些特定的短语直接映射到系统中的思维预算递增：「思考」 < 「仔细思考」 < 「深入思考」 < 「超思考」。每一个级别分配给 Claude 使用的思维预算逐渐增加。
    • 如果这一步的结果看起来合理，您可以让 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 才能编写代码、运行测试、调整代码并再次运行测试。
    • 此时，询问它是否能用独立的子代理验证实现是否过度拟合于测试结果。
  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 --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()？
  • 在 Java 中，baz.py 第 334 行的等效内容是什么？

在 Anthropic，以这种方式使用 Claude Code 已成为我们的核心入职工作流程，显著提高了熟悉时间，减少了其他工程师的负担。无需特殊提示！只需问问题，Claude 将探索代码以找到答案。

f. 使用 Claude 与 git 互动

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

  • 搜索 git 历史 以回答「哪些更改被转入 v1.2.3？」、「谁负责这个特定功能？」或「为什么这个 API 是这样设计的？」请明确提示 Claude 查看 git 历史以回答这些查询。
  • 编写提交信息。Claude 将查看您的更改和最近的历史记录，以自动编写一条消息，将所有相关上下文考虑在内。
  • 处理复杂的 git 操作 ，例如还原文件、解决变基冲突，以及比较和合并补丁。

g. 使用 Claude 与 GitHub 互动

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

  • 创建拉取请求：Claude 理解缩写「pr」，并将根据差异和周围上下文生成适当的提交消息。
  • 为简单的代码审查评论实现一次性解决方案：只需告诉它修复您 PR 上的评论（可选择，给出更具体的指示），并在完成后推送回 PR 分支。
  • 修复构建失败 或 linter 警告。
  • 通过要求 Claude 循环开放的 GitHub 问题来分类和筛选问题。

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

h. 使用 Claude 与 Jupyter 笔记本互动

Anthropic 的研究人员和数据科学家使用 Claude Code 读取和写入 Jupyter 笔记本。Claude 可以解释输出，包括图像，提供快速方式来探索和与数据互动。没有强制的提示或工作流程，但我们推荐的一种工作流程是将 Claude Code 和 .ipynb 文件并排打开在 VS Code 中。

您还可以在向同事展示之前，请 Claude 清理或美化您的 Jupyter 笔记本。特别明确要求它使笔记本或其数据可视化「美观」可以帮助提醒它优化以适应人类观看体验。

4. 优化您的工作流程

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

a. 提供具体的指示

Claude Code 的成功率显著提高，尤其是在首次尝试时，具体指示尤为关键。清晰的方向可以减少后续需要的修正。

例如：

不佳良好
为 foo.py 添加测试为 foo.py 编写一个新测试用例，涵盖用户注销时的边界情况。避免使用模拟
为什么 ExecutionFactory 的 API 如此奇怪？查看 ExecutionFactory 的 git 历史并总结其 API 是如何形成的
添加日历小部件查看主页上现有小部件的实现，以了解模式，尤其是代码和接口如何被分开。HotDogWidget.php 是一个很好的起点。然后，按照该模式实现一个新的日历小部件，让用户选择一个月份并向前/向后分页以选择年份。仅使用除了代码库中已经使用的库之外的其他库构建。

Claude 能够推断意图，但它不能读心。具体性有助于更好地与预期对接。

b. 给 Claude 提供图像

Claude 在处理图像和图表方面表现出色，可以通过多种方式实现：

  • 贴上屏幕截图（小技巧：在 macOS 中按 cmd+ctrl+shift+4 截屏到剪贴板，然后 ctrl+v 粘贴。请注意，这不是通常使用的 cmd+v，在远程情况下也无效。）
  • 直接拖放图像到提示输入中
  • 提供文件路径，以引用图像

这在使用设计模拟作为 UI 开发的参考点以及用于分析和调试的可视化图表时非常有用。如果没有向上下文添加视觉效果，明确告知 Claude 输出的重要性也是有帮助的。

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

使用 Tab 自动补全快速引用您代码库中的文件或文件夹，帮助 Claude 找到或更新正确的资源。

d. 给 Claude 提供网址

在提示中粘贴具体的 URL，以便 Claude 获取和读取。为避免对相同域（例如，docs.foo.com）的权限提示，使用 /permissions 将域添加到您的允许列表。

e. 及早并频繁地进行修正

虽然自动接受模式（shift+tab 切换）允许 Claude 自主工作，但通常通过积极协作和指导 Claude 的方法能获得更好的结果。在一开始充分解释任务给 Claude，能够取得最佳结果，但在任何时间都可以对 Claude 进行修正。

以下四个工具有助于修正：

  • 在编码之前请 Claude 制定计划。明确告诉它在确认计划看起来良好之前不要编码。
  • 按 Escape 键以中断 Claude 在任何阶段（思考、工具调用或输出）。中断后，您可以给 Claude 指导或让它恢复。
  • 在消息中给 Claude 动态反馈。
  • 使用其他 Claude 会话来验证输出。当 Claude 生成复杂的输出时，您可以打开另一个会话，粘贴该输出，并询问第二个 Claude 是否发现任何问题。

对于时间敏感的任务，我们建议多次运行 Claude 并比较结果，而不是花费时间修正单个会话。

f. 使用清单和暂存板

Claude 可以帮助您自动化重复性任务，包括管理清单和暂存板。这些对于跟踪待办事项、记录已知问题或在没有用户监督的情况下自动执行长期任务特别有用。

例如，您可以请 Claude 创建一个清单来跟踪完成大型功能所需的所有步骤，并在完成每个步骤时勾选它们。或者，您可以请 Claude 创建一个暂存板来跟踪它在重构过程中遇到的问题。

g. 使用无头模式进行自动化

对于非交互式任务，您可以使用 -p 标志运行 Claude 在无头模式下，这样它将输出结果直接到终端而不进入交互界面。这对于脚本化或自动化工作流程特别有用。

例如：

claude -p "检查这个 Python 文件的语法错误并修复它们" --file main.py

h. 利用扩展思维和多 Claude 工作流程

对于复杂的问题，您可以使用多个 Claude 会话来处理不同的方面：

  • 一个会话用于探索和理解问题
  • 另一个会话用于实现解决方案
  • 第三个会话用于审查和改进输出

这种方法可以提供更好的结果，因为每个会话都可以专注于特定的任务而不会被其他上下文分散注意力。

5. 高级技巧

a. 使用 git worktrees 进行并行开发

当您需要在多个分支上同时工作时，可以使用 git worktrees：

git worktree add ../my-project-feature feature-branch
cd ../my-project-feature
claude

这允许您在不同的工作目录中运行多个 Claude 会话，每个会话都在不同的分支上工作。

b. 程序化任务处理

您可以创建脚本来自动化常见的 Claude 任务：

#!/bin/bash
# 自动化代码审查脚本
echo "正在对 $1 进行代码审查..."
claude -p "请审查这个文件的代码质量、潜在错误和改进建议" --file "$1"

c. 与 CI/CD 集成

Claude Code 可以集成到您的 CI/CD 流水线中：

# GitHub Actions 示例
- name: 代码审查
  run: |
    claude -p "审查此 PR 的代码更改并提供反馈" --pr-number ${{ github.event.number }}

d. 自定义环境变量

您可以设置环境变量来配置 Claude 的行为：

export CLAUDE_MAX_TOKENS=8192
export CLAUDE_TEMPERATURE=0.1
export CLAUDE_MODEL=claude-3-5-sonnet-20241022

这些变量可以帮助您根据不同的任务调整 Claude 的行为。

结论

Claude Code 是一个强大而灵活的工具，可以显著提高您的编码效率和工作流程。通过遵循这些最佳实践，您可以最大化其潜力并将其无缝集成到您的开发工作流程中。

记住，这些建议只是起点。我们鼓励您进行实验，找出最适合您的具体需求和工作风格的方法。Claude Code 的真正力量在于其适应性——它可以成为您想要的任何工具。

随着您对 Claude Code 的使用越来越熟练，您会发现更多创新的方式来利用其功能。不要害怕尝试新的工作流程或推动工具的边界。毕竟，最好的实践往往来自实验和迭代。

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

我们是如何构建多智能体研究系统的 [译]

这篇文章讲述了构建多智能体研究系统的关键经验和教训，特别是在系统架构、工具设计和提示工程方面的深刻洞见。

迎接经验时代 [译]

探讨人工智能即将进入的新时代，在这个时代中，代理将通过经验学习获得超人类能力

© 2025 智人飞扬