核验日期：2026-07-08

内容来源：Anthropic Engineering 官方技术博客。本文先作为 Claude Code 专区后台草稿入库，发布前应由内容人员复核标题、摘要、图片、来源链接与是否需要补充本站实践说明。 来源：https://www.anthropic.com/engineering/claude-code-best-practices
Canonical: https://code.claude.com/docs/en/best-practices
发布日期：2025-04-18

Claude Code：智能体式编码最佳实践

Claude Code 最佳实践

从配置环境到扩展并行会话，介绍充分发挥 Claude Code 能力的技巧和模式。

Claude Code 是一个智能体式编码环境。与回答问题后等待的聊天机器人不同，Claude Code 可以读取你的文件、运行命令、做出修改，并在你旁观、纠偏或完全离开时自主推进问题。

这会改变你的工作方式。你不再是自己写代码再请 Claude 审查，而是描述你想要什么，然后由 Claude 判断如何构建。Claude 会探索、规划并实现。

但这种自主性仍然有学习曲线。Claude 在一些你需要理解的约束内工作。

本指南涵盖了一些已经在 Anthropic 内部团队，以及使用 Claude Code 处理各种代码库、语言和环境的工程师中被证明有效的模式。要了解智能体循环在底层如何工作，请参见 How Claude Code works。

大多数最佳实践都基于一个约束：Claude 的上下文窗口很快会填满，而且随着填满，性能会下降。

Claude 的上下文窗口保存你的整个对话，包括每条消息、Claude 读取的每个文件，以及每条命令输出。不过，它很容易迅速填满。一次调试会话或代码库探索，就可能生成并消耗数万个 token。

这很重要，因为 LLM 性能会随着上下文填满而下降。当上下文窗口快满时，Claude 可能开始「忘记」早先的指令，或犯更多错误。上下文窗口是最重要的管理资源。要了解会话在实践中如何填满，可以观看交互式演示，了解启动时会加载什么，以及每次文件读取的成本。用自定义状态行持续跟踪上下文使用情况，并查看 Reduce token usage 了解减少 token 使用的策略。

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

给 Claude 一个它可以运行的检查：测试、构建，或可对比的截图。这决定了你是在旁边盯着一次会话，还是可以放心离开。

当工作看起来完成时，Claude 就会停下。如果没有它能运行的检查，「看起来完成」就是唯一可用信号，而你会变成验证循环：每个错误都要等你发现。给 Claude 一个能产生通过或失败结果的东西，这个循环就能自己闭合。Claude 完成工作、运行检查、读取结果，然后不断迭代，直到检查通过。

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

策略 修改前 修改后
提供验证标准 "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"

一旦检查存在，就决定它对停止工作的约束有多强：

  • 在一个提示词中：要求 Claude 在同一条消息中运行检查并迭代，就像上表中的示例一样。
  • 跨会话：将检查设置为 /goal 条件。一个独立评估器会在每轮之后重新检查，Claude 会一直工作直到条件成立。
  • 作为确定性门禁：Stop hook 将你的检查作为脚本运行，并阻止该轮结束，直到检查通过。Claude Code 会在连续 8 次被 hook 阻止后覆盖该 hook 并结束该轮。
  • 通过第二意见：验证子智能体或会检查自身发现的动态工作流，会让一个新的模型尝试反驳结果，这样执行工作的智能体就不是给自己打分的那个。

每一步都是用设置换取注意力。提示词版本今天适用于任何任务。/goal 和 Stop hook 版本则能让无人值守的运行在没有你的情况下正确完成。

让 Claude 展示证据，而不是只声称成功：测试输出、它运行的命令及返回内容，或结果截图。审查证据比你自己重新运行验证更快，而且适用于你没有盯着看的会话。

先探索，再规划，然后编码

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

让 Claude 直接跳到编码，可能会产出解决了错误问题的代码。使用计划模式，把探索与执行分开。

推荐工作流有四个阶段：

进入计划模式。Claude 会读取文件并回答问题，但不做修改。
```txt claude (plan mode) theme={null}
read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.
```
要求 Claude 创建详细实现计划。
```txt claude (plan mode) theme={null}
I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.
```

在 Claude 继续之前，按 `Ctrl+G` 在文本编辑器中打开计划并直接编辑。
退出计划模式，让 Claude 根据计划进行编码和验证。
```txt claude (default mode) theme={null}
implement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.
```
要求 Claude 用描述性信息提交并创建 PR。
```txt claude (default mode) theme={null}
commit with a descriptive message and open a PR
```
计划模式很有用，但也会带来额外开销。

