跳转至

Claude Code：代理式编程的最佳实践

  • 原文链接：https://www.anthropic.com/engineering/claude-code-best-practices [56]
  • 发布时间：2025-04-18
  • 作者：Boris Cherny

Claude Code 是一个低层、可定制、可脚本化且注重安全的代理式编程“电动工具”。[56]

Claude Code 是一个面向代理式编程的命令行工具。本文总结了在不同代码库、语言和环境中使用 Claude Code 的实践技巧与模式。[56]

我们最近发布了 Claude Code，它最初作为研究项目开发，为 Anthropic 工程师和研究人员提供一种更原生的方式，把 Claude 融入编码工作流。[56]

Claude Code 的设计目标是“低层、无观点”，尽可能接近模型的原始能力，不强制固定流程。这让它高度灵活、可定制、可脚本化且更安全，但也意味着新手需要一段学习曲线，直到形成适合自己的最佳实践。[56]

本文给出的一系列模式，来自 Anthropic 内部团队与外部工程师的共同经验。它们不是硬性规则，也不一定适用于所有场景——把它们当作起点，实践并调整到最适合你的方式。[56]

想要更详细的信息？我们在 claude.ai/code 的完整文档覆盖了本文提到的所有功能，并提供更多示例、实现细节与高级技巧。[56]

1. 定制你的环境

Claude Code 会自动把上下文拉入提示词，这会消耗时间与 token。通过环境调优可以显著提升效率。[56]

a. 创建 CLAUDE.md 文件

CLAUDE.md 是一个特殊文件，Claude 在对话开始时会自动读取并加入上下文。非常适合记录以下内容：[56]

  • 常用 bash 命令
  • 核心文件与工具函数
  • 代码风格规范
  • 测试说明
  • 仓库协作习惯（如分支命名、merge vs. rebase）
  • 开发环境设置（如 pyenv、编译器要求）
  • 项目特有的异常行为或警告
  • 你希望 Claude 记住的其他信息

CLAUDE.md 没有固定格式，建议保持简洁、人类可读。例如：[56]

# 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 可以放在多个位置：[56]

  • 仓库根目录（或你运行 claude 的位置）。建议命名为 CLAUDE.md 并纳入 git 以便团队共享，或命名为 CLAUDE.local.md 并加入 .gitignore。
  • 运行目录的任意父目录。适合 monorepo，例如在 root/foo 运行 Claude 时，root/CLAUDE.md 和 root/foo/CLAUDE.md 都会被自动加载。
  • 运行目录的任意子目录。当你进入子目录工作时，Claude 会按需加载该目录中的 CLAUDE.md。
  • 你的 home 目录（~/.claude/CLAUDE.md），适用于所有 Claude 会话。

当你运行 /init 命令时，Claude 会自动生成一个 CLAUDE.md。[56]

b. 调优你的 CLAUDE.md

CLAUDE.md 会直接进入提示词，因此应像高频提示一样持续迭代。常见错误是一次性塞入大量内容，却从不验证效果。建议通过实验来找到最能提高指令遵循的写法。[56]

你可以手动编辑 CLAUDE.md，也可以在 Claude Code 中按 # 键对 Claude 下指令，它会自动写入相关 CLAUDE.md。许多工程师会在编码时频繁用 # 记录命令、文件与风格规范，然后把 CLAUDE.md 的变更随代码一起提交，让团队受益。[56]

在 Anthropic，我们会不定期用 prompt improver 优化 CLAUDE.md，并会通过增加“IMPORTANT”“YOU MUST”等强调语句提升模型遵循度。[56]

图：原文未提供图注

图注：原文未提供图注。[56]

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

默认情况下，Claude Code 会对可能修改系统的动作请求许可：文件写入、许多 bash 命令、MCP 工具等。这种保守策略是出于安全考虑。你可以自定义 allowlist，允许额外你确信安全的工具，或允许容易回滚的潜在风险操作（如文件编辑、git commit）。[56]

有四种方式管理允许工具：[56]

  • 在提示时选择 “Always allow”。
  • 使用 /permissions 命令 为会话添加/移除工具。例如：允许 Edit 进行文件编辑；允许 Bash(git commit:*) 进行 git 提交；允许 mcp__puppeteer__puppeteer_navigate 使用 Puppeteer MCP 进行网页导航。
  • 手动编辑 .claude/settings.json 或 ~/.claude.json（推荐把前者纳入版本控制以共享给团队）。
  • 使用 --allowedTools CLI 参数 设置会话级权限。

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

Claude 可以通过 gh CLI 与 GitHub 交互（创建 issue、开 PR、读评论等）。没有 gh 也能用 GitHub API 或 MCP server（若已安装），但体验更完整的是安装 gh。[56]

