Claude Code 最佳实践

Claude Code 刻意设计为低层次且无特定倾向，提供接近原始模型的访问权限，而不强制执行特定的工作流程。这种设计理念创造了一个灵活、可定制、可脚本化和安全的强大工具。

虽然功能强大，但这种灵活性为新接触代理编码工具的工程师带来了一定的学习曲线——至少在他们开发出自己的最佳实践之前。

本文概述一些已被证明有效的通用模式，适用于 Anthropic 内部团队以及在各种代码库、语言和环境中使用 Claude Code 的外部工程师。

这些建议并非一成不变或通用的。请将它们视为起点。我们鼓励您进行实验，找到最适合您的做法！

定制您的设置

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

创建 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 命令的目录的上级目录。这在单体仓库中特别有用，您可能从 root/foo 运行 claude，并在 root/CLAUDE.md 和 root/foo/CLAUDE.md 中都有 CLAUDE.md 文件。这两个文件都会被自动拉入上下文。
• 运行 claude 命令的目录的子目录。与上述相反，在这种情况下，Claude 会在您处理子目录中的文件时按需拉入 CLAUDE.md 文件。
• 您的主目录（~/.claude/CLAUDE.md），适用于所有 claude 会话。

当您运行 /init 命令时，Claude 会自动为您生成一个 CLAUDE.md 文件。

调优您的 CLAUDE.md 文件

您的 CLAUDE.md 文件会成为 Claude 提示的一部分，因此应像优化常用提示一样对其进行精炼。常见的错误是添加大量内容而不迭代其有效性。花时间实验，确定哪些内容能从模型中获得最佳的指令遵循效果。

您可以手动向 CLAUDE.md 添加内容，或按下 # 键给 Claude 一个指令，Claude 会自动将其纳入相关的 CLAUDE.md 文件。许多工程师频繁使用 # 键来记录命令、文件和风格指南，同时将 CLAUDE.md 的更改纳入提交中，以便团队成员也能受益。

在 Anthropic，我们偶尔会通过提示优化器运行 CLAUDE.md 文件，并经常调整指令（例如，添加“IMPORTANT”或“YOU MUST”以强调）以提高遵循度。

管理 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（我们建议将前者纳入版本控制以与团队共享）。
• 使用 --allowedTools CLI 标志进行会话特定的权限设置。

如果使用 GitHub，安装 gh CLI

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

给 Claude 更多工具

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

将 Claude 与 bash 工具一起使用

Claude Code 继承了您的 bash 环境，可以访问您的所有工具。虽然 Claude 了解常见的 Unix 工具和 gh 等程序，但它不知道您的自定义 bash 工具，除非您提供说明：

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

将 Claude 与 MCP 一起使用

Claude Code 既是 MCP 服务器也是客户端。作为客户端，它可以连接到任意数量的 MCP 服务器，以三种方式访问它们的工具：

• 项目配置（在该目录运行 Claude Code 时可用）。
• 全局配置（在所有项目中可用）。
• .mcp.json 文件（对在您的代码库中工作的任何人可用）。例如，您可以将 Puppeteer 和 Sentry 服务器添加到 .mcp.json，以便每个在您的仓库中工作的工程师都能开箱即用。

在使用 MCP 时，启动 Claude 时使用 --mcp-debug 标志有助于识别配置问题。

使用自定义斜杠命令

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

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

例如，以下是一个可用于自动拉取和修复 GitHub 问题的斜杠命令：

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

请遵循以下步骤：

1. 使用 `gh issue view` 获取问题详情
2. 理解问题描述中的问题
3. 在代码库中搜索相关文件
4. 实现修复问题的必要更改
5. 编写并运行测试以验证修复
6. 确保代码通过 linting 和类型检查
7. 创建描述性的提交消息
8. 推送并创建拉取请求

请记住使用 GitHub CLI（`gh`）处理所有与 GitHub 相关的任务。

将上述内容放入 .claude/commands/fix-github-issue.md，即可在 Claude Code 中作为 /project:fix-github-issue 命令使用。例如，您可以使用 /project:fix-github-issue 1234 让 Claude 修复问题 #1234。同样，您可以将个人命令添加到 ~/.claude/commands 文件夹，使其在所有会话中可用。

尝试常见工作流程

Claude Code 不强制执行特定工作流程，赋予您灵活使用的自由。在这种灵活性范围内，我们的用户社区中涌现了几个成功使用 Claude Code 的模式：

探索、计划、编码、提交

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