对于范围清楚且修复很小的任务（例如修复拼写错误、添加一行日志，或重命名变量），直接要求 Claude 完成即可。

当你不确定方法、改动涉及多个文件，或不熟悉要修改的代码时，规划最有用。如果你能用一句话描述 diff，就跳过计划。

在提示词中提供具体上下文

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

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

策略 修改前 修改后
**限定任务范围。**说明哪个文件、什么场景，以及测试偏好。 "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"

当你在探索并且可以接受中途纠偏时，模糊提示词也可能有用。像 "what would you improve in this file?" 这样的提示，可能发现你原本不会想到要问的内容。

提供丰富内容

使用 `@` 引用文件，粘贴截图/图片，或直接管道输入数据。

你可以通过多种方式向 Claude 提供丰富数据：

  • 用 @ 引用文件，而不是描述代码在哪里。Claude 会在回答前读取该文件。
  • 直接粘贴图片。将图片复制/粘贴或拖放到提示词中。
  • 提供 URL，用于文档和 API 参考。使用 /permissions 将常用域名加入 allowlist。
  • 管道输入数据，例如运行 cat error.log | claude，直接发送文件内容。
  • 让 Claude 自己获取所需内容。告诉 Claude 使用 Bash 命令、MCP 工具或读取文件来拉取上下文。

配置你的环境

一些设置步骤可以显著提升 Claude Code 在所有会话中的效果。要完整了解扩展功能以及每种功能的适用场景，请参见 Extend Claude Code。

编写有效的 CLAUDE.md

运行 `/init`，根据当前项目结构生成一个初始 CLAUDE.md 文件，然后随着时间推移不断完善。

CLAUDE.md 是 Claude 在每次对话开始时都会读取的特殊文件。把 Bash 命令、代码风格和工作流规则放进去。这会给 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 每个会话都会加载，所以只包含广泛适用的内容。对于只在某些时候相关的领域知识或工作流，改用 skills。Claude 会按需加载它们，而不会让每次对话都变臃肿。

保持简洁。对每一行都问一句："删除这一行会导致 Claude 犯错吗？" 如果不会，就删掉。臃肿的 CLAUDE.md 会导致 Claude 忽略你真正的指令！

✅ 包含 ❌ 排除
Claude 猜不到的 Bash 命令 Claude 通过阅读代码就能弄明白的内容
与默认不同的代码风格规则 Claude 已经知道的标准语言约定
测试说明和偏好的测试运行器 详细 API 文档（改为链接到文档）
仓库协作礼仪（分支命名、PR 约定） 频繁变化的信息
项目特定的架构决策 长篇解释或教程
开发环境特殊点（必需环境变量） 逐文件描述代码库
常见坑或非显而易见的行为 像 "write clean code" 这种不言自明的实践

如果 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 文件放在多个位置：

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

配置权限

使用 [auto mode](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode) 让分类器处理批准，使用 `/permissions` 将特定命令加入 allowlist，或使用 `/sandbox` 做操作系统级隔离。每种方式都能减少中断，同时让你保持控制。

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

  • Auto mode：一个独立分类器模型审查命令，只阻止看起来有风险的内容：范围升级、未知基础设施，或由恶意内容驱动的操作。当你信任任务大方向、但不想逐步点击批准时，它最合适
  • 权限 allowlist：允许你知道安全的特定工具，例如 npm run lint 或 git commit
  • 沙盒：启用操作系统级隔离，限制文件系统和网络访问，让 Claude 能在定义好的边界内更自由地工作

阅读更多关于权限模式、权限规则和沙盒的信息。

使用 CLI 工具

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

CLI 工具是与外部服务交互时最节省上下文的方式。如果你使用 GitHub，请安装 gh CLI。Claude 知道如何用它创建 issue、打开 pull request 和读取评论。没有 gh 时，Claude 仍然可以使用 GitHub API，但未认证请求通常会触发速率限制。

Claude 也很擅长学习它尚不了解的 CLI 工具。可以尝试这样的提示词：Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C.

连接 MCP 服务器

运行 `claude mcp add` 来连接 Notion、Figma 或你的数据库等外部工具。

借助 MCP servers，你可以让 Claude 根据 issue tracker 实现功能、查询数据库、分析监控数据、集成 Figma 设计，并自动化工作流。

设置 hooks

对于必须每次都执行、且不能有任何例外的动作，使用 hooks。

Hooks 会在 Claude 工作流的特定点自动运行脚本。不同于作为建议的 CLAUDE.md 指令，hooks 是确定性的，可以保证动作发生。