2. 给 Claude 更多工具

Claude 可以访问你的 shell 环境，你可以像为自己一样给它准备脚本与函数；也可以通过 MCP 或 REST API 接入更复杂的工具。[56]

a. 使用 Claude + bash 工具

Claude Code 继承你的 bash 环境，能访问常见工具与 gh，但它不知道你的自定义工具，除非你告诉它。[56]

建议流程：[56]

  1. 告诉 Claude 工具名并提供用法示例
  2. 让 Claude 运行 --help 查看文档
  3. 在 CLAUDE.md 里记录高频工具

b. 使用 Claude + MCP

Claude Code 既是 MCP server 也是 client。作为 client，它可以连接多个 MCP server，并通过三种方式访问工具：[56]

  • 项目级配置（在该目录运行 Claude Code 时可用）
  • 全局配置（在所有项目中可用）
  • 代码库内 .mcp.json（团队共享）

例如，可以在 .mcp.json 中加入 Puppeteer 和 Sentry server，让所有工程师开箱即用。[56]

排查 MCP 配置时，可以用 --mcp-debug 启动 Claude 便于定位问题。[56]

c. 使用自定义 slash 命令

对于重复性的流程（debug 循环、日志分析等），可以把提示词模板写到 .claude/commands 目录下的 Markdown 文件中。这样在输入 / 时就会出现在命令菜单里。你可以将这些命令提交到 git 与团队共享。[56]

自定义命令支持 $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。例如 /project:fix-github-issue 1234 会让 Claude 修复 issue #1234。你也可以把个人常用命令放在 ~/.claude/commands 中，供所有会话使用。[56]

3. 尝试常见工作流

Claude Code 不强制固定流程，因此社区中形成了一些高效的使用模式：[56]

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

适用于多数问题：[56]

  1. 让 Claude 先读相关文件/图片/URL，可以给模糊指引（“读处理日志的文件”）或明确文件名（“读 logging.py”），并强调先不要写代码。
  2. 这里特别适合使用子代理（subagents）做细节核查或问题调查，尤其在任务早期，可减少上下文压力而不损失效率。
  3. 让 Claude 为具体问题制定计划。建议使用 “think” 触发更深度思考；系统会根据 “think” < “think hard” < “think harder” < “ultrathink” 分配不同的思考预算。[56]
  4. 如果计划合理，可以让 Claude 写成文档或 GitHub issue，以便后续实现不满意时回退到这一步。
  5. 让 Claude 编码实现方案，并要求它在实现过程中自检合理性。
  6. 让 Claude 提交代码并创建 PR，必要时更新 README 或 changelog 说明修改内容。

步骤 #1–#2 非常关键：没有它们，Claude 往往会直接写代码。对于需要深思的问题，先研究再规划会显著提升表现。[56]

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

这是 Anthropic 很喜欢的工作流，适用于可通过单元/集成/E2E 测试验证的问题。TDD 与代理式编程结合会更强：[56]

  1. 让 Claude 按预期输入/输出编写测试，明确你在做 TDD，避免它为不存在的功能写 mock 实现。
  2. 让 Claude 运行测试并确认失败，并明确此阶段不要写实现代码。
  3. 测试满意后提交。
  4. 让 Claude 写代码通过测试，要求不要改测试，并持续迭代直到全绿。[56]
  5. 这一阶段可以让独立子代理验证实现是否过度拟合测试。
  6. 代码满意后提交。[56]

Claude 在有明确目标时表现最佳——如视觉稿、测试用例或其他输出。测试能提供可评估的目标，让 Claude 迭代直至成功。[56]

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

如果有视觉目标（UI 设计、图表），可采用类似流程：[56]

  1. 提供截图工具（如 Puppeteer MCP server、iOS 模拟器 MCP server，或手动截图）。
  2. 提供视觉稿（复制/粘贴或拖拽图片，或给出图片路径）。
  3. 让 Claude 实现设计，截图并反复调整直到匹配。
  4. 满意后提交。[56]

图：原文未提供图注

图注：原文未提供图注。[56]

d. 安全 YOLO 模式

如果你不想频繁监督，可以用 claude --dangerously-skip-permissions 跳过所有权限检查，让 Claude 自主完成任务。这适合修复 lint 或生成样板代码。[56]

但这很危险：可能导致数据丢失、系统损坏，甚至数据泄露（如提示注入攻击）。降低风险的做法是：在无网络的容器中运行，并使用其 参考实现（Docker Dev Containers）。[56]

e. 代码库问答（Codebase Q&A）

