Claude Code 最佳实践（中文翻译）

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

Claude Code 有意设计为低层级且无强制规范，几乎提供了对模型的原始访问，而不强加特定的工作流。这种设计理念带来了灵活、可定制、可脚本化且安全的强大工具。虽然功能强大，但这种灵活性也为新接触代理式编程工具的工程师带来了一定的学习曲线——至少在他们形成自己的最佳实践之前是如此。

本文总结了一些被证明有效的通用模式，既适用于 Anthropic 内部团队，也适用于在各种代码库、语言和环境中使用 Claude Code 的外部工程师。本文的建议并非一成不变或普遍适用；请将其视为起点。我们鼓励你大胆尝试，找到最适合自己的方式！

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

1. 自定义你的设置

Claude Code 是一款代理式编程助手，会自动将上下文拉入提示中。收集这些上下文会消耗时间和 tokens，但你可以通过环境调优来优化这一过程。

a. 创建 ⁠CLAUDE.md⁠ 文件

⁠CLAUDE.md⁠ 是一个特殊文件，Claude 在开始对话时会自动拉入上下文。这是记录以下内容的理想场所：
• 常用 bash 命令
• 核心文件和工具函数
• 代码风格指南
• 测试说明
• 仓库规范（如分支命名、合并 vs. rebase 等）
• 开发环境设置（如 pyenv 使用、可用编译器等）
• 项目中特有的异常行为或警告
• 你希望 Claude 记住的其他信息

⁠CLAUDE.md⁠ 没有固定格式。我们建议保持简洁、易读。例如：# Bash 命令

• npm run build: 构建项目
• npm run typecheck: 运行类型检查器

代码风格

• 使用 ES modules（import/export）语法，不用 CommonJS（require）
• 尽量解构导入（如 import { foo } from 'bar'）

工作流

• 完成一系列代码更改后务必进行类型检查
• 为了性能，优先运行单个测试而不是整个测试套件

你可以将 ⁠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⁠
• 你的 home 文件夹（⁠~/.claude/CLAUDE.md⁠），适用于所有 claude 会话

运行 ⁠/init⁠ 命令时，Claude 会自动为你生成 ⁠CLAUDE.md⁠。

b. 调优你的 ⁠CLAUDE.md⁠ 文件

⁠CLAUDE.md⁠ 会成为 Claude 提示的一部分，因此应像常用提示一样不断优化。常见错误是添加了大量内容却未迭代其有效性。请花时间实验，找出最能提升模型指令遵循性的内容。

你可以手动添加内容，也可以按 ⁠#⁠ 键给 Claude 下达指令，Claude 会自动将其写入相关的 ⁠CLAUDE.md⁠。许多工程师在编码时频繁用 ⁠#⁠ 记录命令、文件和风格指南，并将 ⁠CLAUDE.md⁠ 的更改纳入提交，方便团队成员共享。

在 Anthropic，我们偶尔会用提示优化器处理 ⁠CLAUDE.md⁠，并经常调整指令（如用“IMPORTANT”或“YOU MUST”加重语气）以提升遵循度。

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

默认情况下，Claude Code 对任何可能修改系统的操作（如文件写入、许多 bash 命令、MCP 工具等）都会请求权限。我们有意采用这种保守策略以优先保证安全。你可以自定义允许列表，添加你认为安全的工具，或允许易于撤销的潜在不安全工具（如文件编辑、⁠git commit⁠）。

管理允许工具有四种方式：
• 会话中被提示时选择“Always allow”
• 启动 Claude Code 后用 ⁠/permissions⁠ 命令 添加或移除允许的工具。例如，添加 ⁠Edit⁠ 以始终允许文件编辑，⁠Bash(git commit:*)⁠ 允许 git 提交，或 ⁠mcp__puppeteer__puppeteer_navigate⁠ 允许用 Puppeteer MCP server 导航
• 手动编辑 ⁠.claude/settings.json⁠ 或 ⁠~/.claude.json⁠（推荐将前者提交到源码库以便团队共享）
• 用 ⁠--allowedTools⁠ CLI 标志 为单次会话指定权限

d. 如果用 GitHub，安装 gh CLI

