原文: English original · Anthropic/OpenAI 官方

Claude Code：agentic coding 最佳实践

当前 source URL 会重定向到题为 “Best practices for Claude Code” 的 Claude Code 文档页。

本文汇集了一些技巧和模式，帮助你从 Claude Code 中获得最大价值，涵盖配置环境、扩展到并行 session 等场景。

Claude Code 是一个 agentic coding 环境。它不同于回答问题后等待下一步的聊天机器人；Claude Code 可以读取你的文件、运行命令、做出修改，并在你观察、重新引导或暂时离开时自主推进问题。这会改变你的工作方式。你不再是自己写代码再请 Claude review，而是描述你想要什么，由 Claude 想办法构建。Claude 会探索、规划并实现。但这种自主性仍然有学习曲线。

Claude 会在一些你需要理解的约束下工作。本指南覆盖的模式，已经在 Anthropic 内部团队，以及在各种代码库、语言和环境中使用 Claude Code 的工程师那里证明有效。要了解 agentic loop 在底层如何运作，请参阅 How Claude Code works。

大多数最佳实践都基于一个约束：Claude 的上下文窗口很快会填满，填得越满，表现越会下降。Claude 的上下文窗口保存你的整段对话，包括每条消息、Claude 读取的每个文件，以及每段命令输出。但它可能很快被填满。一次调试 session 或代码库探索，就可能生成并消耗数万 token。这很重要，因为 LLM 的表现会随着上下文填满而下降。

当上下文窗口快满时，Claude 可能开始“忘记”较早的指令，或犯更多错误。上下文窗口是最重要的待管理资源。要了解一个 session 在实践中如何填满，可以观看交互式 walkthrough，了解启动时会加载什么、每次读取文件会花费多少。用自定义状态行持续跟踪上下文用量，并参阅 Reduce token usage，了解降低 token 使用量的策略。

给 Claude 一种验证自己工作的方式

给 Claude 一个可以运行的检查：测试、构建，或可对比的截图。这就是你需要盯着看的 session 和你可以放心离开的 session 之间的区别。

Claude 会在工作看起来完成时停止。没有可运行的检查时，“看起来完成”就是唯一可用信号，而你会变成验证 loop：每个错误都要等你发现。给 Claude 一个能产生通过或失败结果的东西，loop 就会自行闭合。Claude 完成工作、运行检查、读取结果，并迭代直到检查通过。

检查可以是任何能在对话中返回 Claude 可读信号的东西：测试套件、构建退出码、linter、把输出和 fixture 做 diff 的脚本，或用于对比设计稿的浏览器截图。

策略	Before	After
提供验证标准	“implement a function that validates email addresses”	“write a validateEmail function. example test cases: user@example.com is true, invalid is false, user@.com is false. run the tests after implementing”
通过视觉方式验证 UI 变更	“make the dashboard look better”	“[paste screenshot] implement this design. take a screenshot of the result and compare it to the original. list differences and fix them”
处理根因，而不是症状	“the build is failing”	“the build fails with this error: [paste error]. fix it and verify the build succeeds. address the root cause, don’t suppress the error”

检查存在之后，决定它在停止前有多强的门槛作用：

在一个 prompt 中：像上表一样，在同一条消息里要求 Claude 运行检查并迭代。
跨一个 session：把检查设为 /goal 条件。一个单独的 evaluator 会在每轮之后重新检查，Claude 会持续工作直到条件成立。
作为确定性 gate：Stop hook 会以脚本形式运行你的检查，并阻止本轮结束，直到检查通过。Claude Code 会在连续 8 次被阻止后覆盖该 hook 并结束本轮。
通过第二意见：使用 verification subagent，或使用会检查自身发现的 dynamic workflow，让一个新模型尝试反驳结果，这样执行工作的 agent 就不会同时充当评分者。

