Claude Code: Agentic Coding 最佳实践

译者按: 本文是 Boris Cherny (Anthropic, 文末致谢段署名 Written by Boris Cherny) 于 2025-04-18 发表的《Claude Code: Best practices for agentic coding》的中文校对翻译。原文出处: https://www.anthropic.com/engineering/claude-code-best-practices。读原文时深受启发, 特将全文译出与中文读者分享, 感谢原作者的点醒与提携。译文仅供学习交流, 版权归原作者所有, 如有出入以原文为准。

原文发布于 2025 年 4 月 18 日, Anthropic 工程博客。原始 URL 现已 308 重定向到 code.claude.com/docs/en/best-practices (官方文档持续更新版)。本译文基于 archive.org 2025-04-20 快照的原始版本全文翻译。代码与命令保留原样。

Claude Code 是一个用于 agentic coding 的命令行工具。本文汇总了在各种代码库、语言和环境中使用 Claude Code 时被验证有效的技巧。

我们最近发布了 Claude Code, 一个用于 agentic coding 的命令行工具。它最初是一个研究项目, 目的是让 Anthropic 的工程师和研究员能用更原生的方式把 Claude 融入自己的编码工作流。

Claude Code 有意做得低层级、不带立场, 提供接近原始模型的访问能力, 不强推特定工作流。这种设计哲学造就了一个灵活、可定制、可脚本化且安全的强力工具。但强大的灵活性对刚接触 agentic coding 工具的工程师来说也意味着学习曲线, 至少在他们摸索出自己的最佳实践之前是这样。

本文整理的是一些被普遍验证有效的模式, 既来自 Anthropic 内部团队, 也来自在各种代码库、语言、环境中使用 Claude Code 的外部工程师。这份清单里没有一条是铁板钉钉或放之四海皆准的; 请把这些建议当作起点。我们鼓励你多做实验, 找到最适合自己的用法。

想要更详细的信息? 我们的完整文档 (claude.ai/code) 覆盖了本文提到的所有功能, 并提供更多示例、实现细节和进阶技巧。

1. 定制你的环境

Claude Code 是一个会自动把上下文拉进 prompt 的 agentic 编码助手。收集上下文要消耗时间和 token, 但你可以通过环境调优来优化它。

a. 创建 CLAUDE.md 文件

CLAUDE.md 是一个特殊文件, Claude 在开启对话时会自动把它拉进上下文。这让它成为记录以下内容的理想位置:

• 常用 bash 命令
• 核心文件和工具函数
• 代码风格指南
• 测试说明
• 仓库协作规范 (例如分支命名、merge 还是 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 的目录的任意子级目录。这是上一条的反向情况, 当你处理子目录里的文件时, Claude 会按需拉入对应的 CLAUDE.md
• 你的用户主目录 (~/.claude/CLAUDE.md), 会应用到你所有的 claude 会话

运行 /init 命令时, Claude 会自动为你生成一份 CLAUDE.md。

b. 调优你的 CLAUDE.md 文件

CLAUDE.md 会成为 Claude prompt 的一部分, 所以它应该像任何高频使用的 prompt 一样被反复打磨。一个常见错误是塞进大量内容却从不迭代验证效果。花点时间做实验, 搞清楚什么样的写法能让模型的指令遵循度最好。

你可以手动往 CLAUDE.md 里加内容, 也可以按 # 键给 Claude 一条指令, 它会自动把这条指令写进相应的 CLAUDE.md。很多工程师在写代码的过程中频繁用 # 来记录命令、文件和风格规范, 然后把 CLAUDE.md 的变更包含在 commit 里, 让团队成员也受益。

在 Anthropic, 我们偶尔会把 CLAUDE.md 文件跑一遍 prompt improver, 并且经常调整指令措辞 (例如加上 “IMPORTANT” 或 “YOU MUST” 来加重语气) 以提高遵循度。

c. 精心维护 Claude 的工具白名单

默认情况下, Claude Code 对任何可能改动你系统的操作都会请求许可: 写文件、许多 bash 命令、MCP 工具等等。我们刻意用这种保守方式设计 Claude Code, 把安全放在第一位。你可以定制白名单, 放行那些你确认安全的工具, 或者放行那些即使出错也容易撤销的操作 (例如文件编辑、git commit)。

管理工具白名单有四种方式:

• 会话中收到询问时选择 “Always allow”
• 启动 Claude Code 后使用 /allowed-tools 命令增删白名单条目。例如, 加 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、开 pull request、读评论等等。没装 gh 的话, Claude 也能退而使用 GitHub API 或 MCP server (前提是你装了)。

2. 给 Claude 更多工具

Claude 可以访问你的 shell 环境, 你可以像给自己准备工具那样, 为它积累一套便利脚本和函数。它还能通过 MCP 和 REST API 使用更复杂的工具。

a. 让 Claude 用 bash 工具

Claude Code 继承你的 bash 环境, 因此能用到你所有的工具。Claude 认识常见的 unix 工具和 gh, 但你自己写的 bash 工具它是不知道的, 除非你告诉它:

• 直接告诉 Claude 工具名, 并给出用法示例
• 让 Claude 运行 –help 查看工具文档
• 把高频工具写进 CLAUDE.md

b. 让 Claude 用 MCP

Claude Code 既是 MCP server 又是 MCP client。作为 client, 它可以连接任意数量的 MCP server, 有三种配置方式:

• 项目配置 (在该目录运行 Claude Code 时可用)
• 全局配置 (所有项目可用)
• 提交进仓库的 .mcp.json 文件 (对所有在这个代码库工作的人可用)。例如, 你可以把 Puppeteer 和 Sentry 的 server 加进 .mcp.json, 这样仓库里每个工程师开箱即用

排查 MCP 配置问题时, 用 –mcp-debug 参数启动 Claude 会很有帮助。

c. 使用自定义斜杠命令

对于重复性的工作流, 比如调试循环、日志分析等, 可以把 prompt 模板存成 Markdown 文件放进 .claude/commands 文件夹。输入 / 时它们会出现在斜杠命令菜单里。这些命令可以提交进 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, 它就会以 /project:fix-github-issue 命令的形式出现在 Claude Code 里。然后你就可以用 /project:fix-github-issue 1234 让 Claude 去修 #1234 号 issue。同理, 你也可以把个人常用命令放进 ~/.claude/commands 文件夹, 让它们在你所有的会话里可用。

3. 试试这些通用工作流

Claude Code 不强加特定工作流, 你想怎么用就怎么用。在这种灵活性之下, 用户社区里已经浮现出几种行之有效的模式:

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

这个多面手工作流适合很多问题:

1. 让 Claude 阅读相关文件、图片或 URL, 可以给宽泛的指引 (“读一下处理日志的那个文件”), 也可以给具体文件名 (“读 logging.py”), 但要明确告诉它先别写任何代码。
   • 这一步是应该重点考虑使用 subagent 的环节, 尤其是复杂问题。让 Claude 用 subagent 去核实细节或调查它可能存在的疑问, 特别是在对话或任务的早期, 通常能在几乎不损失效率的前提下保住上下文的可用空间。
2. 让 Claude 针对具体问题制定一个计划。我们建议用 “think” 这个词触发扩展思考模式, 给 Claude 额外的计算时间去更充分地评估备选方案。这些特定短语在系统里直接映射为逐级递增的思考预算: “think” < “think hard” < “think harder” < “ultrathink”, 每一级分配的思考预算依次增加。
   • 如果这一步的结果看起来合理, 你可以让 Claude 把计划写成一个文档或 GitHub issue, 这样如果第 3 步的实现不符合预期, 你可以回滚到这个节点。
3. 让 Claude 把方案实现成代码。这一步也适合要求它在实现各个部分时, 顺带显式验证方案的合理性。
4. 让 Claude 提交结果并创建 pull request。如果相关的话, 这也是让 Claude 更新 README 或 changelog 的好时机, 说明它刚才做了什么。

第 1、2 步非常关键; 没有它们, Claude 往往会直接跳到写代码。虽然有时这正是你想要的, 但对于需要先深入思考的问题, 让 Claude 先调研、先规划, 会显著提升表现。

b. 先写测试并提交; 再写代码、迭代、提交

这是 Anthropic 内部的心头好工作流, 适合能用单元测试、集成测试或端到端测试轻松验证的改动。测试驱动开发 (TDD) 在 agentic coding 时代变得更加强大:

1. 让 Claude 基于预期的输入输出对来写测试。要明确说你在做测试驱动开发, 这样它才不会为尚不存在的功能造 mock 实现。
2. 让 Claude 运行测试并确认它们失败。此时明确告诉它不要写任何实现代码, 通常很有帮助。
3. 对测试满意后, 让 Claude 提交测试。
4. 让 Claude 写能通过测试的代码, 并要求它不许改测试。告诉 Claude 一直做到所有测试通过为止。通常要经过几轮迭代: 写代码、跑测试、调整代码、再跑测试。
   • 这个阶段可以让它用独立的 subagent 检查实现有没有对测试过拟合。
5. 对改动满意后, 让 Claude 提交代码。

Claude 在有明确迭代目标时表现最好, 无论是视觉稿、测试用例还是其他形式的产出。提供测试这样的预期输出后, Claude 就能不断修改、评估结果、逐步逼近, 直到成功。

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

和测试工作流类似, 你可以给 Claude 提供视觉目标:

1. 给 Claude 一个截取浏览器截图的手段 (例如 Puppeteer MCP server、iOS 模拟器 MCP server, 或者手动把截图复制粘贴给 Claude)。
2. 给 Claude 一张视觉稿: 复制粘贴、拖拽图片, 或给出图片文件路径。
3. 让 Claude 用代码实现这个设计, 对结果截图, 反复迭代直到和视觉稿一致。
4. 满意后让 Claude 提交。

和人类一样, Claude 的产出经过迭代会明显变好。第一版可能已经不错, 但迭代 2 到 3 轮后通常会好看得多。给 Claude 看到自己产出的工具, 效果最佳。

d. 安全的 YOLO 模式

你也可以不盯着 Claude, 用 claude –dangerously-skip-permissions 跳过所有权限检查, 让它不受打断地一路干到完成。这种方式很适合修 lint 错误、生成样板代码之类的工作流。

让 Claude 运行任意命令是有风险的, 可能导致数据丢失、系统损坏, 甚至数据外泄 (例如遭遇 prompt 注入攻击)。要把风险降到最低, 请在没有互联网访问的容器里使用 –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, 这种用法已经成为我们核心的新人上手工作流, 明显缩短了上手时间, 也减轻了其他工程师的负担。不需要任何特殊 prompt! 直接提问就行, Claude 会自己去探索代码找答案。

f. 用 Claude 操作 git

Claude 能高效处理很多 git 操作。Anthropic 不少工程师 90% 以上的 git 交互都交给 Claude:

• 搜索 git 历史回答问题, 比如 “v1.2.3 里进了哪些改动?"、“这个功能归谁负责?"、“这个 API 当初为什么这么设计?"。这类问题最好显式提示 Claude 去翻 git 历史。
• 写 commit message。Claude 会自动查看你的改动和最近的历史, 把相关上下文都考虑进去再撰写。
• 处理复杂 git 操作, 比如回退文件、解决 rebase 冲突、比较和移植补丁。

g. 用 Claude 操作 GitHub

Claude Code 能搞定很多 GitHub 交互:

• 创建 pull request: Claude 理解 “pr” 这个简写, 会根据 diff 和上下文生成合适的提交信息。
• 一把梭修复简单的 code review 意见: 告诉它去修 PR 上的评论 (可以附加更具体的指示), 修完推回 PR 分支。
• 修复失败的构建或 linter 警告。
• 给开放 issue 分类和分诊: 让 Claude 遍历仓库的 open issues 即可。

有了这些, 你不用再记 gh 的命令行语法, 例行任务也自动化了。

h. 用 Claude 处理 Jupyter notebook

Anthropic 的研究员和数据科学家用 Claude Code 读写 Jupyter notebook。Claude 能解读输出, 包括图片, 这为探索数据、和数据交互提供了一条快车道。没有什么必须的 prompt 或流程, 但我们推荐的一种方式是: 在 VS Code 里把 Claude Code 和 .ipynb 文件并排打开。

你也可以在把 notebook 拿给同事看之前, 让 Claude 清理它或做美化。明确告诉它把 notebook 或数据可视化弄得 “aesthetically pleasing” (赏心悦目), 有助于提醒它这是在为人类的观看体验做优化。

4. 优化你的工作流

下面的建议适用于所有工作流:

a. 指令要具体

指令越具体, Claude Code 的成功率越高, 首次尝试时尤其明显。前期把方向说清楚, 后期就少走弯路。

例如:

Claude 能推断意图, 但它不会读心术。指令越明确, 结果越贴合预期。

b. 给 Claude 图片

Claude 处理图片和图表很在行, 有几种喂图方式:

• 粘贴截图 (小技巧: macOS 上按 cmd+ctrl+shift+4 把截图存到剪贴板, 再按 ctrl+v 粘贴。注意不是 mac 上惯用的 cmd+v, 而且远程环境下不可用)
• 直接把图片拖进 prompt 输入框
• 给出图片的文件路径

这在拿设计稿当 UI 开发参照、用可视化图表做分析和调试时特别有用。就算不往上下文里放图, 明确告诉 Claude 结果的视觉观感有多重要, 也仍然有帮助。

c. 点名你想让 Claude 看或改的文件

用 tab 补全快速引用仓库中任意位置的文件或文件夹, 帮 Claude 找对资源、改对地方。

d. 给 Claude URL

把具体的 URL 连同 prompt 一起贴给 Claude, 让它抓取阅读。为了避免同一域名反复弹出权限确认 (例如 docs.foo.com), 用 /allowed-tools 把域名加进白名单。

e. 尽早纠偏、频繁纠偏

自动接受模式 (shift+tab 切换) 可以让 Claude 自主干活, 但通常你以协作者身份主动引导 Claude 的思路, 结果会更好。最理想的是开工前把任务向 Claude 解释透彻, 但中途任何时候都可以纠偏。

这四个工具帮你纠偏:

• 让 Claude 写代码前先出计划, 并明确告诉它: 计划没被你确认之前不许写代码。
• 按 Escape 可以在任意阶段打断 Claude (思考中、工具调用中、编辑文件中), 上下文得以保留, 你可以重新指路或补充指令。
• 双击 Escape 跳回历史记录, 编辑之前的 prompt, 换一个方向探索。你可以反复编辑 prompt 直到得到想要的结果。
• 让 Claude 撤销改动, 常与上一条配合, 换一种做法。

尽管 Claude Code 偶尔一次就把问题解决得漂漂亮亮, 但用好这些纠偏工具, 通常能更快得到更好的方案。

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

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

g. 复杂工作流用清单和草稿板

对于步骤繁多或要求穷尽式解决的大任务, 比如代码迁移、修一大堆 lint 错误、跑复杂的构建脚本, 让 Claude 用一个 Markdown 文件 (甚至一个 GitHub issue!) 当清单和工作草稿板, 能提升表现:

例如修大量 lint 问题, 可以这样做:

1. 让 Claude 运行 lint 命令, 把所有报错 (带文件名和行号) 写进一个 Markdown 清单
2. 指示 Claude 逐条处理, 修一条、验一条、勾掉一条, 再进行下一条

h. 把数据喂给 Claude

给 Claude 提供数据有好几种方式:

• 直接复制粘贴进 prompt (最常见)
• 管道输入 Claude Code (例如 cat foo.txt | claude), 对日志、CSV 和大块数据尤其好用
• 让 Claude 通过 bash 命令、MCP 工具或自定义斜杠命令去拉数据
• 让 Claude 读文件或抓 URL (图片同样适用)

大多数会话是这些方式的组合。比如, 你可以先管道输入一份日志文件, 然后让 Claude 用某个工具拉取更多上下文来调试这些日志。

5. 用 headless 模式自动化你的基础设施

Claude Code 提供 headless 模式, 用于 CI、pre-commit 钩子、构建脚本、自动化等非交互场景。用 -p 参数加一个 prompt 即可启用 headless 模式, 用 –output-format stream-json 可以获得流式 JSON 输出。

注意 headless 模式不会跨会话保持, 每个会话都要重新触发。

a. 用 Claude 做 issue 分诊

headless 模式可以驱动由 GitHub 事件触发的自动化, 比如仓库里新建 issue 的时候。例如, Claude Code 的公开仓库就用 Claude 检查新进来的 issue 并打上合适的标签。

b. 把 Claude 当 linter 用

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

6. 进阶: 多 Claude 工作流

在单实例用法之外, 一些最强大的应用来自并行运行多个 Claude 实例:

a. 一个 Claude 写代码, 另一个 Claude 来验证

一个简单但有效的做法是让一个 Claude 写代码, 另一个来 review 或测试。就像和多位工程师共事一样, 有时上下文分离反而是好事:

1. 用一个 Claude 写代码
2. 运行 /clear, 或在另一个终端启动第二个 Claude
3. 让第二个 Claude 审查第一个 Claude 的工作
4. 再启动一个 Claude (或再次 /clear), 让它同时读代码和 review 意见
5. 让这个 Claude 根据反馈修改代码

测试也可以这么玩: 一个 Claude 写测试, 另一个 Claude 写代码让测试通过。你甚至可以给各个 Claude 实例分配独立的工作草稿板, 告诉它们各自写哪个、读哪个, 让它们相互通信。

这种分工往往比让一个 Claude 包办一切效果更好。

b. 给仓库搞多份 checkout

与其干等 Claude 完成每一步, Anthropic 很多工程师的做法是:

1. 在不同文件夹里创建 3 到 4 份 git checkout
2. 每个文件夹开一个终端标签页
3. 在每个文件夹里启动 Claude, 分派不同任务
4. 轮流巡视进度, 批准或拒绝权限请求

c. 使用 git worktree

处理多个互不相关的任务时, 这个方法特别出彩, 是多份 checkout 的轻量替代。git worktree 允许你把同一仓库的多个分支检出到不同目录。每个 worktree 有自己独立的工作目录和文件, 同时共享同一份 Git 历史和 reflog。

用 git worktree, 你可以在项目的不同部分同时跑多个 Claude 会话, 每个专注于自己的独立任务。比如, 一个 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. headless 模式配自定义编排

claude -p (headless 模式) 能把 Claude Code 以编程方式嵌入更大的工作流, 同时保留它的内置工具和系统 prompt。使用 headless 模式主要有两种模式:

1. 扇出 (Fanning out), 适合大规模迁移或分析 (例如分析几百份日志的情感倾向, 或分析几千个 CSV):

• 让 Claude 写一个脚本生成任务清单。例如, 生成一份需要从框架 A 迁移到框架 B 的 2000 个文件的清单。
• 循环遍历任务, 对每个任务以编程方式调用 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:*)
• 多跑几遍脚本, 打磨你的 prompt, 直到得到想要的结果。

2. 管道化 (Pipelining), 把 Claude 接进已有的数据/处理管线:

• 调用 claude -p “” –json | your_command, 其中 your_command 是你处理管线的下一环
• 就这么简单! 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 工程师, 他们对 Claude Code 的宝贵见解和实战经验塑造了这些建议。

原文出处: Claude Code: Best practices for agentic coding 原作者: Boris Cherny (Anthropic, 文末致谢段署名 Written by Boris Cherny) 原文发表: 2025-04-18

本文收录于「X深度阅读」栏目: 精选全球 X/Twitter 与博客上最值得精读的 AI 长文, 逐篇校对翻译成中文。