Claude 可以为你编写 hooks。可以尝试这样的提示："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 提供领域知识和可复用工作流。

Skills 用与你的项目、团队或领域相关的信息扩展 Claude 的知识。Claude 会在相关时自动应用它们，你也可以用 /skill-name 直接调用。

通过在 .claude/skills/ 下添加一个包含 SKILL.md 的目录来创建 skill：

---
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 也可以定义可直接调用的可重复工作流：

---
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 调用它。对于带有副作用、且你希望手动触发的工作流，使用 disable-model-invocation: true。

创建自定义子智能体

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

Subagents 在自己的上下文中运行，并拥有自己的一组允许工具。它们适合需要读取大量文件或需要专门聚焦的任务，同时不会弄乱你的主对话。

---
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 使用子智能体："Use a subagent to review this code for security issues."

安装插件

运行 `/plugin` 浏览市场。插件无需配置即可添加 skills、工具和集成。

Plugins 将 skills、hooks、subagents 和 MCP servers 打包成来自社区和 Anthropic 的单个可安装单元。如果你使用带类型的语言，请安装一个代码智能插件，为 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 是一种有效的入职工作流，可以缩短上手时间，并减少其他工程师的负担。不需要特殊提示：直接提问即可。

让 Claude 采访你

对于较大的功能，先让 Claude 采访你。从一个最小提示词开始，要求 Claude 使用 `AskUserQuestion` 工具采访你。

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.

规格完成后，开启一个新会话来执行它。新会话拥有干净上下文，完全聚焦于实现，而且你有一份可引用的书面规格。

最有用的规格是自包含的：它们说明涉及的文件和接口，列出不在范围内的内容，并以一个端到端验证步骤收尾，证明功能可用。把规格写精确所花的时间，比盯着实现过程所花的时间回报更高。

管理你的会话

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

尽早且经常纠偏

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

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

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

如果你在同一个会话中针对同一个问题纠正 Claude 超过两次，上下文就已经混入了失败方法。运行 /clear，用更具体的提示词重新开始，并把你学到的内容纳入其中。带有更好提示词的干净会话，几乎总是胜过积累了多次纠正的长会话。

积极管理上下文

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

当你接近上下文限制时，Claude Code 会自动压缩对话历史，在释放空间的同时保留重要代码和决策。

在长会话中，Claude 的上下文窗口可能被无关对话、文件内容和命令填满。这会降低性能，有时还会分散 Claude 注意力。

  • 经常在任务之间使用 /clear，完全重置上下文窗口
  • 自动压缩触发时，Claude 会总结最重要的内容，包括代码模式、文件状态和关键决策
  • 如需更多控制，运行 /compact <instructions>，例如 /compact Focus on the API changes
  • 要只压缩对话的一部分，使用 Esc + Esc 或 /rewind，选择一个消息检查点，然后选择 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。答案会出现在可关闭的浮层中，不会进入对话历史，所以你可以查看细节而不增加上下文。

使用子智能体做调查

用 `"use subagents to investigate X"` 委派研究。它们会在单独上下文中探索，让你的主对话保持干净，专注于实现。

由于上下文是你的基本约束，子智能体是可用的最强大工具之一。当 Claude 研究代码库时，它会读取大量文件，这些都会消耗你的上下文。子智能体在单独的上下文窗口中运行，并汇报摘要：

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

子智能体会探索代码库、读取相关文件并汇报发现，整个过程不会弄乱你的主对话。

你也可以在 Claude 实现某些内容后，用子智能体进行验证：

use a subagent to review this code for edge cases

用检查点回退

你发送的每个提示词都会创建一个检查点。你可以将对话、代码或二者恢复到任意此前检查点。

Claude 会在每次修改前自动为文件做快照，因此检查点可以恢复它们。双击 Escape 或运行 /rewind 打开 rewind 菜单。你可以只恢复对话、只恢复代码、同时恢复二者，或从选定消息开始总结。详见 Checkpointing。

与其小心规划每一步，不如让 Claude 尝试一些有风险的做法。如果行不通，就回退并尝试另一种方法。检查点跨会话持久保存，所以你可以关闭终端，之后仍然回退。

检查点只跟踪 *Claude* 做出的更改，而不跟踪外部进程。这不能替代 git。

恢复对话

用 `/rename` 命名会话，并把它们像分支一样对待：每条工作流都有自己的持久上下文。

Claude Code 会在本地保存对话，所以当任务跨越多次坐下来处理时，你不必重新解释上下文。运行 claude --continue 接续最近的会话，或运行 claude --resume 从列表中选择。给会话取像 oauth-migration 这样的描述性名称，便于之后找到。关于恢复、分支和命名控制的完整集合，请参见 Manage sessions。