每一步都是用设置成本换取注意力。prompt 版本今天适用于任何任务。/goal 和 Stop hook 版本则能让无人值守运行正确结束。让 Claude 展示证据，而不是宣称成功：测试输出、它运行的命令及返回结果，或结果截图。审阅证据比你自己重新运行验证更快，也适用于你没有盯着看的 session。

先探索，再计划，然后写代码

把研究和规划与实现分开，避免解决错误的问题。

让 Claude 直接开始编码，可能会产出解决了错误问题的代码。使用 plan mode，把探索和执行分离。推荐 workflow 有四个阶段：

Explore

进入 plan mode。Claude 读取文件并回答问题，但不做修改。

claude (plan mode)
read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.

Plan

要求 Claude 创建一份详细实现计划。

claude (plan mode)

I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.

按 Ctrl+G，可以在你的文本编辑器中打开计划，并在 Claude 继续之前直接编辑。

Implement

退出 plan mode，让 Claude 编码，并按计划验证。

claude (default mode)

implement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.

Commit

要求 Claude 用描述性信息提交，并创建 PR。

claude (default mode)

commit with a descriptive message and open a PR

plan mode 很有用，但也会增加开销。对于范围清晰、修复很小的任务，比如修正错别字、添加一行日志，或重命名变量，可以直接让 Claude 去做。当你不确定方法、变更会修改多个文件，或你不熟悉要改的代码时，规划最有用。如果你能用一句话描述 diff，就跳过计划。

在 prompt 中提供具体上下文

你的指令越精确，需要返工纠正的次数就越少。

Claude 可以推断意图，但不能读心。引用具体文件、说明约束，并指出示例模式。

策略	Before	After
界定任务范围。说明哪个文件、什么场景，以及测试偏好。	“add tests for foo.py”	“write a test for foo.py covering the edge case where the user is logged out. avoid mocks.”
指向来源。把 Claude 引到可以回答问题的来源。	“why does ExecutionFactory have such a weird api?”	“look through ExecutionFactory’s git history and summarize how its api came to be”
引用现有模式。把 Claude 指向你代码库中的模式。	“add a calendar widget”	“look at how existing widgets are implemented on the home page to understand the patterns. HotDogWidget.php is a good example. 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 codebase.”
描述症状。提供症状、可能位置，以及怎样才算“修好”。	“fix the login bug”	“users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it”

模糊 prompt 在你探索且有余地纠偏时会有用。像 "what would you improve in this file?" 这样的 prompt，可能会浮现出你原本想不到的问题。

提供丰富内容

使用 @ 引用文件、粘贴截图或图片，或直接通过管道传入数据。

你可以用几种方式向 Claude 提供丰富数据：

用 @ 引用文件，而不是描述代码在哪里。Claude 会在响应前读取该文件。
直接粘贴图片。可以复制/粘贴，或把图片拖放到 prompt 中。
提供文档和 API reference 的 URL。使用 /permissions 把常用域名加入 allowlist。
通过运行 cat error.log | claude 管道传入数据，把文件内容直接发送进去。
让 Claude 自己获取所需内容。告诉 Claude 使用 Bash 命令、MCP tools，或通过读取文件来拉取上下文。

配置你的环境

少数设置步骤能显著提升 Claude Code 在所有 session 中的效果。要完整了解扩展功能以及何时使用各功能，请参阅 Extend Claude Code。

编写有效的 CLAUDE.md

运行 /init，根据你当前项目结构生成一个初始 CLAUDE.md 文件，然后持续细化。

CLAUDE.md 是 Claude 在每次对话开始时都会读取的特殊文件。把 Bash 命令、代码风格和 workflow 规则放进去。这会给 Claude 提供它无法仅凭代码推断出的持久上下文。/init 命令会分析你的代码库，检测构建系统、测试框架和代码模式，为后续细化打下可靠基础。CLAUDE.md 文件没有必需格式，但要保持简短且便于人阅读。例如：

