这是一篇来自Anthropic 的官方文章，作者：Boris Cherny，下面是译文：
Claude Code：智能编码的最佳实践
Claude Code 是一款用于智能（agentic）编码的命令行工具。本文将介绍一些在不同代码库、编程语言和开发环境中使用 Claude Code 的有效技巧和建议。
我们最近发布了 Claude Code—— 这是一款作为研究项目开发的命令行工具，旨在为 Anthropic 的工程师和研究人员提供一种更原生的方式，将 Claude 集成到他们的编码工作流程中。
Claude Code 是一个低抽象层、不过度干预的工具，它几乎以原始模型的方式提供访问权限，不强制使用特定的工作流。这样的设计理念让它成为一个灵活、可定制、可脚本化且安全的强大工具。尽管功能强大，但这种灵活性也意味着初次使用智能编码工具的工程师可能会遇到一些学习曲线 —— 当然，一旦你形成了自己的使用习惯，这些都会变得顺手。
这篇文章总结了一些通用的有效模式，不仅适用于 Anthropic 内部团队，也对其他在各种代码库、语言和开发环境中使用 Claude Code 的工程师有所帮助。需要说明的是，这些建议并不是固定不变的，也不一定适合所有人，你可以将它们作为起点，鼓励你多做尝试，找到最适合自己的方式！
想了解更详细的信息？可以访问我们完整的文档网站claude.ai/code，里面涵盖了本文提到的所有功能，并提供了更多示例、实现细节和高级技巧。
1. 自定义你的设置
Claude Code 是一款智能编码助手，它会自动将相关上下文信息加入到提示词中。这个过程虽然会消耗时间和 token，但你可以通过调整环境配置来优化它。
a. 创建 CLAUDE.md 文件
CLAUDE.md 是一个特殊文件，当你开始与 Claude 交互时，它会被自动读取并纳入上下文。这使得它成为记录项目信息的理想位置，比如：
-
常用的 bash 命令
-
核心文件和工具函数
-
代码风格指南
-
测试说明
-
仓库协作规范（比如分支命名、合并 vs rebase 等）
-
开发环境设置（比如 pyenv 的使用方式、哪些编译器可用）
-
项目中特殊的行为或警告
-
其他你希望 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 文件：
-
代码库的根目录，或者你运行
claude的位置（这是最常见的用法）。文件命名为CLAUDE.md，并将它提交到 git 中，这样就可以在不同的使用会话中共享给自己或团队成员（推荐做法）。如果你只希望本地使用，也可以命名为CLAUDE.local.md并将它加入.gitignore。 -
你运行
claude目录的任意父目录。这种方式在 monorepo（多项目仓库） 中尤其有用，比如你在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” 强调某些要点，以提升 Claude 遵循这些说明的准确性。
c. 管理 Claude 的允许工具列表
默认情况下，Claude Code 会请求对任何可能修改您系统的操作的权限，比如写入文件、执行某些 bash 命令、使用 MCP 工具等。我们在设计 Claude Code 时采用了这种保守策略，以优先保障安全性。但你可以根据自己的需求自定义 “允许工具” 列表，加入那些你确定安全的工具，或者那些即使操作出错也容易撤销的工具（比如编辑文件、提交 git）。
你有四种管理允许使用的工具的方法：
-
1、在会话中出现提示时，选择 “Always allow（总是允许）”。
-
2、启动 Claude Code 后，使用
/allowed-tools命令添加或移除允许的工具。例如，你可以添加Edit来总是允许编辑文件，添加Bash(git commit:*)来允许执行 git 提交命令，或者添加mcp__puppeteer__puppeteer_navigate来启用 Puppeteer MCP 服务的导航功能。 -
3、手动编辑你的配置文件
.claude/settings.json或~/.claude.json（建议将前者提交到版本控制中，方便团队共享）。 -
4、使用命令行参数
--allowedTools为当前会话设置特定权限。
d. 如果使用 GitHub，安装gh命令行工具
Claude 支持使用ghCLI 工具与 GitHub 交互，比如创建 issue、打开 Pull Request、读取评论等。如果你没有安装gh，Claude 仍可以使用 GitHub API 或 MCP 服务（如果你已安装这些）。
2. 给 Claude 更多工具
Claude 可以访问你的 shell 环境，就像你平时为自己准备各种脚本和函数一样，也可以为 Claude 准备这些工具。同时，它还可以通过 MCP 和 REST API 使用更复杂的工具。
a. 使用 Claude 与 bash 工具配合使用
Claude Code 会继承你的 bash 环境，使其能够访问你所有的工具。虽然 Claude 已经了解一些常见工具（比如 Unix 工具、gh等），但如果你有自定义的 bash 工具，它不会自动识别，除非你告诉它怎么用：
-
告诉 Claude 工具的名称，并给出使用示例
-
让 Claude 执行
--help来查看工具的帮助文档 -
在 CLAUDE.md 文件中记录你常用的工具说明
b. 结合 MCP 使用 Claude
Claude Code 同时可以作为 MCP 的客户端和服务器使用。作为客户端，它可以连接多个 MCP 服务器，并通过以下三种方式访问这些工具：
-
在项目配置中定义（当你在该目录下运行 Claude Code 时生效）
-
在全局配置中定义（在所有项目中都可用）
-
在仓库中提交
.mcp.json文件（任何在这个代码库中工作的工程师都可以使用）。例如，你可以把 Puppeteer 和 Sentry 的 MCP 服务器配置添加进.mcp.json，这样团队里的所有成员都能开箱即用。
使用 MCP 时，还可以通过添加--mcp-debug参数启动 Claude，以帮助你调试配置问题。
c. 使用自定义斜杠命令（slash commands）
对于那些重复性的工作流程，比如调试循环、日志分析等，你可以将提示模板保存在.claude/commands文件夹下的 Markdown 文件中。这样，当你输入/时，这些自定义命令就会出现在命令菜单里。你还可以把这些命令提交进 git，这样团队其他成员也能使用。
自定义斜杠命令可以使用特殊关键字$ARGUMENTS，用来接收命令调用时传入的参数。
例如，下面是一个斜杠命令的示例，用来自动拉取并修复一个 GitHub issue：
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 的 GitHub issue。
类似地，你也可以把自己常用的命令放入~/.claude/commands文件夹中，这样这些命令在你所有的会话中都可以使用。
3. 尝试常见的工作流程
Claude Code 并不强制你使用某种特定的工作方式，它非常灵活，可以根据你的习惯自由调整。在这种灵活性之下，我们的用户社区中已经逐渐形成了一些非常有效的使用模式：
a. 探索 → 规划 → 编码 → 提交
这个流程适用于很多场景，操作步骤如下：
1、让 Claude 阅读相关文件、图片或网址。你可以给出大致的提示（如 “读取负责日志记录的文件”），也可以指定具体的文件名（如 “读取 logging.py”），但要明确告诉它暂时不要写代码。
在这一步，特别是面对复杂问题时，建议充分利用子代理（subagents）。可以让 Claude 使用子代理去验证细节、研究一些它可能不确定的问题，尤其在对话初期这么做，可以在不影响效率的前提下更好地保留上下文。
2、让 Claude 规划解决方案的实施步骤。建议使用关键词 “think” 来启动深入思考模式，这会为 Claude 提供更多 “计算预算” 以评估不同选项。系统中内置的关键词思考等级如下：- “think” < “think hard” < “think harder” < “ultrathink”。每个等级都会为 Claude 分配更多的思考资源。
如果你觉得这个方案合理，可以让 Claude 把它写成文档或创建一个 GitHub issue，方便你在后续实现出现偏差时回到这个 “保存点”。
3、让 Claude 根据方案开始编码实现。在这个阶段，你也可以提醒它在编码时检查每个部分是否合理。
4、让 Claude 提交代码并创建 Pull Request。如果有需要，也可以让它更新 README 或 changelog，说明做了哪些改动。
前两步（探索 + 规划）非常关键。否则 Claude 往往会直接跳到编码阶段。虽然有时候这样也没问题，但对于需要更深层思考的问题，先让 Claude 调研和规划，往往能显著提升效果。
b. 编写测试并提交 → 编码、迭代并提交
这是 Anthropic 非常推荐的一种工作流，适合那些可以通过单元测试、集成测试或端到端测试轻松验证的更改。将测试驱动开发（TDD）和智能编码结合，效果非常理想：
1、让 Claude 根据预期的输入 / 输出对写测试用例。明确告诉它你正在做 TDD，这样它就不会生成虚假的实现代码，即使这些功能在代码库中还不存在。
2、让 Claude 运行测试并确认它们失败。这一步也建议明确说明 “不要写任何实现代码”。
3、确认测试合理后，要求 Claude 提交这些测试代码。
4、让 Claude 编写通过测试的代码，并明确要求它不要修改测试内容。还可以告诉它 “继续尝试直到所有测试通过”。Claude 通常会多次尝试：写代码 → 跑测试 → 改代码 → 再测试，直到通过。
在这一步，也可以让 Claude 启动子代理，检查代码是否只是 “过拟合” 测试，而没有真正解决问题。
5、确认无误后，让 Claude 提交代码。
Claude 在有清晰 “目标” 时表现最好，比如一个测试用例、一个界面草图或其他可量化的输出。通过提供这些明确的目标，Claude 就可以对照结果进行自我调整，直到成功为止。
c. 编写代码 → 截图结果 → 迭代改进
这与测试驱动的流程类似，但更适用于有视觉输出的场景：
1、给 Claude 提供截图能力，比如使用 Puppeteer 的 MCP 服务、iOS 模拟器 MCP 服务，或者你也可以手动截图后粘贴到 Claude 对话框里。
2、提供一个视觉草图，可以是粘贴的图片、拖拽上传的文件，或是图片的路径。
3、让 Claude 编写代码实现设计，并通过截图对比实际效果与草图是否一致，进行迭代优化。
4、当你对效果满意后，让 Claude 提交代码。
和人类一样，Claude 的输出也会随着迭代变得更好。第一版可能只是 “差强人意”，但经过 2-3 次修改之后，通常就会非常接近目标效果。所以，如果你能给 Claude 提供它 “看得见” 的反馈，它的表现会大幅提升。
d. 安全版 YOLO 模式
如果你不想每一步都手动确认 Claude 的操作，可以使用命令claude --dangerously-skip-permissions跳过所有权限检查，让 Claude 一次性执行完所有任务，直到完成为止。这种方式特别适合处理像修复 lint 错误、生成模板代码这类任务。
不过要注意，让 Claude 无限制地执行命令是有风险的，可能会导致数据丢失、系统损坏，甚至数据泄露（比如通过提示注入攻击）。为尽量降低风险，建议你在没有互联网访问权限的容器中使用该模式。你可以参考使用 Docker Dev Containers 的参考实现来配置这样的环境。
e. 代码库问答（Codebase Q&A）
在刚接触一个新的代码库时，可以使用 Claude Code 来学习和探索。你可以把 Claude 当作一个项目中的资深工程师，向它提出问题，就像在结对编程时你会问队友的那些问题一样。Claude 能够智能地搜索代码库，回答一些通用问题，比如：
-
日志功能是怎么实现的？
-
我该如何添加一个新的 API 接口？
-
foo.rs第 134 行的
async move { ... }是做什么的？ -
CustomerOnboardingFlowImpl处理了哪些边界情况？
-
为什么我们在第 333 行调用的是
foo()而不是bar()？ -
baz.py第 334 行这段代码用 Java 怎么写？
在 Anthropic，我们已经把这种使用方式作为核心的入职流程，大大加快了新同事的上手速度，也减轻了老员工的指导负担。你不需要特别设计提示词，只要直接提问，Claude 就会主动在代码中查找答案。
f. 使用 Claude 与 Git 交互
Claude 能够高效处理许多 Git 操作。在 Anthropic，很多工程师使用 Claude 完成了超过 90% 的 git 工作：
-
搜索 Git 历史 来回答问题，比如：“v1.2.3 中包含了哪些改动？”、“这个功能是谁写的？”、“这个 API 为什么是这样设计的？” 等。你可以明确提示 Claude 查阅 git 历史来获得这些答案。
-
撰写提交信息（commit message）。Claude 会自动查看你的代码改动和相关历史记录，生成包含上下文的提交说明。
-
处理复杂的 git 操作，比如撤销文件更改、解决 rebase 冲突、对比补丁或拼接 patch 等。
g. 使用 Claude 与 GitHub 交互
Claude Code 也能处理多种 GitHub 操作：
-
创建 Pull Request：Claude 能识别
pr的简写，会根据差异内容和上下文生成合适的提交信息。 -
一键处理代码审查意见：告诉它修复 PR 上的评论（你也可以附上更具体的指令），Claude 会修复后将改动推回对应的分支。
-
修复构建失败或 linter 警告
-
对 GitHub 上的 open issue 进行分类和处理，只需要让 Claude 遍历所有未关闭的 issue 即可
这样一来，你不需要记住复杂的gh命令行语法，就能自动化处理很多日常操作。
h. 使用 Claude 操作 Jupyter Notebook
Anthropic 的研究员和数据科学家使用 Claude Code 来阅读和编写 Jupyter Notebook。Claude 不仅可以理解代码输出结果（包括图片），还能高效地与数据交互和探索。
虽然没有固定的提示格式或流程，但我们推荐的做法是：将 Claude Code 与一个.ipynb文件在 VS Code 中并排打开，这样可以方便地来回查看和修改。
你也可以让 Claude 美化或整理 Notebook，尤其是在向同事展示之前。明确告诉 Claude 让 notebook 的展示效果更 “美观”，或者让图表 “更易于人理解”，往往能让它优化得更加人性化。
4. 优化你的工作流程
以下建议适用于所有工作流程
a. 给出具体明确的指令
Claude Code 的执行效果会因为提示是否具体而有很大差异，特别是在首次尝试时。一开始就给出清晰的指令，可以减少后续需要反复调整的次数。
例如：
| 差（Poor） | 好（Good） |
|---|---|
| 添加 foo.py 的测试 | 为 foo.py 编写一个新的测试用例，覆盖用户已注销时的边界情况。避免使用 mock。 |
| ExecutionFactory 的 API 为什么这么奇怪？ | 查阅 ExecutionFactory 的 Git 历史，整理它的 API 是如何演变成现在这样的。 |
| 添加一个日历组件 | 查看首页上已有的组件是如何实现的，以了解常用的代码模式，特别是代码和界面是如何分离的。可以从 HotDogWidget.php 开始看，它是个很好的例子。然后，按照这种模式实现一个新的日历组件，让用户可以选择月份，并能前后翻页选择年份。请从零开始编写，除非项目中已有库，否则不要引入新库。 |
Claude 能够推断意图，但它不能读心。具体性有助于更好地符合预期。
b. 给 Claude 图片
Claude 对图片和图示非常擅长处理，你可以通过多种方式提供图像：
-
粘贴截图（小技巧：在 macOS 中使用
cmd+ctrl+shift+4截图并复制到剪贴板，然后用ctrl+v粘贴。注意：不是平常使用的cmd+v，而且该方法在远程环境中无法使用） -
直接拖拽图片到 Claude 的输入框
-
提供图片的文件路径
这在进行 UI 开发时，使用设计稿作为参考非常实用；也适合调试时参考图表和可视化结果。如果你没有添加图片，也可以明确告诉 Claude 你希望结果具有良好的视觉效果，它会尝试优化输出的可读性或美观度。
c. 明确指出你希望 Claude 查看或修改的文件
使用 Tab 自动补全，可以快速引用代码库中的文件或文件夹，帮助 Claude 精准找到目标文件。
d. 给 Claude 网址
你可以直接在提示词中粘贴 URL，Claude 会尝试获取并阅读链接内容。为了避免每次访问同一域名时都弹出权限请求，比如docs.foo.com，你可以使用/allowed-tools命令把域名添加到白名单中。
e. 过早、频繁地进行方向校正（course correct）
虽然你可以开启 “自动接受模式”（shift+tab 切换），让 Claude 自主执行任务，但通常来说，你越积极参与、引导它的思路，结果就越好。在任务开始时详细说明内容最重要，但你随时都可以修正方向。
以下是四个常用的方向校正方法：
1、让 Claude 先写一个计划，再开始写代码。明确告诉它：“在我确认方案之前，先不要写代码。” 2、按Esc键中断 Claude 的当前操作（包括思考、调用工具、编辑文件等），保留上下文，便于你调整或补充指令。 3、双击Esc键回到历史记录，修改之前的提示，探索不同方向。你可以反复修改并重试，直到得到你想要的结果。 4、让 Claude 撤销更改，常常和第 2 步配合使用，便于走另一条路径。
虽然 Claude 有时第一次就能完美完成任务，但这些校正工具往往能更快、更可靠地生成更优解。
f. 使用/clear保持上下文干净
长时间会话中，Claude 的上下文窗口会积累很多无关内容，比如旧的对话、文件内容、命令等。这会影响 Claude 的性能，甚至让它跑偏。建议在每个任务之间使用/clear命令清理上下文，保持会话专注
g. 对于复杂流程，使用清单和草稿区
对于大型任务（如代码迁移、修复大量 lint 错误、运行复杂构建脚本等），可以让 Claude 使用 Markdown 文件或 GitHub issue 作为 任务清单 和 工作草稿区，提升整体效率。
例如，要修复大量的代码风格问题，你可以：
1、让 Claude 执行 lint 命令，并将所有错误（包括文件名和行号）写入一个 Markdown 清单中 2、指示 Claude 按照清单逐条处理，每解决一个问题就检查结果，并在清单中勾选完成，然后继续下一个
h. 向 Claude 提供数据的方式
你可以通过多种方式向 Claude 提供数据：
-
直接复制粘贴进对话（最常见）
-
管道输入，例如：
cat foo.txt | claude，适用于日志、CSV、文本数据等 -
使用 bash 命令、MCP 工具或自定义斜杠命令，让 Claude 拉取数据
-
让 Claude 阅读文件或访问 URL（也适用于图片）
通常实际使用中会组合多种方式，例如先把日志文件传给 Claude，然后让它使用工具拉取更多上下文信息进行调试。
5. 使用 Headless 模式自动化基础设施
Claude Code 提供了无交互（headless）模式，适用于 CI、pre-commit hooks、构建脚本和其他自动化场景。你可以使用-p参数传入提示词，并配合--output-format stream-json以流式输出 JSON。
注意：headless 模式不会在会话间保持持久化，每次需要单独触发。
a. 使用 Claude 进行 issue 分类和预处理
你可以在 GitHub 触发器中自动调用 Claude。例如，在一个新 issue 创建时触发，Claude 会自动查看内容并打上适当标签。Claude Code 的开源仓库就是这样做的。
b. 将 Claude 用作代码检查工具
Claude 不只是传统的 Linter，它还可以识别更主观的问题，比如拼写错误、过时注释、误导性的函数或变量命名等，比传统静态分析工具更细致。
6. 多 Claude 协作工作流（Multi-Claude Workflows）
除了单独使用之外，一些最强大的应用涉及并行运行多个 Claude 实例
a. 一个 Claude 写代码，另一个 Claude 审查代码
一种简单却有效的方法是让一个 Claude 编写代码，而另一个进行审查或测试。与多个工程师合作类似，有时拥有不同的视角是有益的：
1、Claude A 负责编写代码 2、运行/clear，或另起一个终端启动 Claude B 3、Claude B 审查 Claude A 写的代码 4、Claude C 读取代码和审查反馈，并根据反馈优化代码
你也可以这样做测试驱动开发：Claude A 写测试，Claude B 编写能通过测试的代码。
更进一步，你甚至可以让不同 Claude 之间通过 共享草稿区 互相 “沟通”，一个写，一个读。
这种角色分离的方式，往往比一个 Claude 做所有事效果更好。
b. 多个代码库副本并行使用 Claude
与其等着 Claude 完成每一步，Anthropic 的许多工程师会采取的做法是：
1、在不同文件夹下创建 3-4 个 git 仓库副本 2、在多个终端窗口中分别打开 3、在每个副本中运行 Claude，分配不同任务 4、依次检查进度，并根据需要批准 / 拒绝权限请求
c. 使用 git worktree（更轻量的方案）
如果你不想复制多个仓库，可以使用git worktree，它允许你在不同目录下检出多个分支，但它们共享同一个 Git 历史。
你可以在不同 worktree 中启动多个 Claude 会话，分别专注于不同子任务。例如：
-
一个 Claude 重构认证系统
-
另一个 Claude 构建数据可视化组件
-
两者互不干扰，效率更高
示例步骤：
# 创建新的 worktree
git worktree add ../project-feature-a feature-a
# 在新目录中启动 Claude
cd ../project-feature-a && claude
建议：
-
使用一致的命名规范
-
每个终端标签对应一个 worktree
-
如果用的是 macOS 的 iTerm2，可以设置 Claude 请求权限时弹出通知
-
用不同的 IDE 窗口分别打开不同 worktree
-
完成后清理：
git worktree remove ../project-feature-a
d. 配合自定义框架使用 headless 模式
你可以使用claude -p将 Claude Code 集成进大型自动化工作流中。两种典型场景如下：
1、并行任务（fanning out）
-
让 Claude 生成待处理文件列表，例如 2k 个需要迁移的文件
-
写脚本循环处理这些任务，Claude 每次接受任务和允许的工具
示例：
claude -p "将 foo.py 从 React 迁移到 Vue。完成后请返回 OK，失败则返回 FAIL。" --allowedTools Edit Bash(git commit:*)
-
多次运行脚本并微调 prompt，直到效果满意
2、流水线集成（pipelining）
示例：
claude -p "<你的提示词>" --json | your_command
这样可以将 Claude 的 JSON 输出传递给下一个处理步骤，便于结构化处理
调试建议：开发时可以加上--verbose方便排查问题，正式使用时可关闭获取更清爽的输出。
致谢
本文由 Boris Cherny 撰写，内容汇集了 Claude Code 社区中丰富的最佳实践和灵感来源。特别感谢 Daisy Hollman、Ashwin Bhat、Cat Wu、Sid Bidasaria、Cal Rueb、Nodir Turakulov、Barry Zhang、Drew Hodun 以及众多 Anthropic 工程师对本文提供的重要建议与真实经验。
原文：https://www.anthropic.com/engineering/claude-code-best-practices