Claude 能用 ⁠gh⁠ CLI 与 GitHub 交互，创建 issue、打开 PR、读取评论等。没有安装 ⁠gh⁠ 时，Claude 仍可用 GitHub API 或 MCP server（如已安装）。

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 server 也是 client。作为 client，可连接任意数量的 MCP server，通过三种方式访问其工具：
• 项目配置中（在该目录运行 Claude Code 时可用）
• 全局配置中（所有项目可用）
• 提交到 ⁠.mcp.json⁠ 文件（任何在你代码库工作的成员都可用）。例如，你可以在 ⁠.mcp.json⁠ 添加 Puppeteer 和 Sentry server，方便每位工程师开箱即用。

使用 MCP 时，建议用 ⁠--mcp-debug⁠ 标志启动 Claude，便于排查配置问题。

c. 使用自定义斜杠命令

对于重复性工作流（如调试循环、日志分析等），可将提示模板存储在 ⁠.claude/commands⁠ 文件夹下的 Markdown 文件中。输入 ⁠/⁠ 时，这些命令会出现在斜杠命令菜单中。你可以将这些命令提交到 git，方便团队成员使用。

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

例如，以下斜杠命令可自动拉取并修复 GitHub issue：请分析并修复 GitHub issue: $ARGUMENTS。

请按以下步骤操作：

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

请务必用 GitHub CLI (gh) 完成所有 GitHub 相关任务。

将上述内容放入 ⁠.claude/commands/fix-github-issue.md⁠，即可通过 ⁠/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”），但要明确说明暂时不要写代码。
a. 这一步建议充分利用子代理，尤其在处理复杂问题时。让 Claude 用子代理核查细节或调查问题，尤其在对话或任务初期，有助于保持上下文可用性，且不会明显降低效率。
2. 让 Claude 制定解决特定问题的计划。建议用“think”一词触发扩展思考模式，Claude 会获得更多计算时间以更全面地评估方案。具体短语会映射到不同的思考预算：“think” < “think hard” < “think harder” < “ultrathink”，每级分配的思考预算递增。
a. 如果结果合理，可让 Claude 创建文档或 GitHub issue 记录计划，便于在实现（第 3 步）不理想时回退。
3. 让 Claude 实现方案代码。此时也可让其在实现过程中明确验证方案的合理性。
4. 让 Claude 提交结果并创建 PR。如有需要，也可让 Claude 更新 README 或 changelog，说明所做更改。

第 1-2 步至关重要——否则 Claude 往往会直接跳到编码。虽然有时你确实需要这样，但让 Claude 先调研和规划，能显著提升复杂问题的表现。

b. 先写测试再编码，迭代提交

适合用单元、集成或端到端测试易于验证的更改。测试驱动开发（TDD）在代理式编程中更为强大：
1. 让 Claude 根据预期输入/输出对写测试。明确说明你在做 TDD，这样 Claude 就不会为尚未实现的功能写 mock 实现。
2. 让 Claude 运行测试并确认失败。此时明确要求不要写实现代码通常很有帮助。
3. 对测试满意后让 Claude 提交测试。
4. 让 Claude 编写通过测试的代码，并要求不要修改测试。让 Claude 持续迭代，直到所有测试通过。通常需要几轮 Claude 编写代码、运行测试、调整代码、再运行测试。
a. 此阶段可让独立子代理验证实现是否过拟合测试用例。
5. 对更改满意后让 Claude 提交代码。

Claude 在有明确目标（如可视化 mock、测试用例或其他输出）时表现最佳。通过提供期望输出，Claude 能不断修改、评估并逐步完善，直到成功。

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

类似测试工作流，你可以为 Claude 提供可视化目标：
1. 为 Claude 提供浏览器截图方式（如 Puppeteer MCP server、iOS 模拟器 MCP server，或手动复制/粘贴截图到 Claude）。
2. 通过复制/粘贴、拖拽图片或提供图片路径，给 Claude 可视化 mock。
3. 让 Claude 实现设计、截图结果并迭代，直到结果与 mock 匹配。
4. 满意后让 Claude 提交。

像人类一样，Claude 的输出经过 2-3 轮迭代后通常会显著提升。为 Claude 提供可见输出工具，效果最佳。

d. 安全 YOLO 模式

你可以用 ⁠claude --dangerously-skip-permissions⁠ 跳过所有权限检查，让 Claude 不间断地工作直至完成。适合修复 lint 错误或生成样板代码等工作流。