# 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 会在每个 session 中加载，因此只应包含普遍适用的内容。对于只在某些时候相关的领域知识或 workflow，改用 skills。Claude 会按需加载它们，而不会膨胀每次对话。保持简洁。对每一行都问一句：“删掉这一行会导致 Claude 犯错吗？”如果不会，就删掉。臃肿的 CLAUDE.md 文件会让 Claude 忽略你的实际指令！

Include	Exclude
Claude 猜不到的 Bash 命令	Claude 可以通过阅读代码搞清楚的任何内容
不同于默认值的代码风格规则	Claude 已经知道的标准语言约定
测试说明和偏好的测试 runner	详细 API 文档（改为链接到文档）
仓库协作规范（分支命名、PR 约定）	频繁变化的信息
项目特定的架构决策	很长的解释或教程
开发者环境易错点（必需 env vars）	按文件逐个描述代码库
常见易错点或非显而易见的行为	“写干净代码”这类不言自明的实践

如果 Claude 在已有规则禁止的情况下仍反复做你不想要的事，这个文件很可能太长，规则被淹没了。如果 Claude 问的问题明明已在 CLAUDE.md 中回答，可能是措辞有歧义。像对待代码一样对待 CLAUDE.md：出问题时检查它，定期修剪，并通过观察 Claude 的行为是否真的改变来测试修改。你可以通过增加强调词，比如 “IMPORTANT” 或 “YOU MUST”，来提升遵循度。

把 CLAUDE.md 提交到 git，让团队可以共同贡献。这个文件会随时间复利增值。CLAUDE.md 文件可以使用 @path/to/import 语法导入其他文件：

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

你可以把 CLAUDE.md 文件放在几个位置：

Home folder（~/.claude/CLAUDE.md）：适用于所有 Claude sessions
Project root（./CLAUDE.md）：提交到 git，与团队共享
Project root（./CLAUDE.local.md）：个人的项目特定笔记；把这个文件加入 .gitignore，避免与团队共享
父目录：适用于 monorepo，其中 root/CLAUDE.md 和 root/foo/CLAUDE.md 都会被自动拉入
子目录：当 Claude 读取这些目录中的文件时，会按需拉入子目录的 CLAUDE.md 文件

配置权限

使用 auto mode 让 classifier 处理批准，使用 /permissions allowlist 具体命令，或使用 /sandbox 做 OS 级隔离。每一种方式都能在让你保持控制的同时减少打断。

默认情况下，Claude Code 会对可能修改你系统的动作请求许可：文件写入、Bash 命令、MCP tools 等等。这是安全的，但很繁琐。到第十次批准时，你其实已经不再认真审查，只是在一路点击。减少这些打断有三种方式：

Auto mode：由一个单独的 classifier model 审查命令，只阻止看起来有风险的动作：范围升级、未知基础设施，或由 hostile content 驱动的动作。适合你信任任务的大方向，但不想每一步都点击的情况
Permission allowlists：允许你已知安全的特定 tools，比如 npm run lint 或 git commit
Sandboxing：启用 OS 级隔离，限制文件系统和网络访问，让 Claude 能在定义好的边界内更自由地工作

阅读更多关于 permission modes、permission rules 和 sandboxing 的内容。

使用 CLI tools

告诉 Claude Code 在与外部服务交互时使用 gh、aws、gcloud 和 sentry-cli 等 CLI tools。

CLI tools 是与外部服务交互时最节省上下文的方式。如果你使用 GitHub，请安装 gh CLI。Claude 知道如何用它创建 issue、打开 pull request 和读取评论。没有 gh 时，Claude 仍可使用 GitHub API，但未经认证的请求经常会遇到速率限制。Claude 也很擅长学习它原本不了解的 CLI tools。可以尝试这样的 prompt：Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C.

连接 MCP servers

运行 claude mcp add，连接 Notion、Figma 或你的数据库等外部 tools。

通过 MCP servers，你可以要求 Claude 根据 issue tracker 实现功能、查询数据库、分析监控数据、集成 Figma 设计，并自动化 workflow。