在新代码库入职时，Claude Code 是强大的学习工具。你可以像与同事结对一样提问，让 Claude 搜索代码库回答问题：[56]

  • 日志是如何工作的？
  • 如何新增一个 API endpoint？
  • foo.rs 第 134 行的 async move { ... } 是什么？
  • CustomerOnboardingFlowImpl 处理了哪些边界情况？
  • 为什么在第 333 行调用 foo() 而不是 bar()？
  • baz.py 第 334 行在 Java 中的等价实现是什么？

在 Anthropic，这类使用方式已成为核心入职工作流，显著提升上手速度并降低其他工程师负担。无需特殊提示，直接提问即可。[56]

图：原文未提供图注

图注：原文未提供图注。[56]

f. 用 Claude 处理 git

Claude 可以处理大量 git 操作，许多 Anthropic 工程师 90%+ 的 git 交互都交给 Claude：[56]

  • 搜索 git 历史（如“v1.2.3 包含哪些改动？”“谁维护这个功能？”“这个 API 为什么这么设计？”）
  • 撰写 commit message（Claude 会根据 diff 与历史上下文生成合适的描述）
  • 复杂 git 操作（回滚文件、解决 rebase 冲突、比较或移植补丁）

g. 用 Claude 处理 GitHub

Claude Code 也能管理 GitHub 交互：[56]

  • 创建 PR：理解“pr”简写并生成合适的提交信息
  • 一口气解决简单 code review 评论：让它修 PR 评论并推送到分支
  • 修复失败的构建或 lint
  • 对 open issues 做分类和分诊

这减少了你记忆 gh 命令语法的负担。[56]

h. 用 Claude 处理 Jupyter notebook

Anthropic 的研究与数据科学团队用 Claude Code 读写 Jupyter notebook。它能理解包括图片在内的输出，是探索数据的高效方式。[56]

推荐的轻量流程：在 VS Code 中同时打开 Claude Code 与 .ipynb 文件。你还可以让 Claude 帮你美化 notebook 或可视化，提升展示效果。[56]

4. 优化你的工作方式

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

a. 指令要具体

Claude Code 在指令更具体时成功率显著提升，尤其是第一次尝试。清晰的方向能减少后期纠偏。[56]

低质量指令 高质量指令
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 能推断意图，但不会读心。具体性是对齐预期的关键。[56]

图：原文未提供图注

图注：原文未提供图注。[56]

b. 给 Claude 图像

Claude 可以通过多种方式接收图像：[56]

  • 粘贴截图（macOS 可用 cmd+ctrl+shift+4 截图到剪贴板，再用 ctrl+v 粘贴；注意远程环境不支持 cmd+v）
  • 拖拽图片 进入输入框
  • 提供文件路径

这在 UI 开发的视觉稿、调试中的图表等场景尤为有用。即使不提供视觉内容，也可以明确告诉 Claude “视觉效果很重要”。[56]

图：原文未提供图注

图注：原文未提供图注。[56]

c. 明确告诉 Claude 需要处理哪些文件

使用 tab 补全可以快速引用仓库中的文件或目录，帮助 Claude 快速定位或更新正确的资源。[56]

图：原文未提供图注

图注：原文未提供图注。[56]

d. 给 Claude URL

在提示中直接贴 URL 让 Claude 拉取阅读。若同一域名频繁触发权限提示（如 docs.foo.com），可以用 /permissions 把域名加入 allowlist。[56]

e. 及早、频繁纠偏

自动接受模式（shift+tab 切换）可以让 Claude 自主执行，但更好的结果通常来自主动协作：在一开始就充分解释任务，必要时随时纠偏。[56]

可用于纠偏的四个工具：[56]

  • 让 Claude 先制定计划，并明确未经确认不得编码。
  • 按 Escape 中断 Claude（思考、工具调用、文件编辑等都可中断），保留上下文以便调整方向。
  • 双击 Escape 回溯历史，编辑之前的提示，尝试不同方向。
  • 让 Claude 撤销更改，通常配合中断与回溯使用。

虽然 Claude 偶尔能一次性完美解决问题，但使用纠偏工具通常能更快得到更好结果。[56]

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

长会话会堆积无关对话、文件内容与命令，导致性能下降或分心。建议在任务之间频繁使用 /clear 重置上下文。[56]

g. 复杂流程中使用清单与草稿

对于多步骤或需要穷举处理的大任务（如代码迁移、修复大量 lint 错误、运行复杂构建脚本），让 Claude 使用 Markdown 清单或 GitHub issue 作为“检查表 + 草稿本”会更高效。[56]

例如修复大量 lint 问题：[56]

  1. 让 Claude 运行 lint 命令，并把错误（含文件名与行号）写入 Markdown 清单
  2. 指示 Claude 逐条修复并验证，完成一条勾掉一条

h. 把数据传给 Claude