让 Claude 任意运行命令有风险，可能导致数据丢失、系统损坏，甚至数据泄露（如提示注入攻击）。为降低风险，建议在无网络访问的容器中用 ⁠--dangerously-skip-permissions⁠。可参考 Docker Dev Containers 的实现。

e. 代码库问答

新入职时，可用 Claude Code 学习和探索代码库。你可以像与项目工程师结对编程时一样向 Claude 提问。Claude 会代理式地搜索代码库，回答如：
• 日志是如何工作的？
• 如何新增 API endpoint？
• ⁠foo.rs⁠ 第 134 行的 ⁠async move { ... }⁠ 有什么作用？
• ⁠CustomerOnboardingFlowImpl⁠ 处理了哪些边界情况？
• 为什么第 333 行调用 ⁠foo()⁠ 而不是 ⁠bar()⁠？
• ⁠baz.py⁠ 第 334 行在 Java 中的等价实现是什么？

在 Anthropic，这已成为核心入职流程，显著提升了上手速度，减轻了其他工程师负担。无需特殊提示！直接提问，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 交互：
• 创建 PR：Claude 理解“pr”简写，会根据 diff 和上下文生成合适的提交信息。
• 一键解决简单代码审查评论：只需让其修复 PR 上的评论（可选补充更具体指令），并推送回 PR 分支。
• 修复构建失败或 linter 警告
• 对 open issue 分类和分流，让 Claude 循环处理所有 open issue

这样无需记住 ⁠gh⁠ 命令行语法，自动化日常任务。

h. 用 Claude 处理 Jupyter notebook

Anthropic 的研究人员和数据科学家用 Claude Code 读写 Jupyter notebook。Claude 能解释输出（包括图片），为数据探索和交互提供快捷方式。无强制提示或工作流，推荐在 VS Code 并排打开 Claude Code 和 ⁠.ipynb⁠ 文件。

你还可以让 Claude 优化 notebook 或数据可视化的美观性，尤其在向同事展示前。明确要求“美观”有助于 Claude 优化人类观感。

4. 优化你的工作流

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

a. 指令要具体

Claude Code 在首次尝试时，指令越具体，成功率越高。明确指令能减少后续修正。

例如：

不佳

优秀

add tests for foo.py

write a new test case for foo.py, covering the edge case where the user is logged out. avoid mocks

why does ExecutionFactory have such a weird api?

look through ExecutionFactory’s git history and summarize how its api came to be

add a calendar widget

look at how existing widgets are implemented on the home page to understand the patterns and specifically how code and interfaces are separated out. HotDogWidget.php is a good example to start with. then, follow the pattern to implement a new calendar widget that lets the user select a month and paginate forwards/backwards to pick a year. Build from scratch without libraries other than the ones already used in the rest of the codebase.

Claude 能推断意图，但无法读心。具体说明有助于更好地满足预期。

b. 给 Claude 图片

Claude 通过多种方式善于处理图片和图表：
• 粘贴截图（小技巧：macOS 下用 cmd+ctrl+shift+4 截图到剪贴板，再用 ctrl+v 粘贴。注意不是常用的 cmd+v，且远程时无效）
• 直接拖拽图片到输入框
• 提供图片文件路径

这对 UI 开发时用设计稿做参考、分析和调试可视化图表特别有用。即使不加视觉内容，也建议明确告知 Claude 结果的美观性很重要。

c. 明确提及要处理的文件

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

d. 给 Claude 提供 URL

在提示中粘贴具体 URL，Claude 会自动拉取和阅读。为避免对同一域名反复请求权限（如 docs.foo.com），可用 ⁠/permissions⁠ 将域名加入允许列表。

e. 及时纠正方向

虽然自动接受模式（shift+tab 切换）让 Claude 自动工作，但主动协作和引导 Claude 通常能获得更好结果。你可以在任务开始时详细说明，也可以随时纠正 Claude 的方向。

以下四种工具有助于纠正：
• 让 Claude 先制定计划，明确要求未确认前不编码
• 按 Escape 随时中断 Claude（思考、调用工具、编辑文件等），保留上下文便于重定向或补充指令
• 双击 Escape 回到历史记录，编辑前一个提示，探索不同方向。可反复编辑直到满意为止
• 让 Claude 撤销更改，常与第 2 点结合，尝试不同方案

虽然 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、pre-commit 钩子、构建脚本和自动化等非交互场景。用 ⁠-p⁠ 标志加提示启用无头模式，⁠--output-format stream-json⁠ 可流式输出 JSON。