设置 hooks

把 hooks 用于那些每次都必须发生、零例外的动作。

hooks 会在 Claude 的 workflow 中的特定点自动运行脚本。与作为建议的 CLAUDE.md 指令不同，hooks 是确定性的，可以保证动作发生。Claude 可以为你编写 hooks。可以尝试这样的 prompt：“Write a hook that runs eslint after every file edit” 或 “Write a hook that blocks writes to the migrations folder.” 直接编辑 .claude/settings.json 可以手动配置 hooks，运行 /hooks 可以浏览已配置内容。

创建 skills

在 .claude/skills/ 中创建 SKILL.md 文件，为 Claude 提供领域知识和可复用 workflow。

skills 会用与你的项目、团队或领域相关的信息扩展 Claude 的知识。Claude 会在相关时自动应用它们，你也可以用 /skill-name 直接调用。创建 skill 的方式，是在 .claude/skills/ 中添加一个带有 SKILL.md 的目录：

---
name: api-conventions
description: REST API design conventions for our services
---
# API Conventions
- Use kebab-case for URL paths
- Use camelCase for JSON properties
- Always include pagination for list endpoints
- Version APIs in the URL path (/v1/, /v2/)

skills 也可以定义可直接调用的可重复 workflow：

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.
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

运行 /fix-issue 1234 调用它。对于有副作用、你希望手动触发的 workflow，使用 disable-model-invocation: true。

创建自定义 subagents

在 .claude/agents/ 中定义专门的 assistants，Claude 可以把隔离任务委派给它们。

subagents 会在自己的上下文中运行，并有自己的一组允许 tools。它们适合那些需要读取很多文件，或需要专门聚焦但又不想弄乱主对话的任务。

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.

明确告诉 Claude 使用 subagents：“Use a subagent to review this code for security issues.”

安装 plugins

运行 /plugin 浏览 marketplace。plugins 会在无需配置的情况下添加 skills、tools 和 integrations。

plugins 会把来自社区和 Anthropic 的 skills、hooks、subagents 和 MCP servers 打包成一个可安装单元。如果你使用类型化语言，请安装 code intelligence plugin，为 Claude 提供精确的符号导航和编辑后的自动错误检测。关于如何在 skills、subagents、hooks 和 MCP 之间选择，请参阅 Extend Claude Code。

有效沟通

你与 Claude Code 沟通的方式，会显著影响结果质量。

提问代码库问题

像向高级工程师提问一样向 Claude 提问。

在接手新代码库时，用 Claude Code 学习和探索。你可以向 Claude 提出和你会问另一位工程师一样的问题：

日志是怎么工作的？
我如何创建一个新的 API endpoint？
foo.rs 第 134 行的 async move { ... } 是什么作用？
CustomerOnboardingFlowImpl 处理哪些边界情况？
为什么这段代码在第 333 行调用 foo() 而不是 bar()？

以这种方式使用 Claude Code，是一种有效的 onboarding workflow，可以缩短上手时间，并减轻其他工程师的负担。不需要特殊 prompt：直接提问即可。

让 Claude 访谈你

对于更大的功能，先让 Claude 访谈你。从最小 prompt 开始，并要求 Claude 使用 AskUserQuestion tool 访谈你。

Claude 会询问一些你可能还没考虑到的事情，包括技术实现、UI/UX、边界情况和取舍。

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.
Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

spec 完成后，开启一个新 session 来执行它。新 session 拥有干净上下文，完全聚焦实现，而你有一份书面 spec 可以引用。最有用的 spec 是自包含的：它会点名涉及的文件和接口，说明什么不在范围内，并以一个端到端验证步骤收尾，证明功能确实可用。花时间把 spec 写精确，比花时间盯着实现更有回报。

管理你的 session

对话是持久且可回退的。利用好这一点！

及早且频繁地纠偏

一发现 Claude 偏离方向，就立即纠正。