向 Claude 提供数据的方式很多：[56]

  • 直接复制粘贴 到提示里（最常见）
  • 管道输入 Claude Code（如 cat foo.txt | claude），适用于日志、CSV、大数据
  • 让 Claude 通过 bash/MCP/自定义命令拉取数据
  • 让 Claude 读文件或抓取 URL（图像也可）

多数会话会组合使用这些方式。例如可以先 pipe 一份日志，再让 Claude 用工具补充上下文调试。[56]

5. 用 headless mode 自动化基础设施

Claude Code 提供 headless mode，用于 CI、pre-commit、构建脚本等非交互场景。通过 -p 参数传入 prompt，并用 --output-format stream-json 获取流式 JSON 输出。[56]

注意：headless mode 不会跨会话持久化，每次会话都需要重新触发。[56]

a. 用 Claude 做 issue 分诊

headless mode 可用于 GitHub 事件触发的自动化，例如新 issue 创建时自动分析与打标签。公开的 Claude Code 仓库 就用 Claude 来检查新 issue 并分配标签。[56]

b. 用 Claude 作为“主观型 linter”

Claude Code 可以做传统 lint 工具难以覆盖的主观代码审查，例如拼写错误、过期注释、误导性的函数/变量名等。[56]

6. 多 Claude 协作提升效率

除了单实例使用，更强大的玩法是并行运行多个 Claude：[56]

a. 一个 Claude 写代码，另一个 Claude 验证

这是一种简单但高效的方法：一个 Claude 写代码，另一个审查或测试。类似多人协作，分离上下文往往更好：[56]

  1. 用 Claude 写代码
  2. 运行 /clear 或在另一个终端开启第二个 Claude
  3. 让第二个 Claude 审查第一个的工作
  4. 再开一个 Claude（或再次 /clear）同时读代码与审查反馈
  5. 由这个 Claude 根据反馈修改代码

你还可以让一个 Claude 写测试，另一个 Claude 写实现，并通过共享的草稿文件互相沟通。[56]

b. 保持多个仓库副本

与其等待一个 Claude 做完再继续，Anthropic 很多工程师会：[56]

  1. 创建 3–4 个 git checkout 放在不同目录
  2. 每个目录开一个终端标签页
  3. 在每个目录启动 Claude 分配不同任务
  4. 轮询查看进度 并处理权限请求

c. 使用 git worktrees

对于多个独立任务，git worktrees 是更轻量的方案：从同一仓库 checkout 多个分支到不同目录，共享历史但工作区隔离。[56]

这样你可以并行运行多个 Claude 实例，分别处理互不干扰的任务，例如一个 Claude 重构认证系统，另一个 Claude 构建数据可视化组件，彼此互不阻塞也避免冲突：[56]

  1. 创建 worktree：git worktree add ../project-feature-a feature-a
  2. 在每个 worktree 启动 Claude：cd ../project-feature-a && claude
  3. 按需新增更多 worktree（重复 1–2）

一些小技巧：[56]

  • 使用一致的命名规范
  • 每个 worktree 使用一个终端标签页
  • 如果你在 Mac 上使用 iTerm2，可以配置 通知 让 Claude 需要关注时提醒
  • 不同 worktree 使用不同 IDE 窗口
  • 结束后清理：git worktree remove ../project-feature-a

d. 用自定义 harness 搭配 headless mode

claude -p（headless mode）能在保留系统提示与内置工具的前提下，把 Claude Code 以编程方式嵌入更大流程。主要有两种模式：[56]

  1. 扇出（Fanning out）：用于大型迁移或分析（如成百上千日志或 CSV 的批量处理）：
  2. 让 Claude 先生成任务清单，例如列出 2000 个要从框架 A 迁移到 B 的文件。
  3. 逐个任务循环调用 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:*)
  4. 多次运行脚本并优化提示词，直到效果稳定。
  5. 管道（Pipelining）：把 Claude 接入已有的数据处理管线：
  6. 使用 claude -p “<your prompt>” --json | your_command，其中 your_command 是下一步处理命令。
  7. 结束。JSON 输出（可选）可提高自动化处理的结构化程度。

这两种场景都建议用 --verbose 便于调试；生产环境通常关闭 verbose 以保持输出整洁。[56]

你还有哪些 Claude Code 的实践技巧？欢迎在社媒上 @AnthropicAI 分享！[56]

致谢

本文由 Boris Cherny 撰写，汇集了 Claude Code 更广泛用户社区的最佳实践。特别感谢 Daisy Hollman、Ashwin Bhat、Cat Wu、Sid Bidasaria、Cal Rueb、Nodir Turakulov、Barry Zhang、Drew Hodun 以及更多 Anthropic 工程师的洞见与经验。[56]

想进一步学习？Explore courses