注意，无头模式不会在会话间持久化。每次都需手动触发。

a. 用 Claude 进行 issue 分流

无头模式可驱动由 GitHub 事件触发的自动化，如新 issue 创建时。Claude Code 公共仓库就用 Claude 检查新 issue 并分配合适标签。

b. 用 Claude 做 linter

Claude Code 可提供主观代码审查，发现传统 linter 检测不到的问题，如拼写错误、过时注释、误导性函数或变量名等。

6. 多 Claude 协作提升效率

除了单独使用，最强大的用法之一是并行运行多个 Claude 实例：

a. 一个 Claude 写代码，另一个 Claude 审查

简单高效的做法是让一个 Claude 写代码，另一个 Claude 审查或测试。类似多名工程师协作，有时分开上下文更好：
1. 用 Claude 写代码
2. 用 ⁠/clear⁠ 或在另一个终端启动第二个 Claude
3. 让第二个 Claude 审查第一个 Claude 的工作
4. 再启动一个 Claude（或再次 ⁠/clear⁠），读取代码和审查反馈
5. 让这个 Claude 根据反馈修改代码

你也可以让一个 Claude 写测试，另一个 Claude 写通过测试的代码。甚至可以让 Claude 实例间通过各自的草稿本通信，指定谁写谁读。

这种分工往往比单 Claude 处理所有任务效果更好。

b. 多仓库检出

许多 Anthropic 工程师会：
1. 创建 3-4 个 git 检出，放在不同文件夹
2. 分别在不同终端标签页打开每个文件夹
3. 在每个文件夹启动 Claude，分配不同任务
4. 轮流检查进度，批准/拒绝权限请求

c. 用 git worktree

适合多个独立任务，是多检出的轻量替代方案。git worktree 允许你将同一仓库的多个分支检出到不同目录。每个 worktree 有独立工作目录，文件隔离，但共享 git 历史和 reflog。

用 git worktree 可让你在项目不同部分同时运行多个 Claude，每个专注于独立任务。例如，一个 Claude 重构认证系统，另一个构建数据可视化组件。任务互不干扰，各自高效推进，无需等待或处理冲突：
1. 创建 worktree：⁠git worktree add ../project-feature-a feature-a⁠
2. 在每个 worktree 启动 Claude：⁠cd ../project-feature-a && claude⁠
3. 按需创建更多 worktree（在新终端标签页重复 1-2 步）

一些建议：
• 使用一致的命名规范
• 每个 worktree 保持一个终端标签页
• Mac 用户用 iTerm2 设置 Claude 需要关注时的通知
• 不同 worktree 用不同 IDE 窗口
• 完成后清理：⁠git worktree remove ../project-feature-a⁠

d. 用无头模式和自定义脚本

⁠claude -p⁠（无头模式）可将 Claude Code 程序化集成到更大工作流，同时利用其内置工具和系统提示。主要有两种模式：
1. 扇出（fanning out） 适合大规模迁移或分析（如分析数百日志或数千 CSV）：
a. 让 Claude 写脚本生成任务列表。例如，生成 2000 个需从框架 A 迁移到 B 的文件列表。
b. 循环处理任务，程序化调用 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:*)⁠
c. 多次运行脚本，迭代优化提示，直到获得理想结果。
2. 流水线（pipelining） 将 Claude 集成到现有数据/处理流水线：
a. 调用 ⁠claude -p “<你的提示>” --json | your_command⁠，⁠your_command⁠ 是流水线下一步
b. 就这样！可选的 JSON 输出便于结构化自动处理。

这两种用法都建议用 ⁠--verbose⁠ 标志调试 Claude 调用。生产环境建议关闭 verbose，输出更简洁。

你有哪些 Claude Code 使用技巧和最佳实践？欢迎 @AnthropicAI，分享你的成果！

致谢

作者：Boris Cherny。本指南借鉴了 Claude Code 用户社区的最佳实践，感谢大家的创新思路和工作流不断激励我们。特别感谢 Daisy Hollman、Ashwin Bhat、Cat Wu、Sid Bidasaria、Cal Rueb、Nodir Turakulov、Barry Zhang、Drew Hodun 及众多 Anthropic 工程师，他们的宝贵经验和实践帮助完善了这些建议。