最好的结果来自紧密反馈 loop。虽然 Claude 偶尔能第一次就完美解决问题，但快速纠正通常能更快产出更好的方案。

Esc：用 Esc 键在 Claude 动作进行中停止它。上下文会保留，因此你可以重定向。
Esc + Esc 或 /rewind：按两次 Esc 或运行 /rewind 打开 rewind 菜单，恢复之前的对话和代码状态，或从选定消息开始总结。
"Undo that"：让 Claude revert 它的修改。
/clear：在无关任务之间重置上下文。带有无关上下文的长 session 可能降低表现。

如果你在一个 session 中针对同一问题纠正 Claude 超过两次，上下文就已经被失败方案弄乱了。运行 /clear，用更具体、吸收了你已学到内容的 prompt 重新开始。一个干净 session 搭配更好的 prompt，几乎总是胜过一个堆积了纠正记录的长 session。

积极管理上下文

在无关任务之间运行 /clear 来重置上下文。

Claude Code 会在你接近上下文限制时自动压缩对话历史，在释放空间的同时保留重要代码和决策。长 session 中，Claude 的上下文窗口可能填满无关对话、文件内容和命令。这会降低表现，有时还会分散 Claude 的注意力。

经常在任务之间使用 /clear，完全重置上下文窗口
当 auto compaction 触发时，Claude 会总结最重要的内容，包括代码模式、文件状态和关键决策
如需更多控制，运行 /compact <instructions>，例如 /compact Focus on the API changes
要只压缩部分对话，使用 Esc + Esc 或 /rewind，选择一个消息 checkpoint，然后选择 Summarize from here 或 Summarize up to here。前者会压缩该点之后的消息，同时保留更早上下文；后者会压缩更早消息，同时完整保留近期消息。参阅 Restore vs. summarize。
在 CLAUDE.md 中用类似 "When compacting, always preserve the full list of modified files and any test commands" 的指令自定义压缩行为，确保关键上下文在总结中留存
对于不需要留在上下文中的快速问题，使用 /btw。答案会出现在可关闭的 overlay 中，且永远不会进入对话历史，因此你可以检查细节而不增加上下文。

使用 subagents 做调查

用 "use subagents to investigate X" 委派研究。它们会在单独上下文中探索，让你的主对话保持清爽，以便实现。

由于上下文是你的根本约束，subagents 是最强大的可用 tools 之一。当 Claude 研究代码库时，它会读取很多文件，所有这些都会消耗你的上下文。subagents 会在独立上下文窗口中运行，并回报摘要：

Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

subagent 会探索代码库、读取相关文件，并回报发现，而不会弄乱你的主对话。Claude 实现某个东西后，你也可以用 subagents 做验证：

use a subagent to review this code for edge cases

用 checkpoints 回退

你发送的每个 prompt 都会创建一个 checkpoint。你可以把对话、代码，或二者恢复到任何之前的 checkpoint。

Claude 会在每次修改前自动给文件做快照，因此 checkpoint 可以恢复它们。双击 Escape 或运行 /rewind 打开 rewind 菜单。你可以只恢复对话、只恢复代码、二者都恢复，或从选定消息开始总结。详情参阅 Checkpointing。与其仔细计划每一步，不如让 Claude 尝试一些有风险的做法。如果不可行，就 rewind 再试另一个方向。

Checkpoints 会跨 session 持久保存，因此你关闭终端后，之后仍然可以 rewind。

Checkpoints 只跟踪 Claude 做出的变更，不跟踪外部进程。这不能替代 git。

恢复对话

用 /rename 给 session 命名，并把它们当作分支：每条 workstream 都有自己的持久上下文。

Claude Code 会在本地保存对话，因此当一个任务跨越多次工作时，你不必重新解释上下文。运行 claude --continue 继续最近的 session，或运行 claude --resume 从列表中选择。给 session 起 oauth-migration 这样的描述性名称，方便之后找到。参阅 Manage sessions，了解完整的 resume、branch 和命名控制。

自动化和扩展