自动化与扩展

当你能有效使用一个 Claude 后，就可以用并行会话、非交互模式和 fan-out 模式放大产出。

前面所有内容都假设一个人、一个 Claude、一个对话。但 Claude Code 可以水平扩展。本节的技巧展示了如何完成更多工作。

运行非交互模式

在 CI、pre-commit hooks 或脚本中使用 `claude -p "prompt"`。添加 `--output-format stream-json --verbose` 以获得流式 JSON 输出。

使用 claude -p "your prompt"，你可以非交互式运行 Claude，而不创建会话。非交互模式是将 Claude 集成进 CI pipeline、pre-commit hooks 或任何自动化工作流的方式。输出格式让你能够以程序方式解析结果：纯文本、JSON 或流式 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 会话

并行运行多个 Claude 会话，以加快开发、运行隔离实验，或启动复杂工作流。

选择适合你自己想承担多少协调工作的并行方式：

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

除了并行化工作，多个会话也能支持注重质量的工作流。新鲜上下文可以改善代码审查，因为 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`） ```bash theme={null} 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 个文件出现的问题改进提示词，然后在完整集合上运行。`--allowedTools` 标志会限制 Claude 能做什么，这在无人值守运行时很重要。

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

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

开发调试时使用 --verbose，生产环境中关闭它。

使用 auto mode 自主运行

要实现带后台安全检查的不间断执行，使用 auto mode。分类器模型会在命令运行前审查它们，阻止范围升级、未知基础设施和由恶意内容驱动的操作，同时让常规工作无需提示即可继续。

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

对于带 -p 标志的非交互运行，如果分类器反复阻止动作，auto mode 会中止，因为没有用户可供回退。阈值见 when auto mode falls back。

添加对抗性审查步骤

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

Claude 无人值守工作的时间越长，在把工作算作完成前，独立检查就越重要。运行在新鲜 subagent 上下文中的审查者，只看到 diff 和你给它的标准，而不是产出改动的推理，因此会按结果本身进行评估。

对于正确性检查，运行内置 /code-review skill，它会在新鲜子智能体中审查当前 diff 是否有 bug，并把发现返回给会话。如果要按计划检查 diff，则自己编写审查提示词。说明要检查的工作、要对照的计划，以及什么算作发现：

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.

由于审查者作为子智能体运行，实现会话会直接收到缺口，然后可以修复并再次审查，而不需要你在窗口之间复制发现。对于更长的自主运行，agent team 可以在许多任务中持续这个循环，而你只需抽查记录下来的发现。

如果提示审查者寻找缺口，它通常会报告一些问题，即使工作本身没问题，因为这正是它被要求做的事。追逐每个发现会导致过度工程：额外抽象层、防御性代码，以及针对不可能发生情况的测试。告诉审查者只标记影响正确性或既定需求的缺口，其余内容视为可选。

避免常见失败模式

以下是一些常见错误。尽早识别它们可以节省时间：

  • **大杂烩式会话。**你从一个任务开始，然后问 Claude 一些无关内容，接着又回到第一个任务。上下文里充满无关信息。

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

  • **反复纠正。**Claude 做错了，你纠正它，它仍然错，你再次纠正。上下文被失败方法污染。

    修复：两次纠正失败后，使用 /clear，并把你学到的内容纳入一个更好的初始提示词。

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

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

  • **先信任后验证的缺口。**Claude 产出看起来合理的实现，但没有处理边界情况。

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

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

    修复：收窄调查范围，或使用子智能体，让探索不会消耗主上下文。

培养你的直觉

本指南中的模式并非一成不变。它们是通常有效的起点，但不一定适合每种情况。

有时候，你应该让上下文累积，因为你正深入处理一个复杂问题，历史记录很有价值。有时候，你应该跳过规划，让 Claude 自己摸索，因为任务本身是探索性的。有时候，一个模糊提示词恰好合适，因为你想先看看 Claude 如何理解问题，再去约束它。

关注什么有效。当 Claude 产出优秀结果时，注意你做了什么：提示词结构、你提供的上下文、所处模式。当 Claude 表现吃力时，问问原因。上下文是否太嘈杂？提示词是否太模糊？任务是否太大，不适合一次完成？

随着时间推移，你会形成任何指南都无法完全捕捉的直觉。你会知道什么时候该具体、什么时候该开放，什么时候该规划、什么时候该探索，什么时候该清空上下文、什么时候该让它累积。

相关资源