{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# Claude Code 最佳实践

> 充分利用 Claude Code 的技巧和模式，从配置环境到跨并行会话扩展。

Claude Code 是一个智能体编程环境。与回答问题并等待的聊天机器人不同，Claude Code 可以读取你的文件、运行命令、做出更改，并在你观看、重定向或完全离开时自主处理问题。

这改变了你的工作方式。你不再自己编写代码并让 Claude 审查，而是描述你想要的内容，Claude 会想出如何构建它。Claude 探索、规划并实施。

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

本指南涵盖了在 Anthropic 内部团队和使用 Claude Code 的各种代码库、语言和环境的工程师中被证明有效的模式。有关智能体循环如何在底层工作，请参见 [Claude Code 工作原理](/en/how-claude-code-works)。

***

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

Claude 的上下文窗口保存你的整个对话，包括每条消息、Claude 读取的每个文件和每个命令输出。然而，这会很快填满。单个调试会话或代码库探索可能生成和消耗数万个 token。

这很重要，因为 LLM 性能会随着上下文填满而下降。当上下文窗口快满时，Claude 可能会开始"忘记"早期指令或犯更多错误。上下文窗口是最重要的资源管理。要查看会话在实践中如何填满，[观看交互式演练](/en/context-window)了解启动时加载的内容和每次文件读取的成本。使用[自定义状态行](/en/statusline)持续跟踪上下文使用情况，并参见[减少 token 使用](/en/costs#reduce-token-usage)了解减少 token 使用的策略。

***

## 让 Claude 有办法验证其工作

<Tip>
  包含测试、截图或预期输出，以便 Claude 能自我检查。这是你能做的最高杠杆的事情。
</Tip>

当 Claude 能验证自己的工作时，表现会显著提升，如运行测试、比较截图和验证输出。

没有明确的成功标准，它可能会产生看起来正确但实际上不起作用的东西。你成为唯一的反馈循环，每个错误都需要你的注意。

| 策略 | 之前 | 之后 |
| --- | --- | --- |
| **提供验证标准** | *"implement a function that validates email addresses"* | *"write a validateEmail function. example test cases: [user@example.com](mailto:user@example.com) is true, invalid is false, [user@.com](mailto: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"* |

UI 更改可以使用 [Chrome 中的 Claude 扩展](/en/chrome)进行验证。它在你的浏览器中打开新标签页，测试 UI，并迭代直到代码正常工作。

你的验证也可以是测试套件、linter 或检查输出的 Bash 命令。投入精力使你的验证坚如磐石。

让 Claude 展示证据而不是断言成功：测试输出、它运行的命令及其返回结果，或结果的截图。审查证据比重运行验证更快，对你未关注的会话也有效。

***

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

<Tip>
  将研究和规划与实施分开，以避免解决错误的问题。
</Tip>

让 Claude 直接跳到编码可能会产生解决错误问题的代码。使用[计划模式](/en/permission-modes#analyze-before-you-edit-with-plan-mode)将探索与执行分开。

推荐的工作流有四个阶段：

<Steps>
  <Step title="探索">
    进入计划模式。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.
    ```
  </Step>

  <Step title="规划">
    要求 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.
    ```

    按 `Ctrl+G` 在文本编辑器中打开计划，在 Claude 继续之前直接编辑。
  </Step>

  <Step title="实施">
    切换出计划模式，让 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.
    ```
  </Step>

  <Step title="提交">
    要求 Claude 带描述性消息提交并创建 PR。

    ```txt claude (default mode) theme={null}
    commit with a descriptive message and open a PR
    ```
  </Step>
</Steps>

<Callout>
  计划模式很有用，但也会增加开销。

  对于范围明确且修复较小的任务（如修复拼写错误、添加日志行或重命名变量），直接让 Claude 做。

  当你对方法不确定、更改涉及多个文件或不熟悉被修改的代码时，规划最有用。如果你能用一句话描述差异，就跳过计划。
</Callout>

***

## 在提示中提供具体的上下文

<Tip>
  你的指令越精确，需要的纠正就越少。
</Tip>

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?"` 这样的提示可以发现你想不到要问的东西。

### 提供丰富内容

<Tip>
  使用 `@` 引用文件、粘贴截图/图片，或直接导入数据。
</Tip>

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

* **用 `@` 引用文件**，而不是描述代码在哪里。Claude 在回复前会读取文件。
* **直接粘贴图片**。复制/粘贴或拖放图片到提示中。
* **提供 URL** 用于文档和 API 参考。使用 `/permissions` 将常用域名加入白名单。
* **通过运行 `cat error.log | claude` 导入数据**，直接发送文件内容。
* **让 Claude 获取它需要的内容**。告诉 Claude 使用 Bash 命令、MCP 工具或读取文件自行拉取上下文。

***

## 配置你的环境

几个设置步骤可以使 Claude Code 在所有会话中显著更有效。有关扩展功能的完整概述以及何时使用每种功能，请参见[扩展 Claude Code](/en/features-overview)。

### 编写有效的 CLAUDE.md

<Tip>
  运行 `/init` 根据当前项目结构生成入门 CLAUDE.md 文件，然后随时间优化。
</Tip>

CLAUDE.md 是一个特殊文件，Claude 在每次对话开始时读取。包含 Bash 命令、代码风格和工作流规则。这为 Claude 提供了无法仅从代码推断的持久上下文。

`/init` 命令分析你的代码库以检测构建系统、测试框架和代码模式，为你提供一个良好的优化基础。

CLAUDE.md 文件没有必需的格式，但应保持简短且人类可读。例如：

```markdown CLAUDE.md theme={null}
# 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 每次会话都加载，所以只包含广泛适用的内容。对于仅有时相关的领域知识或工作流，改用[技能](/en/skills)。Claude 按需加载它们，不会使每次对话变得臃肿。

保持简洁。对于每一行，问：*"删除这个会导致 Claude 犯错吗？"* 如果不会，就删掉。臃肿的 CLAUDE.md 文件会导致 Claude 忽略你的实际指令！

| ✅ 包含 | ❌ 排除 |
| --- | --- |
| Claude 无法猜测的 Bash 命令 | Claude 通过阅读代码就能弄清楚的任何内容 |
| 与默认值不同的代码风格规则 | Claude 已经知道的标准语言约定 |
| 测试说明和首选测试运行器 | 详细的 API 文档（改为链接到文档） |
| 仓库礼仪（分支命名、PR 约定） | 频繁变化的信息 |
| 项目特定的架构决策 | 冗长的解释或教程 |
| 开发环境特殊性（必需的环境变量） | 代码库的逐文件描述 |
| 常见陷阱或非显而易见的行为 | 不言而喻的做法如"编写干净的代码" |

如果 Claude 持续做你不想要的事情，即使有规则禁止，文件可能太长，规则被忽略了。如果 Claude 问你 CLAUDE.md 中已回答的问题，措辞可能有歧义。将 CLAUDE.md 当作代码：出错时审查它，定期精简，并通过观察 Claude 的行为是否实际改变来测试更改。

你可以通过添加强调（如 "IMPORTANT" 或 "YOU MUST"）来调整指令以提高遵守度。将 CLAUDE.md 提交到 git，以便你的团队可以贡献。该文件的价值会随时间增长。

CLAUDE.md 文件可以使用 `@path/to/import` 语法导入其他文件：

```markdown CLAUDE.md theme={null}
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 文件

### 配置权限

<Tip>
  使用[自动模式](/en/permission-modes#eliminate-prompts-with-auto-mode)让分类器处理审批，使用 `/permissions` 将特定命令加入白名单，或使用 `/sandbox` 进行操作系统级隔离。每种方式都能减少中断，同时保持你的控制。
</Tip>

默认情况下，Claude Code 会请求可能修改你系统的操作的许可：文件写入、Bash 命令、MCP 工具等。这很安全但很繁琐。到第十次审批时你已经不再真正审查了，只是在点击通过。有三种方法可以减少这些中断：

* **自动模式**：一个单独的分类器模型审查命令，只阻止看起来有风险的操作：范围升级、未知基础设施或敌对内容驱动的操作。当你信任任务的大方向但不想逐步点击时最适合
* **权限白名单**：允许你已知安全的特定工具，如 `npm run lint` 或 `git commit`
* **沙箱**：启用操作系统级隔离，限制文件系统和网络访问，允许 Claude 在定义的边界内更自由地工作

阅读更多关于[权限模式](/en/permission-modes)、[权限规则](/en/permissions)和[沙箱](/en/sandboxing)。

### 使用 CLI 工具

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

CLI 工具是与外部服务交互的最具上下文效率的方式。如果你使用 GitHub，请安装 `gh` CLI。Claude 知道如何使用它来创建问题、打开拉取请求和读取评论。没有 `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 服务器

<Tip>
  运行 `claude mcp add` 连接 Notion、Figma 或数据库等外部工具。
</Tip>

通过 [MCP 服务器](/en/mcp)，你可以让 Claude 从问题跟踪器实施功能、查询数据库、分析监控数据、集成 Figma 的设计以及自动化工作流。

### 设置钩子

<Tip>
  使用钩子处理必须每次都发生且无例外的操作。
</Tip>

[钩子](/en/hooks-guide)在 Claude 工作流的特定点自动运行脚本。与作为建议的 CLAUDE.md 指令不同，钩子是确定性的，保证操作会发生。

Claude 可以为你编写钩子。尝试这样的提示：*"Write a hook that runs eslint after every file edit"* 或 *"Write a hook that blocks writes to the migrations folder."* 直接编辑 `.claude/settings.json` 手动配置钩子，运行 `/hooks` 浏览已配置的钩子。

### 创建技能

<Tip>
  在 `.claude/skills/` 中创建 `SKILL.md` 文件，为 Claude 提供领域知识和可重用的工作流。
</Tip>

[技能](/en/skills)通过项目、团队或领域特定的信息扩展 Claude 的知识。Claude 在相关时自动应用它们，或者你可以用 `/skill-name` 直接调用。

通过在 `.claude/skills/` 中添加包含 `SKILL.md` 的目录来创建技能：

```markdown .claude/skills/api-conventions/SKILL.md theme={null}
---
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/)
```

技能也可以定义你直接调用的可重复工作流：

```markdown .claude/skills/fix-issue/SKILL.md theme={null}
---
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`，这样你想要手动触发。

### 创建自定义子智能体

<Tip>
  在 `.claude/agents/` 中定义专门的助手，Claude 可以委派给它们进行隔离任务。
</Tip>

[子智能体](/en/sub-agents)在自己的上下文中运行，拥有自己的一组允许工具。它们对于读取许多文件或需要专门关注而不使主对话混乱的任务很有用。

```markdown .claude/agents/security-reviewer.md theme={null}
---
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."*

### 安装插件

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

[插件](/en/plugins)将技能、钩子、子智能体和 MCP 服务器捆绑为一个可安装单元，来自社区和 Anthropic。如果你使用类型化语言，安装[代码智能插件](/en/discover-plugins#code-intelligence)为 Claude 提供精确的符号导航和编辑后的自动错误检测。

有关在技能、子智能体、钩子和 MCP 之间选择的指南，请参见[扩展 Claude Code](/en/features-overview#match-features-to-your-goal)。

***

## 有效沟通

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

### 提出代码库问题

<Tip>
  向 Claude 提出你会问高级工程师的问题。
</Tip>

在加入新代码库时，使用 Claude Code 进行学习和探索。你可以向 Claude 提出你会问另一个工程师的同类问题：

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

这样使用 Claude Code 是一种有效的入职工作流，可以加快上手速度并减少其他工程师的负担。不需要特殊提示：直接提问。

### 让 Claude 面试你

<Tip>
  对于较大的功能，先让 Claude 面试你。从最小的提示开始，要求 Claude 使用 `AskUserQuestion` 工具面试你。
</Tip>

Claude 会问你可能还没有考虑过的事情，包括技术实现、UI/UX、边界情况和权衡。

```text theme={null}
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.
```

规范完成后，启动一个新会话来执行它。新会话有干净的上下文，完全专注于实施，你有书面规范可参考。

最有用的规范是自包含的：它们命名涉及的文件和接口，说明不在范围内的内容，并以端到端验证步骤结束，证明功能有效。花时间使规范精确比花时间观看实施更有价值。

***

## 管理你的会话

对话是持久的和可逆的。利用这一点！

### 及早且频繁地纠正方向

<Tip>
  一旦发现 Claude 偏离方向就立即纠正。
</Tip>

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

* **`Esc`**：按 `Esc` 键在 Claude 操作中途停止。上下文已保留，你可以重定向。
* **`Esc + Esc` 或 `/rewind`**：按两次 `Esc` 或运行 `/rewind` 打开回退菜单，恢复之前的对话和代码状态，或从选定消息开始总结。
* **`"Undo that"`**：让 Claude 撤销其更改。
* **`/clear`**：在不相关的任务之间重置上下文。包含不相关上下文的长会话可能降低性能。

如果你在一次会话中对同一问题纠正 Claude 超过两次，上下文中充满了失败的方法。运行 `/clear` 并用结合了你所学的更具体的提示重新开始。干净的会话加上更好的提示几乎总是优于积累了纠正的长会话。

### 积极管理上下文

<Tip>
  在不相关的任务之间运行 `/clear` 以重置上下文。
</Tip>

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

在长会话期间，Claude 的上下文窗口可能充满不相关的对话、文件内容和命令。这可能降低性能，有时会分散 Claude 的注意力。

* 在任务之间频繁使用 `/clear` 完全重置上下文窗口
* 当自动压缩触发时，Claude 总结最重要的内容，包括代码模式、文件状态和关键决策
* 要获得更多控制，运行 `/compact <instructions>`，如 `/compact Focus on the API changes`
* 要仅压缩对话的一部分，使用 `Esc + Esc` 或 `/rewind`，选择一个消息检查点，然后选择**从此处总结**或**总结到此处**。前者从该点向前压缩消息，同时保持早期上下文完整；后者压缩早期消息，同时完整保留最近的消息。参见[恢复与总结](/en/checkpointing#restore-vs-summarize)。
* 在 CLAUDE.md 中自定义压缩行为，使用如 `"When compacting, always preserve the full list of modified files and any test commands"` 的指令，确保关键上下文在总结中存活
* 对于不需要留在上下文中的快速问题，使用 [`/btw`](/en/interactive-mode#side-questions-with-%2Fbtw)。答案出现在可关闭的覆盖层中，永远不会进入对话历史，因此你可以在不增长上下文的情况下查看细节。

### 使用子智能体进行调查

<Tip>
  通过 `"use subagents to investigate X"` 委托研究。它们在单独的上下文中探索，保持主对话干净以进行实施。
</Tip>

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

```text theme={null}
Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.
```

子智能体探索代码库，读取相关文件，并报告发现，所有这些都不会使你的主对话混乱。

你也可以在 Claude 实施后使用子智能体进行验证：

```text theme={null}
use a subagent to review this code for edge cases
```

### 使用检查点回退

<Tip>
  你发送的每个提示都会创建一个检查点。你可以将对话、代码或两者恢复到任何之前的检查点。
</Tip>

Claude 在每次更改前自动快照文件，以便检查点可以恢复它们。双击 `Escape` 或运行 `/rewind` 打开回退菜单。你可以仅恢复对话、仅恢复代码、同时恢复两者，或从选定消息开始总结。参见[检查点](/en/checkpointing)了解详情。

你可以告诉 Claude 尝试有风险的事情，而不是仔细规划每一步。如果不起作用，回退并尝试不同的方法。检查点跨会话持久化，因此你可以关闭终端，稍后仍然可以回退。

<Warning>
  检查点只跟踪 *Claude* 做出的更改，不包括外部进程。这不是 git 的替代品。
</Warning>

### 恢复对话

<Tip>
  用 `/rename` 命名会话，将它们当作分支：每个工作流都有自己的持久上下文。
</Tip>

Claude Code 在本地保存对话，因此当任务跨越多个时间段时，你不必重新解释上下文。运行 `claude --continue` 恢复最近的会话，或运行 `claude --resume` 从列表中选择。给会话起描述性的名称如 `oauth-migration`，以便稍后找到它们。参见[管理会话](/en/sessions)了解完整的恢复、分支和命名控制集。

***

## 自动化和扩展

一旦你与一个 Claude 配合有效，就可以通过并行会话、非交互模式和扇出模式来倍增你的输出。

到目前为止的一切都假设一个人、一个 Claude 和一个对话。但 Claude Code 可以水平扩展。本节中的技术展示了如何完成更多工作。

### 运行非交互模式

<Tip>
  在 CI、pre-commit 钩子或脚本中使用 `claude -p "prompt"`。添加 `--output-format stream-json --verbose` 以获取流式 JSON 输出。
</Tip>

通过 `claude -p "your prompt"`，你可以非交互式地运行 Claude，无需会话。[非交互模式](/en/headless)是你将 Claude 集成到 CI 管道、pre-commit 钩子或任何自动化工作流的方式。输出格式允许你以编程方式解析结果：纯文本、JSON 或流式 JSON。

```bash theme={null}
# 一次性查询
claude -p "Explain what this project does"

# 脚本的结构化输出
claude -p "List all API endpoints" --output-format json

# 实时处理的流式输出
claude -p "Analyze this log file" --output-format stream-json --verbose
```

### 运行多个 Claude 会话

<Tip>
  并行运行多个 Claude 会话以加速开发、运行隔离实验或启动复杂工作流。
</Tip>

选择适合你想要自己协调程度的并行方法：

* [工作树](/en/worktrees)：在隔离的 git 检出中运行单独的 CLI 会话，使编辑不会冲突
* [桌面应用](/en/desktop#work-in-parallel-with-sessions)：可视化管理多个本地会话，每个在自己的工作树中
* [网页版 Claude Code](/en/claude-code-on-the-web)：在 Anthropic 管理的云基础设施上的隔离 VM 中运行会话
* [智能体团队](/en/agent-teams)：自动协调多个会话，共享任务、消息传递和团队领导

除了并行化工作之外，多个会话还支持以质量为中心的工作流。干净的上下文可以改善代码审查，因为 Claude 不会偏向于它刚编写的代码。

例如，使用编写者/审查者模式：

| 会话 A（编写者） | 会话 B（审查者） |
| --- | --- |
| `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 编写测试，然后另一个编写代码来通过它们。

### 跨文件扇出

<Tip>
  循环遍历任务，为每个任务调用 `claude -p`。使用 `--allowedTools` 限定批量操作的权限。
</Tip>

对于大型迁移或分析，你可以将工作分布在许多并行的 Claude 调用中：

<Steps>
  <Step title="生成任务列表">
    让 Claude 列出所有需要迁移的文件（例如 `list all 2,000 Python files that need migrating`）
  </Step>

  <Step title="编写循环遍历列表的脚本">
    ```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
    ```
  </Step>

  <Step title="在几个文件上测试，然后大规模运行">
    根据前 2-3 个文件出错的情况优化你的提示，然后在完整集合上运行。`--allowedTools` 标志限制 Claude 可以做什么，这在无人值守运行时很重要。
  </Step>
</Steps>

你也可以将 Claude 集成到现有的数据/处理管道中：

```bash theme={null}
claude -p "<your prompt>" --output-format json | your_command
```

在开发期间使用 `--verbose` 进行调试，在生产环境中关闭它。

### 使用自动模式自主运行

要在不中断的情况下执行并带有后台安全检查，请使用[自动模式](/en/permission-modes#eliminate-prompts-with-auto-mode)。分类器模型在命令运行前审查它们，阻止范围升级、未知基础设施和敌对内容驱动的操作，同时让常规工作无需提示即可进行。

```bash theme={null}
claude --permission-mode auto -p "fix all lint errors"
```

对于使用 `-p` 标志的非交互运行，如果分类器反复阻止操作，自动模式会中止，因为没有用户可以回退。参见[自动模式何时回退](/en/permission-modes#when-auto-mode-falls-back)了解阈值。

### 添加对抗性审查步骤

<Tip>
  在将任务视为完成之前，让子智能体在干净的上下文中审查差异并报告不足之处。
</Tip>

Claude 无人值守工作的时间越长，在你将工作算作完成之前进行独立检查就越重要。在干净的[子智能体](/en/sub-agents)上下文中运行的审查者只看到差异和你给它的标准，而不是产生更改的推理过程，因此它根据自己的条件评估结果。

对于正确性检查，运行内置的 [`/code-review` 技能](/en/commands)，它在干净的子智能体中审查当前差异的缺陷，并将发现返回到会话。要改为根据你的计划检查差异，请自己编写审查提示。命名要检查的工作、要检查的计划以及什么算作发现：

```text theme={null}
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.
```

由于审查者作为子智能体运行，实施会话直接接收不足之处，可以修复它们并重新审查，无需你在窗口之间复制发现。对于较长时间的自主运行，[智能体团队](/en/agent-teams)可以跨多个任务保持这个循环运行，同时你抽查记录的发现。

<Callout>
  被提示寻找不足的审查者通常会报告一些，即使工作是合理的，因为这就是它被要求做的。追逐每个发现会导致过度工程化：额外的抽象层、防御性代码和对不可能发生的情况的测试。告诉审查者只标记影响正确性或既定要求的不足，其余的视为可选。
</Callout>

***

## 避免常见的失败模式

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

* **大杂烩会话。** 你从一个任务开始，然后问 Claude 不相关的事情，然后又回到第一个任务。上下文充满了不相关的信息。
  > **修复**：在不相关的任务之间 `/clear`。
* **反复纠正。** Claude 做错了什么，你纠正它，它还是错的，你再纠正。上下文被失败的方法污染。
  > **修复**：两次失败的纠正后，`/clear` 并编写更好的初始提示，融入你学到的内容。
* **过度指定的 CLAUDE.md。** 如果你的 CLAUDE.md 太长，Claude 会忽略一半，因为重要的规则在噪音中丢失。
  > **修复**：无情地精简。如果 Claude 在没有指令的情况下已经正确做了某事，删除它或将其转换为钩子。
* **信任后验证差距。** Claude 产生了看起来合理但不处理边界情况的实现。
  > **修复**：始终提供验证（测试、脚本、截图）。如果你无法验证，就不要发布。
* **无限探索。** 你让 Claude "调查"某事而没有限定范围。Claude 读取数百个文件，填满上下文。
  > **修复**：狭义地限定调查范围或使用子智能体，使探索不会消耗你的主上下文。

***

## 培养你的直觉

本指南中的模式不是一成不变。它们是普遍有效的起点，但可能不是每种情况的最优解。

有时你*应该*让上下文积累，因为你深入一个复杂问题，历史很有价值。有时你应该跳过规划，让 Claude 自己弄清楚，因为任务是探索性的。有时模糊的提示恰好正确，因为你想在约束之前看 Claude 如何解释问题。

注意什么有效。当 Claude 产生出色的输出时，注意你做了什么：提示结构、你提供的上下文、你使用的模式。当 Claude 遇到困难时，问为什么。是上下文太嘈杂？提示太模糊？任务太大一次无法完成？

随着时间的推移，你会培养出任何指南都无法捕捉的直觉。你会知道何时具体、何时开放，何时规划、何时探索，何时清除上下文、何时让其积累。

## 相关资源

* [Claude Code 工作原理](/en/how-claude-code-works)：智能体循环、工具和上下文管理
* [扩展 Claude Code](/en/features-overview)：技能、钩子、MCP、子智能体和插件
* [常见工作流](/en/common-workflows)：调试、测试、PR 等的分步指南
* [CLAUDE.md](/en/memory)：存储项目约定和持久上下文