一旦你能高效使用一个 Claude，就可以用并行 session、non-interactive mode 和 fan-out 模式放大产出。到目前为止，所有内容都假设是一个人、一个 Claude、一段对话。但 Claude Code 可以横向扩展。本节展示如何做成更多事。

运行 non-interactive mode

在 CI、pre-commit hooks 或脚本中使用 claude -p "prompt"。加上 --output-format stream-json --verbose 可以得到 streaming JSON 输出。

使用 claude -p "your prompt" 时，你可以以 non-interactive 方式运行 Claude，不创建 session。Non-interactive mode 是把 Claude 集成进 CI pipelines、pre-commit hooks 或任何自动化 workflow 的方式。输出格式让你可以用程序解析结果：纯文本、JSON 或 streaming JSON。

# One-off queries
claude -p "Explain what this project does"

# Structured output for scripts
claude -p "List all API endpoints" --output-format json

# Streaming for real-time processing
claude -p "Analyze this log file" --output-format stream-json --verbose

运行多个 Claude sessions

并行运行多个 Claude sessions，以加速开发、运行隔离实验，或启动复杂 workflow。

选择与你希望自行协调程度匹配的并行方式：

Worktrees：在隔离的 git checkouts 中运行独立 CLI sessions，避免编辑冲突
Desktop app：以可视化方式管理多个本地 sessions，每个都在自己的 worktree 中
Claude Code on the web：在 Anthropic 托管的云基础设施上，以隔离 VM 运行 sessions
Agent teams：多个 sessions 的自动化协调，包含共享任务、消息传递和 team lead

除了并行化工作，多个 sessions 还能支持质量导向的 workflow。新鲜上下文会改善 code review，因为 Claude 不会偏向自己刚写的代码。例如，可以使用 Writer/Reviewer 模式：

Session A (Writer)	Session B (Reviewer)
`Implement a rate limiter for our API endpoints`	`Review the rate limiter implementation in @src/middleware/rateLimiter.ts. Look for edge cases, race conditions, and consistency with our existing middleware patterns.`
`Here's the review feedback: [Session B output]. Address these issues.`

你也可以用类似方式处理测试：让一个 Claude 写测试，再让另一个 Claude 写代码来通过它们。

Fan out 到多个文件

遍历任务列表，为每项调用 claude -p。用 --allowedTools 限定批处理操作的权限范围。

对于大型迁移或分析，可以把工作分发到许多并行 Claude 调用：

生成任务列表

让 Claude 列出所有需要迁移的文件（例如 list all 2,000 Python files that need migrating）

编写脚本遍历列表

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

先在少数文件上测试，再规模化运行

根据前 2-3 个文件暴露的问题优化你的 prompt，然后在完整集合上运行。--allowedTools 标志会限制 Claude 能做什么；在无人值守运行时，这一点很重要。

你也可以把 Claude 集成到已有数据或处理 pipeline 中：

claude -p "<your prompt>" --output-format json | your_command

开发期间使用 --verbose 进行调试，生产中关闭。

使用 auto mode 自主运行

要实现不中断执行并带后台安全检查，请使用 auto mode。一个 classifier model 会在命令运行前审查它们，阻止范围升级、未知基础设施和由 hostile content 驱动的动作，同时让常规工作无需 prompt 即可继续。

claude --permission-mode auto -p "fix all lint errors"

对于带 -p 标志的 non-interactive runs，如果 classifier 反复阻止动作，auto mode 会中止，因为没有用户可以接手。阈值请参阅 when auto mode falls back。

添加 adversarial review 步骤

在把任务视为完成之前，让一个 subagent 在新鲜上下文中审查 diff 并报告缺口。

Claude 无人值守工作得越久，在认定完成前做一次独立检查就越重要。运行在新鲜 subagent 上下文中的 reviewer 只看到 diff 和你给出的标准，而不是产生变更的推理过程，因此它会独立评估结果。对于正确性检查，运行内置的 /code-review skill；它会在新鲜 subagent 中 review 当前 diff，检查 bug，并把 findings 返回给 session。