1. 要求 Claude 阅读相关文件、图片或 URL，提供通用指引（“读取处理日志的文件”）或具体文件名（“读取 logging.py”），但明确告诉它暂时不要编写任何代码。
2. 在此步骤中，尤其对于复杂问题，强烈建议使用子代理。告诉 Claude 使用子代理验证细节或调查特定问题，特别是在对话或任务的早期，通常可以在不损失效率的情况下保留上下文可用性。
3. 要求 Claude 为特定问题制定计划。我们建议使用“think”一词触发扩展思考模式，这会为 Claude 提供额外的计算时间以更彻底地评估替代方案。以下短语直接映射到系统中的思考预算增加级别：“think” < “think hard” < “think harder” < “ultrathink”。每个级别为 Claude 分配越来越多的思考预算。
4. 如果此步骤的结果看起来合理，您可以让 Claude 创建一个文档或 GitHub 问题记录其计划，以便在实现（第 3 步）不符合预期时可以重置到此点。
5. 要求 Claude 用代码实现其解决方案。这也是一个好时机，要求它在实现解决方案的各个部分时明确验证其合理性。
6. 要求 Claude 提交结果并创建拉取请求。如果相关，这也是让 Claude 更新 README 或变更日志以解释其操作的好时机。

第 1-2 步至关重要——如果没有这些步骤，Claude 倾向于直接开始编码解决方案。虽然有时这是您想要的，但要求 Claude 先研究和计划对于需要深入思考的问题会显著提高性能。

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

这是 Anthropic 内部最受欢迎的工作流程，适用于易于通过单元测试、集成测试或端到端测试验证的更改。测试驱动开发（TDD）在代理编码中变得更加强大：

1. 要求 Claude 根据期望的输入/输出对编写测试。明确说明您正在进行测试驱动开发，以避免它为尚未存在于代码库中的功能创建模拟实现。
2. 告诉 Claude 运行测试并确认它们失败。明确告诉它在此阶段不要编写任何实现代码通常很有帮助。
3. 当您对测试满意时，要求 Claude 提交测试。
4. 要求 Claude 编写通过测试的代码，指示它不要修改测试。告诉 Claude 继续迭代直到所有测试通过。通常需要几次迭代，Claude 会编写代码、运行测试、调整代码并再次运行测试。
5. 在此阶段，要求它使用独立子代理验证实现没有过度拟合测试可能会有帮助。
6. 当您对更改满意时，要求 Claude 提交代码。

Claude 在有明确目标（例如视觉模型、测试用例或其他输出）时表现最佳。通过提供测试等预期输出，Claude 可以进行更改、评估结果并逐步改进直到成功。

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

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

1. 为 Claude 提供截取浏览器截图的方法（例如，使用 Puppeteer MCP 服务器、iOS 模拟器 MCP 服务器，或手动将截图复制/粘贴到 Claude）。
2. 为 Claude 提供视觉模型，通过复制/粘贴或拖放图片，或提供图片文件路径。
3. 要求 Claude 用代码实现设计，截取结果的截图，并迭代直到结果与模型匹配。
4. 当您满意时，要求 Claude 提交。

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

安全 YOLO 模式

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

让 Claude 运行任意命令有风险，可能导致数据丢失、系统损坏甚至数据泄露（例如，通过提示注入攻击）。为降低这些风险，请在没有网络访问的容器中使用 --dangerously-skip-permissions。您可以参考此 Docker 开发容器实现。

代码库问答

在熟悉新代码库时，使用 Claude Code 进行学习和探索。您可以向 Claude 提出与项目中另一位工程师配对编程时会问的相同问题。Claude 可以代理搜索代码库，回答以下通用问题：

• 日志记录是如何工作的？
• 如何创建新的 API 端点？
• foo.rs 第 134 行的 async move { ... } 做什么？
• CustomerOnboardingFlowImpl 处理了哪些边缘情况？
• 为什么在第 333 行调用 foo() 而不是 bar()？
• baz.py 第 334 行的 Java 等效代码是什么？

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

使用 Claude 与 git 交互

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

• 搜索 git 历史，回答如“v1.2.3 中包含了哪些更改？”、“谁拥有这个特定功能？”或“这个 API 为什么这样设计？”等问题。明确提示 Claude 查看 git 历史以回答此类问题会有帮助。
• 编写提交消息。Claude 会自动查看您的更改和近期历史，综合所有相关上下文撰写提交消息。
• 处理复杂的 git 操作，如恢复文件、解决变基冲突，以及比较和嫁接补丁。

使用 Claude 与 GitHub 交互

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

• 创建拉取请求：Claude 理解“pr”简写，并会根据差异和周围上下文生成适当的提交消息。
• 实现一次性代码审查评论修复：只需告诉它修复您的拉取请求上的评论（可选地，提供更具体的指令），并在完成后推送到拉取请求分支。
• 修复失败的构建或 linter 警告。
• 分类和分拣开放问题，通过要求 Claude 循环遍历开放的 GitHub 问题。

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

使用 Claude 处理 Jupyter 笔记本

Anthropic 的研究人员和数据科学家使用 Claude Code 读取和编写 Jupyter 笔记本。Claude 可以解释输出，包括图片，提供了快速探索和交互数据的方法。没有特定的提示或工作流程要求，但我们推荐的工作流程是在 VS Code 中并排打开 Claude Code 和 .ipynb 文件。