如果要按你的计划检查 diff，可以自己编写 review prompt。写清要检查的工作、用来对照的计划，以及什么算作 finding：

Use a subagent to review the rate limiter diff against PLAN.md. Check that
every requirement is implemented, the listed edge cases have tests, and
nothing outside the task's scope changed. Report gaps, not style preferences.

由于 reviewer 作为 subagent 运行，实现 session 会直接收到缺口并可以修复，再重新 review，而无需你在窗口之间复制 findings。对于更长的自主运行，agent team 可以在许多任务中持续这个 loop，而你只需抽查记录下来的 findings。

被要求找缺口的 reviewer 通常会报告一些问题，即使工作本身没问题，因为这正是你要求它做的。追逐每一条 finding 会导致过度工程：额外抽象层、防御性代码，以及为不可能发生的情况写测试。告诉 reviewer 只标记影响正确性或既定需求的缺口，其余视为可选。

避免常见失败模式

这些是常见错误。及早识别可以节省时间：

The kitchen sink session。你从一个任务开始，然后问 Claude 一些无关内容，接着又回到第一个任务。上下文里充满无关信息。

Fix：在无关任务之间使用 /clear。

反复纠正。Claude 做错了，你纠正它，它还是错，你再纠正。上下文被失败方案污染。

Fix：两次纠正失败后，/clear，并把学到的内容吸收到一个更好的初始 prompt 里。

过度指定的 CLAUDE.md。如果你的 CLAUDE.md 太长，Claude 会忽略其中一半，因为重要规则淹没在噪声中。

Fix：严格修剪。如果 Claude 在没有该指令时已经能正确做某事，就删除它或把它转成 hook。

trust-then-verify gap。Claude 产出一个看起来合理、但没有处理边界情况的实现。

Fix：始终提供验证（测试、脚本、截图）。如果你无法验证，就不要发布。

无限探索。你要求 Claude “调查”某事，但没有界定范围。Claude 会读取数百个文件，填满上下文。

Fix：狭窄地界定调查范围，或使用 subagents，让探索不消耗你的主上下文。

培养你的直觉

本指南中的模式不是一成不变的。它们是在一般情况下效果不错的起点，但未必适合每种场景。有时你应该让上下文累积，因为你正深陷一个复杂问题，历史很有价值。有时你应该跳过计划，让 Claude 自己弄清楚，因为任务本身是探索性的。有时模糊 prompt 恰好合适，因为你想先看看 Claude 如何解释问题，再约束它。留意什么有效。

当 Claude 产出优秀结果时，注意你做了什么：prompt 结构、你提供的上下文、当时所处的 mode。当 Claude 表现吃力时，问问原因。上下文太嘈杂了吗？prompt 太模糊了吗？任务太大，无法一次完成吗？随着时间推移，你会发展出任何指南都无法捕捉的直觉。你会知道什么时候该具体，什么时候该开放；什么时候该计划，什么时候该探索；什么时候该清理上下文，什么时候该让它累积。

Claude Code：agentic coding 最佳实践

Claude Code：agentic coding 最佳实践

给 Claude 一种验证自己工作的方式

先探索，再计划，然后写代码

在 prompt 中提供具体上下文

提供丰富内容

配置你的环境

编写有效的 CLAUDE.md

配置权限

使用 CLI tools

连接 MCP servers

设置 hooks

创建 skills

创建自定义 subagents

安装 plugins

有效沟通

提问代码库问题

让 Claude 访谈你

管理你的 session

及早且频繁地纠偏

积极管理上下文

使用 subagents 做调查

用 checkpoints 回退

恢复对话

自动化和扩展

运行 non-interactive mode

运行多个 Claude sessions

Fan out 到多个文件

使用 auto mode 自主运行

添加 adversarial review 步骤

避免常见失败模式

培养你的直觉

相关资源