您还可以要求 Claude 在向同事展示之前清理或美化您的 Jupyter 笔记本。明确告诉它使笔记本或其数据可视化“美观”通常有助于提醒它优化人类查看体验。

优化您的工作流程

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

a. 指令具体化

Claude Code 的成功率在指令更具体时显著提高，特别是在第一次尝试时。提前提供清晰的指令可以减少后续修正的需要。

例如：

Claude 可以推断意图，但无法读心。具体化指令能更好地与预期对齐。

为 Claude 提供图片

Claude 在处理图片和图表方面表现出色，支持以下几种方法：

• 粘贴截图（提示：在 macOS 上按 cmd+ctrl+shift+4 截图到剪贴板，然后按 ctrl+v 粘贴。注意，这不是通常的 cmd+v 粘贴，且在远程操作时无效。）
• 直接拖放图片到提示输入中。
• 提供图片文件路径。

这在以设计模型为参考进行 UI 开发，以及用于分析和调试的可视化图表时特别有用。如果您未将视觉内容添加到上下文中，明确告诉 Claude 结果的美观程度有多重要仍会有帮助。

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

使用 tab 补全快速引用仓库中的文件或文件夹，帮助 Claude 找到或更新正确的资源。

为 Claude 提供 URL

在提示中粘贴特定 URL，供 Claude 获取和阅读。为避免对同一域（例如，docs.foo.com）的重复权限提示，使用 /permissions 将域添加到您的允许列表。

尽早且经常进行纠正

虽然自动接受模式（按 shift+tab 切换）允许 Claude 自主工作，但作为积极的协作者并引导 Claude 的方法通常会获得更好的结果。您可以在开始时详细向 Claude 解释任务，也可以在任何时候进行纠正。

以下四种工具可帮助纠正：

• 要求 Claude 在编码前制定计划。明确告诉它在您确认计划合理之前不要编码。
• 按 Escape 键中断 Claude 在任何阶段（思考、工具调用、文件编辑），保留上下文以便您可以重新定向或扩展指令。
• 双击 Escape 键回溯历史，编辑之前的提示，探索不同的方向。您可以编辑提示并重复直到获得想要的结果。
• 要求 Claude 撤销更改，通常与选项 2 结合使用以尝试不同方法。

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

使用 /clear 保持上下文专注

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

对复杂工作流程使用清单和草稿

对于大型任务（如代码迁移、修复大量 lint 错误或运行复杂构建脚本），通过让 Claude 使用 Markdown 文件（甚至 GitHub 问题！）作为清单和工作草稿，可以提高性能：

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

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

向 Claude 传递数据

为 Claude 提供数据的几种方法：

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

大多数会话涉及这些方法的组合。例如，您可以管道输入日志文件，然后告诉 Claude 使用工具拉取额外上下文以调试日志。

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

Claude Code 包括无头模式，适用于非交互式上下文，如 CI、预提交钩子、构建脚本和自动化。使用 -p 标志和提示启用无头模式，使用 --output-format stream-json 进行流式 JSON 输出。

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

使用 Claude 进行问题分拣

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

使用 Claude 作为 linter

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

使用多 Claude 工作流程提升效率

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

一个 Claude 编写代码，另一个 Claude 验证

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

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

您可以对测试做类似的事情：让一个 Claude 编写测试，另一个 Claude 编写通过测试的代码。您甚至可以让 Claude 实例通过为它们提供单独的工作草稿并指定写入和读取的草稿来相互通信。

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

拥有多个仓库检出

与其等待 Claude 完成每个步骤，Anthropic 的许多工程师会：

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

使用 git 工作树

对于多个独立任务，这种方法比多个检出更轻量。Git 工作树允许您从同一仓库检出多个分支到单独的目录。每个工作树拥有独立的工作目录和文件，同时共享相同的 Git 历史和 reflog。

使用 git 工作树可以让您在项目的不同部分同时运行多个 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

使用无头模式和自定义工具

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

1. 分发处理大型迁移或分析（例如，分析数百个日志的情感或分析数千个 CSV）：
2. 让 Claude 编写脚本生成任务列表。例如，生成需要从框架 A 迁移到框架 B 的 2k 个文件列表。
3. 循环遍历任务，为每个任务以编程方式调用 Claude，并为其提供任务和可使用的工具集。例如：claude -p “将 foo.py 从 React 迁移到 Vue。完成后，如果成功，必须返回字符串 OK，如果任务失败，返回 FAIL。” --allowedTools Edit Bash(git commit:*)
4. 多次运行脚本并优化提示以获得预期结果。
5. 管道化将 Claude 集成到现有数据/处理管道：
6. 调用 claude -p “<your prompt>” --json | your_command，其中 your_command 是处理管道的下一步。
7. 就这样！JSON 输出（可选）可为自动化处理提供结构。

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