4 4
5# Claude Code 最佳实践5# Claude Code 最佳实践
6 6
7> 从配置环境到跨并行会话扩展，充分利用 Claude Code 的提示和模式。7> 充分发挥 Claude Code 的作用：告诉 Claude 它看不到的信息，给它一个可以运行的检查，并强制执行不允许例外的规则。
8 8
9Claude Code 是一个代理式编码环境。与等待回答问题的聊天机器人不同，Claude Code 可以读取你的文件、运行命令、进行更改，并在你观看、重定向或完全离开的情况下自主解决问题。9Claude Code 的设计使得在大多数情况下，您在新会话中的第一个普通提示词就已经能做对事情，无需您进行任何设置。
10 10
11这改变了你的工作方式。与其自己编写代码并要求 Claude 审查，不如描述你想要什么，让 Claude 弄清楚如何构建它。Claude 会探索、规划和实现。11例如：
12 12
13但这种自主性仍然伴随着学习曲线。Claude 在某些约束条件下工作，你需要理解这些约束。13* 为了让命令安全运行而无需您逐一批准，新的终端和 VS Code 会话以[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)启动，由分类器在任何有风险的操作运行之前进行审查。
14* 为了在独立工作并行进行时保持主对话的专注，Claude 会将工作委派给子代理，并且只在必要时与您确认。
15* 为了让长会话持续进行而无需您管理，对话会在上下文窗口填满之前自动压缩。
14 16
15本指南涵盖了在 Anthropic 内部团队和在各种代码库、语言和环境中使用 Claude Code 的工程师中已被证明有效的模式。有关代理循环如何在幕后工作的信息，请参阅 [Claude Code 如何工作](https://code.claude.com/docs/zh-CN/how-claude-code-works.md)。17本页介绍默认设置不够用时该怎么做。这种情况通常发生在您的项目拥有 Claude 无法仅从代码中看到的知识、规则或约束时：
16 18
17***19* 只存在于某个人脑子里的部署流程
20* 绝不能被读取的文件
21* 必须通过才算完成的检查
22* 您需要控制在其内的预算
18 23
19大多数最佳实践都基于一个约束：Claude 的 context window 填充速度很快，随着填充，性能会下降。24没有任何默认设置能知道您项目的这些情况，所以在这里您做一点设置就能获得回报。
20 25
21Claude 的 context window 保存你的整个对话，包括每条消息、Claude 读取的每个文件和每个命令输出。但这可能会很快填满。单个调试会话或代码库探索可能会生成并消耗数万个 token。26当会话没有按您的预期进行时，几乎总是以下情况之一：
22 27
23这很重要，因为当 context 填充时，LLM 性能会下降。当 context window 即将满时，Claude 可能会开始"遗忘"早期的指令或犯更多错误。context window 是最重要的资源。要查看会话在实践中如何填充，请 [观看交互式演练](https://code.claude.com/docs/zh-CN/context-window.md)，了解启动时加载的内容以及每个文件读取的成本。使用 [自定义状态行](https://code.claude.com/docs/zh-CN/statusline.md) 持续跟踪 context 使用情况，并查看 [减少 token 使用](https://code.claude.com/docs/zh-CN/costs.md#reduce-token-usage) 了解减少 token 使用的策略。28* Claude 构建的东西与您设想的不同，或者它每次会话开始时都要重新发现同一个事实。它缺少无法通过阅读仓库获得的信息。请参阅[告诉 Claude 它看不到的信息](#tell-claude-what-it-cant-see)。
29* Claude 说已经完成了，但其实还差一点，这通常是因为它没有办法检查自己的工作。请参阅[给 Claude 一个可以运行的检查](#give-claude-a-check-to-run)。
30* Claude 做了在这个仓库中绝不应该发生的事，或者跳过了必须始终执行的步骤。仅靠提示词无法保证这两者。请参阅[强制执行不允许例外的规则](#enforce-the-rules-that-cant-have-exceptions)。
31* Claude 做对了，但花费的时间、token 或权限提示超出了任务本身的价值。请参阅[更改默认设置](#change-a-default)。
24 32
25***33[让 Claude 在无人值守时运行](#let-claude-run-without-you)将这四点应用于无人值守的运行，而[您可以不再做的事](#what-you-can-stop-doing)列出了当前模型已使其变得不再必要的建议。
26 34
27## 给 Claude 一种验证其工作的方式35> [!NOTE]
28
29> [!TIP]
30>36>
31> 给 Claude 一个它可以运行的检查：测试、构建、屏幕截图进行比较。这是你观看的会话和你可以离开的会话之间的区别。37> 面向整个团队的设置在单独的页面上：[为您的组织设置 Claude Code](https://code.claude.com/docs/zh-CN/admin-setup.md)。
32 38
33当工作看起来完成时，Claude 会停止。没有它可以运行的检查，"看起来完成"是唯一可用的信号，你成为验证循环：每个错误都在等待你注意到它。给 Claude 一些能产生通过或失败的东西，循环就会自动关闭。Claude 完成工作，运行检查，读取结果，并迭代直到检查通过。39## 确定性指令与非确定性指令
34 40
35检查是任何返回 Claude 可以在对话中读取的信号的东西：测试套件、构建退出代码、linter、针对固定装置比较输出的脚本，或与设计进行比较的[浏览器屏幕截图](https://code.claude.com/docs/zh-CN/chrome.md)。运行 [`/verify`](https://code.claude.com/docs/zh-CN/skills#run-and-verify-your-app) 在 Claude 的检查通过后自己确认针对运行中的应用的更改。41您给 Claude Code 的每一条指令都属于以下之一：
36 42
37| 策略 | 之前 | 之后 |431. 非确定性：您编写指令，由 Claude（模型）读取。这可以是您的提示词、`CLAUDE.md` 或 skill。然后由模型决定如何处理这些信息。它通常会遵循您的命令，当前模型也很擅长在没有太多上下文的情况下理解您的意图，但并不*保证*它会遵循您的指令。它仍然可能决定不做某些事，或者做其他事。
38| - | - | - |442. 确定性：您配置指令，由 Claude Code（harness）*必须*执行。这可以是 hook、拒绝规则或托管设置。无论模型决定做什么，Claude Code 每次都会应用它。
39| **提供验证标准** | *"实现一个验证电子邮件地址的函数"* | *"编写一个 validateEmail 函数。示例测试用例：[user@example.com](mailto:user@example.com) 为真，invalid 为假，[user@.com](mailto:user@.com) 为假。实现后运行测试"* |
40| **以视觉方式验证 UI 更改** | *"让仪表板看起来更好"* | *"\[粘贴屏幕截图] 实现此设计。对结果进行屏幕截图并与原始设计进行比较。列出差异并修复它们"* |
41| **解决根本原因，而不是症状** | *"构建失败"* | *"构建失败，出现此错误：\[粘贴错误]。修复它并验证构建成功。解决根本原因，不要抑制错误"* |
42 45
43一旦检查存在，决定它对停止的限制有多严格：46Claude Code 中的大多数东西都有这两种形式：
44 47
45* **在一个提示中**：要求 Claude 运行检查并在同一消息中迭代，如上表所示。48| | 非确定性（由 Claude 决定） | 确定性（由 Claude Code 强制执行） |
46* **在整个会话中**：将检查设置为 [`/goal` 条件](https://code.claude.com/docs/zh-CN/goal)。单独的评估器在每次转换后重新检查它，Claude 继续工作直到目标解决。如果 Claude 停滞，Claude Code 最终会在目标仍然设置的情况下停止运行 — 请参阅 [/goal 评估如何工作](https://code.claude.com/docs/zh-CN/goal.md#how-evaluation-works)。49| :- | :- | :- |
47* **作为确定性门**：[Stop hook](https://code.claude.com/docs/zh-CN/hooks.md#stop) 作为脚本运行你的检查，并阻止转换结束直到它通过。[Stop input](https://code.claude.com/docs/zh-CN/hooks.md#stop-input) 涵盖连续阻止的上限。50| 做什么 | 您的提示词、`CLAUDE.md`、Claude 自行选用的 skill | hook，以及只有您才能启动的 skill |
48* **通过第二意见**：[验证子代理](https://code.claude.com/docs/zh-CN/sub-agents.md)或[动态工作流](https://code.claude.com/docs/zh-CN/workflows.md)检查自己的发现，有一个新鲜的模型尝试反驳结果，所以做工作的代理不是给它评分的。51| 能触及什么 | 自动模式的分类器 | 拒绝规则、[严格模式](https://code.claude.com/docs/zh-CN/sandboxing.md#turn-off-the-retry-with-strict-sandbox-mode)下的沙箱、托管设置 |
52| 何时算完成 | 要求提供证据、`/goal`、`/code-review` | 测试、类型检查、`Stop` hook、CI |
53| 花费多少 | effort 级别、Claude 自己的节奏 | 配合 `-p` 使用的 `--max-turns` 或 [`--max-budget-usd`](https://code.claude.com/docs/zh-CN/cli-reference)、您设置的[支出限额](https://code.claude.com/docs/zh-CN/costs.md) |
54| 谁拥有最终决定权 | Claude 对其所做工作的总结 | 分支保护、批准合并的人 |
49 55
50每一步都用设置换取关注。提示版本适用于今天的任何任务。`/goal` 和 Stop hook 版本是让无人值守运行正确完成而无需你的东西。56大多数时候，您希望由 Claude 来决定。几乎每条准则都有例外，而当前模型很擅长阅读眼前的代码并判断某条准则是否适合当前情况。有了实际代码在眼前，Claude 通常比您事先写好的规则更适合做出这个判断。
51 57
52让 Claude 显示证据而不是声称成功：测试输出、它运行的命令及其返回的内容，或结果的屏幕截图。审查证据比自己重新运行验证要快，并且它适用于你没有观看的会话。58确定性的那一类适用于您想确保某些事*始终*发生（或永不发生）的情况，无论模型作何决定。这不一定是什么重大的事。自动模式已经[阻止了那些重大的事](https://code.claude.com/docs/zh-CN/permission-modes.md#what-the-classifier-blocks-by-default)，比如生产部署或强制推送覆盖他人的工作。它通常是*您的*项目特有的东西，可以要多小众就多小众：
53 59
54***60* 永远不要编辑 `src/gen/` 中生成的客户端
61* 创建文件后始终运行 license-header 脚本
55 62
56## 先探索，再规划，最后编码63您本可以把这两条写成 `CLAUDE.md` 中的一行或写在提示词里，Claude 几乎每次都会遵循。但无论您的措辞多么强烈，Claude 在某一轮次中是否遵循那一行，仍然由 Claude 决定。
57 64
58> [!TIP]65> [!TIP]
59>66>
60> 将研究和规划与实现分开，以避免解决错误的问题。67> 如果您不断给 `CLAUDE.md` 中的某一行加强调，而 Claude 仍然遗漏它，这说明这一行应该放进 hook。反过来也成立：如果您为一些只是偏好的事情设置了 hook，请删除它们，让 Claude 来决定。
61 68
62让 Claude 直接跳到编码可能会产生解决错误问题的代码。使用 [Plan Mode](https://code.claude.com/docs/zh-CN/permission-modes.md#analyze-before-you-edit-with-plan-mode) 将探索与执行分开。69## 告诉 Claude 它看不到的信息
63 70
64推荐的工作流有四个阶段：71> [!TIP]
72>
73> 只写下 Claude 通过阅读仓库找不到的内容，或者它原本每次会话都要花时间重新发现的内容。
65 74
66**1. 探索**75Claude 在开始每个任务时都会阅读您的代码，而当前模型在这方面*非常*擅长。它们会找到您的文件布局、约定、测试框架以及现有组件的构建方式，通常比您解释得还快。这意味着 Claude 已经知道您可能想为它写下的大部分内容。
67 76
68进入 Plan Mode，按 `Shift+Tab` 直到状态栏显示 `⏸ plan mode on`，或使用 `claude --permission-mode plan` 启动会话。Claude 读取文件并回答问题，不进行任何更改。77它找不到的，是从未存在于仓库中的信息：
69 78
70```txt title="claude (plan mode)" wrap theme={null}79* 您的团队在会议上做出的决定
71read /src/auth and understand how we handle sessions and login.80* 只存在于某一个人脑子里的部署流程
72also look at how we manage environment variables for secrets.81* 集成测试所需的环境变量
73```
74 82
75**2. 规划**83还有一些信息*确实*在仓库里，但需要花几分钟挖掘才能找到，而 Claude 每次会话开始时都必须重新挖掘一遍。
76 84
77要求 Claude 创建详细的实现计划。85在为 Claude 写下任何东西之前，一个好的检验方法：
78 86
79```txt title="claude (plan mode)" wrap theme={null}871. 它能通过阅读代码找到这个吗？
80I want to add Google OAuth. What files need to change?882. 它真的会去查找吗？
81What's the session flow? Create a plan.
82```
83 89
84按 `Ctrl+G` 在文本编辑器中打开计划进行直接编辑，然后 Claude 继续。90如果两个答案都是肯定的，就不用写。
85 91
86**3. 实现**92### 编写具体的提示词
87 93
88切换出 Plan Mode，通过批准计划或按 `Shift+Tab`，然后让 Claude 编码，根据其计划进行验证。94具体的提示词之所以有帮助，原因相同：它给了 Claude 原本没有的信息。如果您一开始就指明文件、描述症状并说明"修复"是什么样子，通常可以省去之后的一轮更正。
89 95
90```txt title="claude" wrap theme={null}96对于两种合理方法之间的偏好也是如此：Claude 无法从代码中读出这一点，所以如果您在意它选择哪种，请一开始就说明。
91implement the OAuth flow from your plan. write tests for the
92callback handler, run the test suite and fix any failures.
93```
94 97
95**4. 提交**98| 不要这样 | 试试这样 |
99| :- | :- |
100| *"修复登录错误"* | *"用户报告会话超时后登录失败。查看 src/auth/ 中的 token 刷新，编写一个能重现问题的失败测试，然后修复它"* |
101| *"添加一个日历小部件"* | *"按照 HotDogWidget.php 中的模式，构建一个日历小部件，让用户可以选择月份并在年份之间翻页。不要引入新库"* |
96 102
97要求 Claude 使用描述性消息进行提交并创建 PR。103如果您已经有 Claude 需要的东西，直接交给它，而不是去描述它：
98 104
99```txt title="claude" wrap theme={null}105* 文件：输入 `@` 和路径，即可在消息中[包含文件内容](https://code.claude.com/docs/zh-CN/common-workflows.md#reference-files-and-directories)。
100commit with a descriptive message and open a PR106* 图像：将设计或错误的屏幕截图粘贴到提示词中。
101```107* 命令输出：从 shell 中通过管道传入，例如 `cat error.log | claude -p "what's going on here"`。
102 108
103Plan Mode 很有用，但也增加了开销。109像 `think step by step` 或 `be thorough` 这样的短语只是普通的提示词文本，而不是关键词。控制 Claude 思考深度的主要手段是 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)，[更改模型和 effort](#change-the-model-and-effort) 中有相关介绍。这类措辞仍然可以在 effort 设置范围内轻微推动 Claude，但不会让它超出该设置。
104 110
105对于范围明确且修复很小的任务（如修复拼写错误、添加日志行或重命名变量），要求 Claude 直接执行。111有一个短语仍然有帮助，那就是 `be ambitious`。Claude 往往会保守地理解请求，构建能满足它的最小实现，因为它看不到您期望的程度。当您想要更完整的版本，处理好边界情况并包含自然的后续工作时，请明确说出来：
106 112
107当你对方法不确定、更改修改多个文件或你不熟悉被修改的代码时，规划最有用。如果你能用一句话描述 diff，跳过计划。113```text theme={null}
114build the settings page from the mockup. be ambitious: empty and error states, the save flow wired up, keyboard navigation, not just the layout
115```
108 116
109***117这是在告诉 Claude 范围，而范围只有您知道，而不是告诉它要思考多深。
110 118
111## 在提示中提供具体的上下文119当您在探索而不是修复某个具体问题时，像 `what would you improve in this file?` 这样模糊的提示词完全没问题。您会在过程中多做一些更正，这就是其中的取舍。
112 120
113> [!TIP]121### 先与 Claude 进行头脑风暴
114>
115> 你的指令越精确，你需要的更正就越少。
116 122
117Claude 可以推断意图，但它不能读心术。引用特定文件、提及约束，并指出示例模式。123当您还不确定自己想要什么时，不必在提示之前就把一切想清楚。可以让 Claude 来采访您：
118 124
119| 策略 | 之前 | 之后 |125```text theme={null}
120| - | - | - |126I want to add rate limiting to the public API but haven't thought it through yet. Interview me until you could write the spec, then write it to SPEC.md.
121| **限定任务范围。** 指定哪个文件、什么场景和测试偏好。 | *"为 foo.py 添加测试"* | *"为 foo.py 编写测试，涵盖用户已注销的边界情况。避免 mock。"* |127```
122| **指向来源。** 指导 Claude 到可以回答问题的来源。 | *"为什么 ExecutionFactory 有这样奇怪的 api？"* | *"查看 ExecutionFactory 的 git 历史并总结其 api 是如何形成的"* |
123| **参考现有模式。** 指向代码库中的模式。 | *"添加日历小部件"* | *"查看主页上现有小部件的实现方式以了解模式。HotDogWidget.php 是一个很好的例子。按照模式实现一个新的日历小部件，让用户选择月份并向前/向后分页以选择年份。从头开始构建，除了代码库中已使用的库外，不使用其他库。"* |
124| **描述症状。** 提供症状、可能的位置以及"修复"的样子。 | *"修复登录错误"* | *"用户报告会话超时后登录失败。检查 src/auth/ 中的身份验证流程，特别是 token 刷新。编写一个失败的测试来重现问题，然后修复它"* |
125 128
126当你在探索并能够改正方向时，模糊的提示可能很有用。像 `"你会改进这个文件的什么？"` 这样的提示可以表面你不会想到要问的东西。129Claude 会就您尚未确定的部分提出多项选择题：按用户还是按密钥限流、超出限制的请求如何处理、哪些不在范围内。它会一直提问，直到答案足以构成一份规范。
127 130
128### 提供丰富的内容131`SPEC.md` 生成之后，开启一个新会话并基于它进行构建，这样构建就从干净的上下文和一份书面的完成定义开始。之后在[给 Claude 一个可以运行的检查](#give-claude-a-check-to-run)中，您也会让审查者参照这个文件。
129 132
130> [!TIP]133### 保持 CLAUDE.md 简短
131>
132> 使用 `@` 引用文件、粘贴屏幕截图/图像或直接管道数据。
133 134
134你可以通过多种方式向 Claude 提供丰富的数据：135Claude Code 会将 [`CLAUDE.md`](https://code.claude.com/docs/zh-CN/memory) 加载到每个会话中，这意味着其中每一行在*每个*任务上都会占用 Claude 的一点注意力，无论是否相关。这就是为什么这个文件只包含 Claude 无法从代码本身推断出的内容时效果最好：
135 136
136* **使用 `@` 引用文件**，而不是描述代码的位置。Claude 在响应前读取文件。137* 如何在这个仓库中确认工作：确切的测试、类型检查和 lint 命令，以及如何运行单个测试文件
137* **直接粘贴图像**。复制/粘贴或拖放图像到提示中。138* 代码具有误导性的地方：随处可见但新代码不得照搬的旧模式，或者看起来没有被使用但实际在用的目录
138* **提供 URL** 用于文档和 API 参考。使用 `/permissions` 将经常使用的域添加到允许列表。139* 不在仓库中的决定：团队选定了哪个错误辅助函数、部署如何进行、什么需要迁移审查
139* **通过管道传入数据**，运行 `cat error.log | claude -p "explain this error"` 直接发送文件内容。140* 任何您已经更正过两次的事情
140* **让 Claude 获取它需要的东西**。告诉 Claude 使用 Bash 命令、MCP 工具或通过读取文件来自己拉取上下文。
141 141
142***142通过这一检验的 `CLAUDE.md` 会保持简短：
143 143
144## 配置你的环境144```markdown CLAUDE.md theme={null}
145# Commands
146- Install: pnpm install
147- Run one test file: pnpm vitest run path/to/file.test.ts
148- Typecheck: pnpm tsc --noEmit
145 149
146一些设置步骤使 Claude Code 在所有会话中显著更有效。有关扩展功能的完整概述和何时使用每个功能，请参阅 [扩展 Claude Code](https://code.claude.com/docs/zh-CN/features-overview.md)。150# Conventions
151- Use the error helpers in src/lib/errors.ts, never throw raw strings
152- src/legacy/ is still live but don't copy its patterns into new code
147 153
148### 编写有效的 CLAUDE.md154# Gotchas
155- Integration tests need DATABASE_URL set, see .env.example
156```
149 157
150> [!TIP]158在会话中运行 `/context` 以确认 Claude 已加载该文件。
151>
152> 运行 `/init` 根据你的当前项目结构生成启动 CLAUDE.md 文件，然后随时间精化。
153 159
154CLAUDE.md 是一个特殊文件，Claude 在每次对话开始时读取。包括 Bash 命令、代码风格和工作流规则。这给 Claude 提供了它无法从代码中推断的持久上下文。160请注意，类型检查那一行只是命令本身。Claude 需要知道这个命令，以便在工作过程中检查自己的工作。如果您还希望 Claude Code 在 Claude 完成之前*强制*要求类型检查通过，那是 [`Stop` hook](#enforce-the-check-with-a-stop-hook) 的工作。在这个文件中写 `Always typecheck before you finish` 这样的一行，大多数时候有效，但并非每次都有效。
155 161
156CLAUDE.md 文件没有必需的格式，但保持简短和易读。例如：162您不必从头编写这个文件：
157 163
158```markdown CLAUDE.md theme={null}164* `/init` 会根据您的代码库生成一个初始版本。之后的工作主要是删减行。[记忆指南](https://code.claude.com/docs/zh-CN/memory.md#write-effective-instructions)建议保持在 200 行以内。
159# Code style165* `/doctor` 会针对 Claude [已能从代码中推断出](https://code.claude.com/docs/zh-CN/memory.md#my-claude-md-is-too-large)的内容建议删减。
160- Use ES modules (import/export) syntax, not CommonJS (require)166* `/doctor prompt-audit` 会标记为旧模型编写的指令、指向已不存在文件的指令，或[相互矛盾](https://code.claude.com/docs/zh-CN/memory.md#audit-your-instruction-files)的指令。
161- Destructure imports when possible (eg. import { foo } from 'bar')
162 167
163# Workflow168您的个人偏好应放在 `CLAUDE.local.md` 而不是 `CLAUDE.md` 中，并将该文件添加到 `.gitignore`，使其不进入仓库。
164- Be sure to typecheck when you're done making a series of code changes
165- Prefer running single tests, and not the whole test suite, for performance
166```
167 169
168运行 `/context` 来确认 Claude 加载了该文件。CLAUDE.md 在每个会话中加载，所以只包括广泛适用的东西。对于仅有时相关的域知识或工作流，改用 [skills](https://code.claude.com/docs/zh-CN/skills.md)。Claude 按需加载它们，不会使每次对话都膨胀。170> [!NOTE]
171>
172> 如果 Claude 一直忽略*确实*写在 `CLAUDE.md` 中的某一行，添加 IMPORTANT 可能解决不了问题。要么是文件已经长到让这一行被淹没，要么这一行是一条不允许例外的规则，在这种情况下它应该放进 [hook](#enforce-the-rules-that-cant-have-exceptions)。
169 173
170保持简洁。对于每一行，问自己：*"删除这个会导致 Claude 犯错吗？"* 如果不会，删除它。膨胀的 CLAUDE.md 文件会导致 Claude 忽略你的实际指令！174### 将规则限定到代码库的某一部分
171 175
172| ✅ 包括 | ❌ 排除 |176如果某条规则只在代码库的某一部分有意义，请将它放在 [`.claude/rules/`](https://code.claude.com/docs/zh-CN/memory#path-specific-rules) 中，并加上 `paths:` 过滤器，这样它只会在 Claude 实际在那里工作时加载。例如，下面这个 `.claude/rules/api.md` 会针对 `src/api/` 下的 TypeScript 文件加载：
173| - | - |
174| Claude 无法猜测的 Bash 命令 | Claude 可以通过读取代码弄清楚的任何东西 |
175| 与默认值不同的代码风格规则 | Claude 已经知道的标准语言约定 |
176| 测试指令和首选测试运行器 | 详细的 API 文档（改为链接到文档） |
177| 存储库礼仪（分支命名、PR 约定） | 经常变化的信息 |
178| 特定于你的项目的架构决策 | 长解释或教程 |
179| 开发者环境怪癖（必需的环境变量） | 自明的实践，如"编写干净的代码" |
180| 常见陷阱或非显而易见的行为 | 不言自明的实践，如"编写干净的代码" |
181 177
182如果 Claude 继续做你不想要的事情，尽管有反对的规则，该文件可能太长，规则被遗漏了。如果 Claude 问你在 CLAUDE.md 中回答的问题，措辞可能不明确。像对待代码一样对待 CLAUDE.md：当事情出错时审查它，定期修剪它，并通过观察 Claude 的行为是否实际改变来测试更改。对于检入的 CLAUDE.md，运行 [`/doctor`](https://code.claude.com/docs/zh-CN/commands#all-commands)，Claude 会建议删除它可以从代码库中推导的内容。178```markdown .claude/rules/api.md theme={null}
179---
180paths:
181 - "src/api/**/*.ts"
182---
183- Validate request bodies with the zod schemas in src/api/schemas/, don't hand-roll checks
184- Every new endpoint needs an entry in openapi.yaml, CI fails without it
185```
183 186
184如果 Claude 继续跳过一条指令，添加强调，如"IMPORTANT"到那一行。如果你强调许多行，没有一行会突出。将 CLAUDE.md 检入 git，以便你的团队可以贡献。该文件随时间增加价值。187### 将团队流程放进 skill
185 188
186CLAUDE.md 文件可以使用 `@path/to/import` 语法导入其他文件。有关导入规则和 CLAUDE.md 文件可以存在的位置，请参阅 [CLAUDE.md 文件](https://code.claude.com/docs/zh-CN/memory.md#claude-md-files)。189能力更强的模型懂得更多工程知识，但并不知道*您的*团队如何发布版本、您的事故处理手册写了什么，或者您希望 API 文档怎样编写。这类知识应放在 [skill](https://code.claude.com/docs/zh-CN/skills.md) 中：保存在 `.claude/skills/<name>/SKILL.md` 的流程或团队知识。
187 190
188### 配置权限191对于这类内容，skill 对上下文的占用也比 `CLAUDE.md` 更轻。对于 Claude 可以自行启动的 skill，它在每个会话中只看到名称和描述，只有在任务需要时才会[读取完整文件](https://code.claude.com/docs/zh-CN/skills.md#skill-content-lifecycle)。放在 skill 中的冗长发布流程，不会像放在 `CLAUDE.md` 中那样拖累您无关的错误修复。
189 192
190> [!TIP]193> [!NOTE]
191>194>
192> 要获得更少的提示而不放弃控制，使用 `/permissions` 预先批准你信任的工具，并使用 `/sandbox` 让沙箱命令无需询问即可运行。当你想自己批准编辑和命令时，切换到手动模式。195> `CLAUDE.md` 的规则同样适用于 skill：只写下 Claude 自己找不到的内容。
193 196
194在 Claude Code v2.1.283 或更高版本中，auto mode 是交互式终端和 VS Code 会话的 [内置起始权限模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)：一个单独的分类器模型审查大多数操作，而不是你，仅阻止看起来有风险的东西，如范围升级、未知基础设施或由敌对内容驱动的操作。在早期版本中，auto mode 仅在 Pro、Max 和 Team 计划上是交互式终端和 VS Code 会话的内置起始权限模式。197对于有副作用的工作流，比如真正发布那个版本，请添加 `disable-model-invocation: true`。这样 Claude 就[无法自行启动该 skill](https://code.claude.com/docs/zh-CN/skills.md#control-who-invokes-a-skill)，只有当您自己输入 `/release` 时它才会运行。保存为 `.claude/skills/release/SKILL.md` 后，它可能如下所示：
195 198
196在手动模式中，Claude Code 在可能修改你的系统的操作之前询问：文件写入、Bash 命令、MCP 工具。这是安全的但繁琐。在第十次批准后，你在点击通过而不是审查。两个工具在手动模式中减少这些中断，也适用于 auto mode：199```markdown .claude/skills/release/SKILL.md theme={null}
200---
201name: release
202description: Cut a new release. Bumps the version, writes the changelog entry, tags it and pushes the tag so CI can publish.
203disable-model-invocation: true
204---
2051. Make sure you're on main with a clean tree. If not, stop and ask.
2062. Run `pnpm changeset version` and commit the result.
2073. Summarize the PRs merged since the last tag into CHANGELOG.md, one line each, user-facing changes only.
2084. Tag `v<new version>` and push the tag. CI publishes from there, never publish from your machine.
209```
197 210
198* **权限允许列表**：允许你知道是安全的特定工具，如 `npm run lint` 或 `git commit`211### 连接 Claude 需要的工具
199* **沙箱**：启用操作系统级隔离，限制文件系统和网络访问，允许 Claude 在定义的边界内更自由地工作
200 212
201阅读更多关于 [权限模式](https://code.claude.com/docs/zh-CN/permission-modes.md)、[权限规则](https://code.claude.com/docs/zh-CN/permissions.md) 和 [沙箱](https://code.claude.com/docs/zh-CN/sandboxing.md)。213Claude 看不到的一些信息完全存在于其他系统中，比如您的问题跟踪器或错误仪表板。如果该系统有 CLI，那通常是最简单的接入方式。例如，安装并登录 `gh` 后，Claude 无需您做任何解释就会创建 Pull Request 并读取审查评论。对于它没见过的 CLI，让它查看 `--help` 就足够了。
202 214
203### 使用 CLI 工具215对于没有 CLI 的系统，可以使用 [MCP](https://code.claude.com/docs/zh-CN/mcp.md)。您可以从 shell 中添加服务器：
204 216
205> [!TIP]217```bash theme={null}
206>218claude mcp add --transport http notion https://mcp.notion.com/mcp
207> 告诉 Claude Code 在与外部服务交互时使用 CLI 工具，如 `gh`、`aws`、`gcloud` 和 `sentry-cli`。219```
220
221之后该服务器会出现在会话内的 `/mcp` 下。已连接的服务器即使在您不使用时，也会将其工具名称和说明添加到上下文中，因此值得在那里[关闭您不需要的服务器](https://code.claude.com/docs/zh-CN/mcp.md#disable-a-server-without-removing-it)。
222
223如果您使用类型化语言工作，[代码智能插件](https://code.claude.com/docs/zh-CN/plugins/code-intelligence.md)可以让 Claude 直接跳转到定义，而不必阅读许多文件去寻找它。
208 224
209CLI 工具是与外部服务交互的最 context 高效的方式。如果你使用 GitHub，安装 `gh` CLI。Claude 知道如何使用它来创建问题、打开拉取请求和读取评论。没有 `gh`，Claude 仍然可以使用 GitHub API，但未认证的请求经常会触发速率限制。225## 给 Claude 一个可以运行的检查
210 226
211Claude 也有效地学习它不知道的 CLI 工具。尝试像 `Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C.` 这样的提示。227当工作看起来完成时，Claude 就会停止。如果它没有可以运行的东西来告诉它工作是否*确实*完成，那么"看起来完成"就是它唯一的依据。实际上，这会让您成为测试套件，每个错误都会留在那里，直到您碰巧注意到它。
212 228
213### 连接 MCP 服务器229如果您给它一个返回通过或失败的东西，Claude 就可以自己闭合这个循环。它进行更改，运行检查，如果有东西出错，它会读取输出并修复，然后再次运行检查。
214 230
215> [!TIP]231> [!TIP]
216>232>
217> 运行 `claude mcp add` 带有服务器名称和 URL 或命令来连接外部工具，如 Notion、Figma 或你的数据库。例如：`claude mcp add --transport http notion https://mcp.notion.com/mcp`。233> 给 Claude 一个可以运行并返回通过或失败的东西。一旦有了它，Claude 就可以自行继续工作，您不必盯着。
218 234
219使用 [MCP servers](https://code.claude.com/docs/zh-CN/mcp.md)，你可以要求 Claude 从问题跟踪器实现功能、查询数据库、分析监控数据、集成来自 Figma 的设计并自动化工作流。235检查几乎可以是任何东西，只要 Claude 能读取结果：
220 236
221### 设置 hooks237* 测试文件
238* 构建的退出码
239* linter
240* 将输出与固定数据进行 diff 对比的脚本
241* 放在设计稿旁边的[浏览器屏幕截图](https://code.claude.com/docs/zh-CN/chrome.md)
222 242
223> [!TIP]243如果您的仓库中已经有其中之一，那么 `CLAUDE.md` 中最有用的一行就是运行它的命令。
224>
225> 使用 hooks 来处理必须每次发生且没有例外的操作。
226 244
227[Hooks](https://code.claude.com/docs/zh-CN/hooks-guide.md) 在 Claude 工作流中的特定点自动运行脚本。与 CLAUDE.md 指令不同，hooks 是确定性的，保证操作发生。245检查要多严格由您决定。可选方案从由 Claude 自行决定一直到由 Claude Code 强制执行：
228 246
229Claude 可以为你编写 hooks。尝试像 *"编写一个在每次文件编辑后运行 eslint 的 hook"* 或 *"编写一个阻止写入迁移文件夹的 hook"* 这样的提示。编辑 `.claude/settings.json` 直接配置 hooks，并运行 `/hooks` 来浏览配置的内容。247* 在提示词中：`run the auth tests after, and keep going until they pass`。由 Claude 自行决定何时满意。这适用于任何任务，今天就能用，无需设置。
248* 作为目标：[`/goal all tests in tests/auth pass and lint is clean`](https://code.claude.com/docs/zh-CN/goal) 会设置一个条件，由一个单独的模型在每个轮次之后对照对话进行检查，Claude 会一直工作直到条件满足。您在会话中很少需要亲自使用它。它对长时间的后台运行很重要，在这类运行中，Claude 有时会在仍有未完成事项时以进度总结结束一个轮次，而目标会把它送回去继续工作。
249* 作为 Stop hook：[`Stop` hook](https://code.claude.com/docs/zh-CN/hooks#stop) 会在 Claude 每次尝试结束其轮次时运行您的脚本，如果脚本以退出码 2 退出，就让 Claude 回去继续工作。这一种由 Claude Code（harness）强制执行，因此在类型检查通过或达到[阻止上限](https://code.claude.com/docs/zh-CN/hooks.md#stop-input)之前，轮次不会结束。[下文有一个示例](#enforce-the-check-with-a-stop-hook)。
250* 由没有编写代码的人检查：在终端中，[`/code-review`](https://code.claude.com/docs/zh-CN/code-review-local) 会在一个从未见过您对话的新子代理中审查 diff。它不会被产生代码的推理过程所左右。
230 251
231### 创建 skills252无论使用哪种方案，都要向 Claude 索要*证据*：它运行的命令及其输出，或屏幕截图。单独一句"所有测试都通过了"能告诉您的信息很少，而阅读输出比自己重新运行检查更快。对于您没有盯着的会话，这也是您唯一的证据。
232 253
233> [!TIP]254> [!TIP]
234>255>
235> 在 `.claude/skills/` 中创建 `SKILL.md` 文件，为 Claude 提供域知识和可重用工作流。256> Claude 说完成之后，您还可以在会话中运行 [`/verify`](https://code.claude.com/docs/zh-CN/skills#run-and-verify-your-app)，让 Claude 构建并运行应用，然后查看结果。这能发现测试和类型检查遗漏的那类问题。
236 257
237[Skills](https://code.claude.com/docs/zh-CN/skills.md) 使用特定于你的项目、团队或域的信息扩展 Claude 的知识。Claude 在相关时自动应用它们，或者你可以使用 `/skill-name` 直接调用它们。258### 对照您的规范进行审查
238 259
239通过向 `.claude/skills/` 添加带有 `SKILL.md` 的目录来创建 skill：260如果您更希望审查是对照您的计划检查工作，而不是泛泛地寻找错误，请自己编写审查提示词：
240 261
241```markdown .claude/skills/api-conventions/SKILL.md theme={null}262```text theme={null}
242name: api-conventions263use a subagent to review the rate limiter diff against SPEC.md, check every requirement is implemented and the listed edge cases have tests, report gaps that affect correctness and skip style
243description: REST API design conventions for our services
244# API Conventions
245- Use kebab-case for URL paths
246- Use camelCase for JSON properties
247- Always include pagination for list endpoints
248- Version APIs in the URL path (/v1/, /v2/)
249```264```
250 265
251Skills 也可以定义你直接调用的可重复工作流：266> [!NOTE]
252 267>
253```markdown .claude/skills/fix-issue/SKILL.md theme={null}268> 不要删掉那个提示词中的 `skip style` 部分。被要求找问题的审查者总会找到*一些东西*。如果您修复每一个发现，最终会得到多余的抽象层，以及针对不可能发生的情况的测试。
254name: fix-issue269
255description: Fix a GitHub issue270### 用 Stop hook 强制执行检查
256disable-model-invocation: true271
257Analyze and fix the GitHub issue: $ARGUMENTS.272类型检查规则的 `Stop` hook 版本只需在 `.claude/settings.json` 中写几行。退出码 2 是阻止停止的关键。命令打印到 stderr 的任何内容都会作为 Claude 尚不能完成的原因返回给它，这就是编译器输出被重定向到那里的原因：
258 273
2591. Use `gh issue view` to get the issue details274```json .claude/settings.json theme={null}
2602. Understand the problem described in the issue275{
2613. Search the codebase for relevant files276 "hooks": {
2624. Implement the necessary changes to fix the issue277 "Stop": [
2635. Write and run tests to verify the fix278 {
2646. Ensure code passes linting and type checking279 "hooks": [
2657. Create a descriptive commit message280 { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
2668. Push and create a PR281 ]
282 }
283 ]
284 }
285}
267```286```
268 287
269运行 `/fix-issue 1234` 来调用它。对于具有你想手动触发的副作用的工作流，使用 `disable-model-invocation: true`。288要查看效果，请让 Claude 做一个会破坏类型的更改：它不会就此结束，而是收到编译器错误并继续工作，直到 `tsc` 通过。如果该 hook [连续阻止了八次停止](https://code.claude.com/docs/zh-CN/hooks.md#stop-input)且期间没有任何工具调用，Claude Code 会覆盖下一次阻止并结束该轮次。要提高上限，请设置 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](https://code.claude.com/docs/zh-CN/env-vars)。
270 289
271### 创建自定义 subagents290## 强制执行不允许例外的规则
272 291
273> [!TIP]292> [!TIP]
274>293>
275> 在 `.claude/agents/` 中定义专门的助手，Claude 可以委托给它们来处理隔离的任务。294> 如果某件事必须每次都发生，请将其设为 hook、拒绝规则或托管设置。`CLAUDE.md` 用于准则，而 Claude 可以判定某条准则不适用。
276 295
277[Subagents](https://code.claude.com/docs/zh-CN/sub-agents.md) 在自己的 context 中运行，拥有自己的一组允许的工具。它们对于读取许多文件或需要专门关注而不会使你的主对话混乱的任务很有用。296以您现在可能写在 `CLAUDE.md` 中的三条规则为例：`Never read .env`、`Always run the formatter after editing`、`Don't touch the migrations folder`。Claude 几乎每次都会遵循它们。对于少数"几乎"还不够好的规则，请将它们从 `CLAUDE.md` 中移出，放入由 Claude Code（harness）自行应用的配置中。从那以后，结果就不再取决于模型记住了什么或决定了什么。
278 297
279```markdown .claude/agents/security-reviewer.md theme={null}298### 用 hook 强制执行步骤
280name: security-reviewer299
281description: Reviews code for security vulnerabilities300[Hooks](https://code.claude.com/docs/zh-CN/hooks-guide.md) 会在 Claude 循环中的固定时间点运行您的某样东西：工具调用之前或之后、Claude 尝试停止时、会话开始时等等。这样东西可以是：
282tools: Read, Grep, Glob, Bash301
283model: opus302* shell 命令（常见情况）
284You are a senior security engineer. Review code for:303* 向 HTTP 端点发送 POST 请求
285- Injection vulnerabilities (SQL, XSS, command injection)304* 对您某个 MCP 服务器的工具调用
286- Authentication and authorization flaws305* [`prompt` 或 `agent` hook](https://code.claude.com/docs/zh-CN/hooks#hook-handler-fields)，让模型来决定
287- Secrets or credentials in code306
288- Insecure data handling307`prompt` 或 `agent` hook 会让*另一个模型*来决定，所以它也不是确定性的。要真正强制执行，请使用 `command` 或 `http` hook，如果在 hook 本身崩溃或超时时也应阻止该操作，请添加 [`onFailure: "block"`](https://code.claude.com/docs/zh-CN/hooks#block-the-action-when-a-hook-fails)。例如，对于扫描提交中是否含有密钥的 hook，在扫描器宕机时，您宁愿阻止提交，也不愿让它未经扫描就通过。
308
309下面是将格式化规则写成 `PostToolUse` hook 的样子。它在每次 `Edit` 或 `Write` 之后运行，Claude 是否记得这条规则已不再重要，因为运行它的不是 Claude：
289 310
290Provide specific line references and suggested fixes.311```json .claude/settings.json theme={null}
312{
313 "hooks": {
314 "PostToolUse": [
315 {
316 "matcher": "Edit|Write",
317 "hooks": [
318 { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }
319 ]
320 }
321 ]
322 }
323}
291```324```
292 325
293明确告诉 Claude 使用 subagents：*"使用 subagent 来审查此代码的安全问题。"*326要检验该 hook，请让 Claude 在一个由 Prettier 格式化的文件中添加一行缩进错误的代码。保存后的文件会恢复正确的缩进。
294 327
295### 安装 plugins328迁移规则则变成一个 [`PreToolUse` hook](https://code.claude.com/docs/zh-CN/hooks-guide#block-edits-to-protected-files)，对 `migrations/` 下的任何路径以退出码 2 退出。您不必自己编写它：`write a hook that blocks edits to the migrations folder` 作为提示词就能奏效，`/hooks` 会显示结果。不过不要过度使用：hook 是给*零*例外的规则用的，而 `Prefer named exports` 有很多例外，所以那一条应留在 `CLAUDE.md` 中。
296 329
297> [!TIP]330### 用权限规则和沙箱限制访问
298>
299> 运行 `/plugin` 来浏览市场。Plugins 添加 skills、工具和集成，无需配置。
300 331
301[Plugins](https://code.claude.com/docs/zh-CN/plugins/overview.md) 将 skills、hooks、subagents 和 MCP 服务器捆绑到来自社区和 Anthropic 的单个可安装单元中。如果你使用类型化语言，安装 [代码智能 plugin](https://code.claude.com/docs/zh-CN/plugins/code-intelligence.md) 来为 Claude 提供精确的符号导航和编辑后的自动错误检测。332[权限规则](https://code.claude.com/docs/zh-CN/permissions.md)决定 Claude 可以运行、读取和获取什么。`deny` 规则在每种权限模式下都有效，包括自动模式和 `bypassPermissions`，这正是 `.env` 规则应放在这里的原因：
302 333
303有关在 skills、subagents、hooks 和 MCP 之间选择的指导，请参阅 [扩展 Claude Code](https://code.claude.com/docs/zh-CN/features-overview.md#match-features-to-your-goal)。334```json .claude/settings.json theme={null}
335{
336 "permissions": {
337 "allow": ["Bash(pnpm tsc --noEmit)"],
338 "ask": ["Bash(git push *)"],
339 "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
340 }
341}
342```
304 343
305***344保存之后，询问 Claude `.env` 中有什么将会失败，无论是通过 `Read` 工具还是通过 `cat .env`。
306 345
307## 有效沟通346规则匹配的是工具调用，而不是意图，因此值得了解其边界在哪里：
308 347
309向 Claude 提出你会问另一位工程师的问题，对于更大的功能，让 Claude 采访你并在开始实现之前编写规范。348* `Read` 规则*确实*能拦截 `cat .env`，因为 Claude Code 能识别[常见的文件读取命令](https://code.claude.com/docs/zh-CN/permissions.md#read-and-edit)。
349* 它无法拦截打开该文件的脚本。
350* 针对某个域名的 `WebFetch` 拒绝规则对指向同一域名的 `curl` 不起作用，除非启用了沙箱。
310 351
311### 提出代码库问题352要对文件系统或网络访问进行操作系统级的限制，请在会话中使用 `/sandbox` 启用[沙箱](https://code.claude.com/docs/zh-CN/sandboxing.md)。它会在 macOS、Linux 和 WSL2 上限制 Claude 的 shell 命令，并且还会[采纳您的 `Read` 拒绝规则和 `WebFetch(domain:...)` 规则](https://code.claude.com/docs/zh-CN/sandboxing#permission-rules)，因此对于任何与安全相关的事项，您需要两者兼用。
312 353
313> [!TIP]354默认情况下，Claude 仍然可以请求在沙箱之外重试被阻止的命令，该请求会经过正常的权限流程。`/sandbox` 的 **Overrides** 选项卡中的[严格沙箱模式](https://code.claude.com/docs/zh-CN/sandboxing.md#turn-off-the-retry-with-strict-sandbox-mode)会关闭这种重试。
355
356> [!WARNING]
314>357>
315> 问 Claude 你会问资深工程师的问题。358> 自动模式是一个对每个操作进行判断的分类器模型，而不是硬性规则。它很擅长这件事，但和任何判断一样，它可能出错。您还可以调整它认定为有风险的内容，您的组织也可以完全关闭它，所以您的"绝不"规则应放在拒绝规则或 hook 中。
359
360### 选择规则适用于谁
316 361
317当加入新代码库时，使用 Claude Code 进行学习和探索。你可以问 Claude 你会问另一个工程师的相同类型的问题：362规则放在哪里，决定了它适用于谁：
318 363
319* 日志如何工作？364* `.claude/settings.local.json` 和 `~/.claude/settings.json` 只属于您自己。当您为某个命令选择 **Yes, and don't ask again** 时，Claude Code 会将该规则保存到本地文件中。
320* 我如何创建新的 API 端点？365* `.claude/settings.json` 及其中的 hook 属于仓库。一旦您提交它们，它们就会适用于在该仓库中工作的每个人。其中的拒绝规则立即生效。其中的 `allow` 规则要等到每个人接受该文件夹的[信任对话框](https://code.claude.com/docs/zh-CN/permissions.md#what-runs-before-you-trust-a-folder)后才生效，[工作区信任](https://code.claude.com/docs/zh-CN/hooks.md#workspace-trust)也决定了其中的 hook 何时开始在他们的机器上运行。
321* `foo.rs` 第 134 行的 `async move { ... }` 做什么？366* [托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)属于组织。它们来自管理控制台、MDM 或 `managed-settings.json` 文件，任何个人设置文件都无法覆盖它们，这使它们成为安全团队策略的唯一归宿。如果您是负责设置它们的人，请参阅[为您的组织设置 Claude Code](https://code.claude.com/docs/zh-CN/admin-setup.md)。
322* `CustomerOnboardingFlowImpl` 处理哪些边界情况？
323* 为什么这段代码在第 333 行调用 `foo()` 而不是 `bar()`？
324 367
325以这种方式使用 Claude Code 是一个有效的入职工作流，改进了加入时间并减少了对其他工程师的负担。无需特殊提示：直接提问。368无论作用域如何，都要让强制执行的规则集保持精简。每个 hook 和拒绝规则偶尔都会在不该触发时触发，而且每一个都需要有人维护。如果您发现自己已经有四十条，其中大多数可能只是 Claude 本可以自行权衡的偏好。
326 369
327### 让 Claude 采访你370## 更改默认设置
328 371
329> [!TIP]372> [!TIP]
330>373>
331> 对于更大的功能，让 Claude 先采访你。从最小的提示开始，要求 Claude 使用 `AskUserQuestion` 工具采访你。374> 默认设置已经足够好，可以保持不动，直到某个任务花费的时间、token 或中断超出应有的程度。发生这种情况时，在会话中运行 `/usage` 查看消耗在哪里。
332 375
333Claude 会问你可能还没有考虑过的东西，包括技术实现、UI/UX、边界情况和权衡。将 `[brief description]` 替换为你的功能，然后再发送提示。376新会话已经为您做了几项决定：
334 377
335```text wrap theme={null}378* 交互式终端和 VS Code 会话以自动模式启动。
336I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.379* 在大多数套餐和提供商上，它运行 [medium effort 的 Claude Opus 5.5](https://code.claude.com/docs/zh-CN/model-config.md#default-model-setting)。
380* 当它认为有理由时，会将工作委派给子代理。
381* 随着对话增长，它会压缩对话。
337 382
338Ask 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.383大多数时候您根本不会想到这些。当某个任务确实花费过多时，原因通常是这四项之一。
339 384
340Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.385### 更改权限模式
341```
342 386
343一旦规范完成，启动新会话来执行它。新会话有干净的 context，完全专注于实现，你有一个书面规范可以参考。387权限范围的两端都有代价：
344 388
345最有用的规范是自包含的：它们命名涉及的文件和接口，说明什么在范围之外，并以端到端验证步骤结束，证明该功能有效。花在使规范精确上的时间比花在观看实现上的时间收益更大。389* **手动模式**：您需要亲自批准每次编辑和每个非只读命令。安全，但到第十次提示之后，您就开始不看内容直接批准了，而且当您离开键盘时，一切都会停滞。
390* **`bypassPermissions`**：批准所有未被您的拒绝规则和询问规则覆盖的操作，这只在一次性容器中才有意义。
346 391
347***392[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)介于两者之间，也是交互式终端和 VS Code 会话[启动时使用的模式](https://code.claude.com/docs/zh-CN/permission-modes.md#which-mode-a-session-starts-in)。Claude 在工作时无需为常规批准而停下，一个单独的分类器模型会在操作运行前按[固定顺序](https://code.claude.com/docs/zh-CN/permission-modes.md#how-the-classifier-evaluates-actions)进行检查。它专注于[您希望有人出面阻止的事情](https://code.claude.com/docs/zh-CN/permission-modes.md#what-the-classifier-blocks-by-default)：
348 393
349## 管理你的会话394* `curl | bash`
395* 生产部署和迁移
396* 强制推送覆盖他人的工作
397* 将敏感数据发送到外部端点
398* 看起来是由 Claude 读取的内容而不是由您驱动的操作
350 399
351对话是持久的且可逆的。充分利用这一点！400当它确实阻止了某项操作时，您会收到通知，该操作会出现在 `/permissions` 的 **Recently denied** 下，您可以在那里通过手动批准重试它。在[连续三次阻止](https://code.claude.com/docs/zh-CN/permission-modes.md#when-auto-mode-falls-back)（或总计二十次）之后，自动模式会暂停并恢复为向您询问。
352 401
353### 尽早且频繁地纠正方向402这些都不会取代您的确定性控制，因为它在它们*之后*运行。拒绝规则、询问规则和 `PreToolUse` hook 会在分类器看到任何内容之前生效，因此拒绝规则在自动模式中的阻止效果与在其他任何地方完全相同。沙箱仍然会限制[它所包装的 shell 命令](https://code.claude.com/docs/zh-CN/sandboxing.md#what-runs-outside-the-sandbox)。
354 403
355> [!TIP]404> [!NOTE]
356>405>
357> 一旦发现 Claude 偏离轨道，立即纠正它。406> 您也可以在对话中说 `don't push until I've reviewed`，分类器会[将其视为阻止信号](https://code.claude.com/docs/zh-CN/permission-modes.md#boundaries-you-state-in-conversation)。但这仍然是一个模型在阅读会话记录，而且这句话可能在对话压缩时丢失，所以任何重要的事项都应放在拒绝规则中。
407
408相反的问题是，分类器反复阻止在您的环境中属于常规的操作。与其每次都手动批准，不如将其添加到 `autoMode.allow`，或在[自动模式配置](https://code.claude.com/docs/zh-CN/auto-mode-config.md)中描述您信任的基础设施。它使用的是普通英语而不是模式，[`/auto-mode-setup`](https://code.claude.com/docs/zh-CN/auto-mode-config#generate-environment-entries) 可以根据您的项目和近期会话为您起草 `environment` 部分：
409
410```json ~/.claude/settings.json theme={null}
411{
412 "autoMode": {
413 "environment": [
414 "$defaults",
415 "Source control: github.com/example-org and every repo under it",
416 "Trusted internal domains: *.internal.example.com"
417 ],
418 "allow": [
419 "$defaults",
420 "Deploying to the staging namespace is fine, it's isolated from production and resets nightly"
421 ]
422 }
423}
424```
358 425
359最好的结果来自紧密的反馈循环。虽然 Claude 有时能在第一次尝试时完美解决问题，但快速纠正通常能更快地产生更好的解决方案。426> [!WARNING]
427>
428> 在您设置的每个列表中都保留 `"$defaults"`，否则您的条目会*替换*该列表的内置规则，而不是添加到其中。对于 `environment` 和 `allow`，您会失去内置的上下文和例外；而缺少它的 `soft_deny` 列表会丢掉对强制推送和生产部署的内置阻止。
429>
430> `autoMode` 块还必须放在 `~/.claude/settings.json` 中，而不是项目中，因为分类器会忽略项目设置中的 `autoMode`。
360 431
361* **`Esc`**：使用 `Esc` 键在 Claude 执行过程中停止它。上下文会被保留，所以你可以重新引导。432如果您更希望在每次编辑和命令发生之前都能看到它们，可以在会话中按 `Shift+Tab` 在各权限模式（包括手动模式）之间循环切换，或者从 shell 中使用 `claude --permission-mode manual` 启动。如果手动模式随后询问过于频繁，`/fewer-permission-prompts` 会扫描您近期的会话记录，找出常见的只读 Bash 和 MCP 调用，并将它们添加到 `.claude/settings.json` 中的允许列表。
362* **`Esc + Esc` 或 `/rewind`**：按两次 `Esc` 或运行 `/rewind` 来打开 rewind 菜单，恢复之前的对话和代码状态，或从选定的消息进行总结。
363* **`"Undo that"`**：让 Claude 撤销其更改。
364* **`/clear`**：在不相关的任务之间重置上下文。包含无关上下文的长会话可能会降低性能。
365 433
366如果你在一个会话中对同一问题纠正了 Claude 两次以上，上下文就会被失败的方法所污染。运行 `/clear` 并使用更具体的提示重新开始，该提示应该包含你学到的内容。一个干净的会话配合更好的提示几乎总是比一个积累了许多纠正的长会话表现更好。434### 更改模型和 effort
367 435
368### 积极管理上下文436[Effort](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level) 是控制 Claude 思考时长的主要手段，它取代了人们过去通过提示词措辞所做的大部分工作。Claude Opus 5.5、Sonnet 5.5 和 Haiku 5.5 默认为 `medium`，这对于范围明确的日常功能开发已经足够。您会在会话中使用 `/effort` 调整它的情况：
369 437
370> [!TIP]438* 当做对事情取决于容易被忽略的情况时，使用 `/effort high` 或 `/effort xhigh` 调高。比如您没写过的代码中的错误、不稳定的测试，或者 Claude 必须找到旧 schema 的每一个读取方的 schema 变更。Claude 随后会在回答前检查更多边界情况并验证更多工作，额外的时间和 token 就花在这里。
371>439* 当您快速来回交流并且无论如何都会审查每个结果时，使用 `/effort low` 调低：头脑风暴、初步草图、跨几个文件的重命名。Claude 会更快地给您一个起点，而且由于您在引导每一步，额外的深思熟虑除了让您多等之外不会改变太多。
372> 在不相关的任务之间运行 `/clear` 来重置上下文。440* 将 `max` 留给您希望 Claude 在没有您参与的情况下攻克的难题，比如寻找安全漏洞。在普通任务上它往往会过度思考，所以您付出更多，得到的答案却可能并不比 `high` 更好。
441* 当只有下一条消息需要它时，比如在一系列常规工作中间出现一个棘手的问题，请在那条提示词中加入 [`ultrathink`](https://code.claude.com/docs/zh-CN/model-config#use-ultrathink-for-one-off-deep-reasoning)，而不是更改设置。
373 442
374当你接近上下文限制时，Claude Code 会自动压缩对话历史，这样可以保留重要的代码和决策，同时释放空间。443至于模型本身，默认的 Opus 5.5 能很好地处理大多数编码工作，而 Sonnet 在常规工作上成本更低。当您通过 `/model fable` 明确选择时，可以使用 [Claude Fable 5.1](https://code.claude.com/docs/zh-CN/model-config.md#work-with-fable)，而 Haiku 很适合执行简单任务的子代理。[模型配置](https://code.claude.com/docs/zh-CN/model-config.md)列出了各套餐和提供商的完整列表。
375 444
376在长会话期间，Claude 的上下文窗口可能会被无关的对话、文件内容和命令填满。这可能会降低性能，有时还会分散 Claude 的注意力。445### 了解子代理的成本
377 446
378* 在任务之间频繁使用 `/clear` 来完全重置上下文窗口447Claude 会自行委派给[子代理](https://code.claude.com/docs/zh-CN/sub-agents.md)：
379* 当自动压缩触发时，Claude 会总结最重要的内容，包括代码模式、文件状态和关键决策
380* 为了获得更多控制，运行 `/compact <instructions>`，例如 `/compact Focus on the API changes`
381* 要仅压缩对话的一部分，使用 `Esc + Esc` 或 `/rewind`，选择一个消息检查点，然后选择**从这里总结**或**总结到这里**。第一个选项会压缩从该点开始的消息，同时保留较早的上下文；第二个选项会压缩较早的消息，同时保留最近的消息完整。参见 [rewind 菜单的总结选项](https://code.claude.com/docs/zh-CN/checkpointing.md#rewind-and-summarize)。
382* 在 CLAUDE.md 中自定义压缩行为，使用诸如 `"When compacting, always preserve the full list of modified files and any test commands"` 这样的指令，以确保关键上下文在总结中得以保留
383* 对于不需要保留在上下文中的问题，使用 [`/btw`](https://code.claude.com/docs/zh-CN/interactive-mode#side-questions-with-%2Fbtw)。答案永远不会进入对话历史，所以你可以检查细节而不会增加上下文。
384 448
385### 使用子代理进行调查449* 广泛的代码库搜索交给内置的 Explore Agent。
450* 在 fork 模式开启时（默认），附带任务会被[分叉](https://code.claude.com/docs/zh-CN/sub-agents.md#fork-the-current-conversation)。
451* 它启动的子代理默认在后台运行，因此您的主对话可以继续推进。
386 452
387> [!TIP]453您很少需要主动要求这些，但了解您得到的是什么以及代价是什么会有所帮助。
388>
389> 使用 `"use subagents to investigate X"` 委派研究。它们在单独的上下文中探索，保持你的主对话干净以供实现。
390 454
391由于上下文是你的基本约束，使用子代理来保持研究不进入上下文。当 Claude 研究代码库时，它会读取大量文件，所有这些都会消耗你的上下文。子代理在单独的上下文窗口中运行并报告回总结：455子代理在以下情况下物有所值：
392 456
393```text wrap theme={null}457* 同时运行相互独立的工作，让整个任务更快完成
394Use subagents to investigate how our authentication system handles token458* 将长输出（比如完整的测试运行或大范围搜索）排除在主对话之外，否则它会在会话的剩余部分一直伴随着您
395refresh, and whether we have any existing OAuth utilities I should reuse.459* 获得一个没有看到代码编写过程的审查者
396```460* 给某个任务提供比主会话更少的工具，比如一个能读取但不能编辑的审查者
397 461
398你也可以在 Claude 实现某些东西后使用子代理进行验证。参见 [添加对抗性审查步骤](#add-an-adversarial-review-step)。462它们的代价主要是 token，因为每个子代理都会发送自己的请求，并且与您的主对话计入相同的用量。有时还有时间成本：新的子代理必须先收集您的对话中已有的上下文，因此它可能比在当前会话中直接完成任务*更慢*。
399 463
400### 使用检查点进行 Rewind464而且默认情况下，它是同一个模型（或更小的模型）处理同一个任务。您从中获得的是并行性或一双新的眼睛，而不是更聪明的答案。
401 465
402> [!TIP]466要在子代理上花得更少：
403>
404> 你发送的每个开始一个轮次的提示都会创建一个检查点。你可以将对话、代码或两者都恢复到任何之前的检查点。
405 467
406Claude 在每次更改前自动为文件创建快照，所以检查点可以将它们恢复。双击 `Escape` 或运行 `/rewind` 来打开 rewind 菜单。你可以仅恢复对话、仅恢复代码、同时恢复两者，或从选定的消息进行总结。参见 [Checkpointing](https://code.claude.com/docs/zh-CN/checkpointing.md) 了解详情。468* 如果子代理的工作很简单，比如收集导入某个模块的文件或检查文档中的链接，请在其定义中设置 [`model: haiku`](https://code.claude.com/docs/zh-CN/sub-agents#choose-a-model)。这类工作不需要更大的模型，而 Haiku 每次请求的成本要低得多。
469* 要求返回简短的总结，这样二十个结果就不会反而填满您的上下文。
470* 查看 `/usage`，了解每种子代理类型占您用量的多少，从而判断哪些物有所值。
471* 给 `.claude/agents/` 中的自定义子代理只配置 `tools: Read, Grep, Glob`。这样它就是一个无法编辑任何内容的审查者，而且这一限制由 Claude Code 强制执行，而不是在提示词中请求。
407 472
408与其仔细规划每一步，你可以告诉 Claude 尝试一些冒险的事情。如果它不起作用，rewind 并尝试不同的方法。检查点与对话一起保存，所以你可以关闭终端，稍后恢复会话，并仍然可以 rewind。473这个审查者只是一个简短的文件，`.claude/agents/reviewer.md`：
409 474
410> [!WARNING]475```markdown .claude/agents/reviewer.md theme={null}
411>476---
412> 检查点仅跟踪通过 Claude 的文件编辑工具所做的更改。通过 Bash 命令或外部进程所做的更改不会被捕获。这不是 git 的替代品。477name: reviewer
478description: Reviews changed files against the spec they were built from. Use after implementing a feature, before opening the PR.
479tools: Read, Grep, Glob
480---
481You're reviewing code you didn't write. Compare the changed files against the spec you're given,
482check that every requirement is implemented and the listed edge cases have tests,
483and report only the gaps that affect correctness. Skip style.
484```
413 485
414### 恢复对话486让 Claude `have the reviewer compare the rate limiter against SPEC.md`，发现的缺口就会回到您的会话中，由 Claude 来修复。
415 487
416> [!TIP]488### 控制成本和上下文
417>
418> 使用 `/rename` 命名会话，并将它们视为分支：每个工作流都有自己的持久上下文。
419 489
420Claude Code 在本地保存对话，所以当任务跨越多个会话时，你不必重新解释上下文。运行 [`claude --continue`](https://code.claude.com/docs/zh-CN/sessions#resume-a-session) 来从你停止的地方继续，或 `claude --resume` 来从列表中选择。给会话起描述性的名称，如 `oauth-migration`，这样你以后可以找到它们。参见 [管理会话](https://code.claude.com/docs/zh-CN/sessions.md) 了解完整的恢复、分支和命名控制。490由于大多数当前模型拥有 1M token 的窗口，并且在接近上限时进行压缩，您很少会用完上下文。不过，您仍然可能为不需要的上下文*付费*。每个请求都会发送整个对话，因此一个累积了三个无关任务的会话，在处理第四个任务的每个轮次时都会重新读取前三个。在[缓存有效期间会有折扣](https://code.claude.com/docs/zh-CN/costs.md#why-usage-climbs-in-a-long-session)，而缓存过期后则按全价计费。
421 491
422***492[`/usage`](https://code.claude.com/docs/zh-CN/costs) 是首先要查看的地方。在 Pro、Max、Team 和 Enterprise 上，它会按 skill、子代理、插件和 MCP 服务器细分您的用量。当长上下文或频繁缓存未命中等模式之一超过您用量的 10% 时，它也会标记出来。常见的解决方法有：
423 493
424## 自动化和扩展494* 在不相关的任务之间使用 `/clear`。它不花任何成本，并且意味着下一个任务不必继续为上一个任务的历史付费。`/clear oauth-migration` 会为您离开的会话命名，以便您之后回到它。
495* 带焦点地使用 `/compact`，比如 `/compact keep the API changes and the test commands`。在长会话中，`/compact` 本身就是一个大请求，因为它要读取整个对话来进行总结，缓存过期后更是如此。
496* 留意后台工作：`/loop`、目标在每个轮次之后的检查，以及 Claude 自己的子代理，都会在您没有输入时持续发送请求。
425 497
426一旦你对一个 Claude 有效，通过并行会话、非交互模式和扇出模式来增加你的输出。498> [!NOTE]
499>
500> [提示缓存](https://code.claude.com/docs/zh-CN/prompt-caching.md)在订阅下持续约一小时，在 API 密钥、云提供商或使用额度下为五分钟。除非您更改，否则子代理为五分钟。
501>
502> 在一小时缓存下，超过约 200K token 的空闲会话会在缓存过期前不久被压缩，因此午饭回来后您会从一份总结继续。如果您完全不需要这些历史，开启新会话的成本仍然更低。
427 503
428### 运行非交互模式504## 引导会话
429 505
430> [!TIP]506> [!TIP]
431>507>
432> 在 CI、pre-commit hooks 或脚本中使用 `claude -p "prompt"`。添加 `--output-format stream-json --verbose` 用于流式 JSON 输出。508> 留意第一分钟，一旦 Claude 偏离方向就按 `Esc`，在两次更正失败后运行 `/clear` 并写一个更好的提示词，而不是进行第三次更正。
433 509
434使用 `claude -p "your prompt"`，你可以非交互地运行 Claude，不需要交互式提示。该运行仍然会创建一个可恢复的会话，除非你传递 `--no-session-persistence`。[非交互模式](https://code.claude.com/docs/zh-CN/headless.md)是你将 Claude 集成到 CI 管道、pre-commit hooks 或任何自动化工作流中的方式。输出格式让你以编程方式解析结果：纯文本、JSON 或流式 JSON。510再多的配置也无法取代留意第一分钟，并在 Claude 朝您不想要的方向前进时介入。用于此目的的控制手段只有几个，值得熟记于心：
435 511
436```bash theme={null}512* `Esc` 会在 Claude 执行过程中停止它，并保留到那时为止的所有内容，因此您可以重新引导而不丢失工作。
437# One-off queries513* `/rewind`，或在空提示词上按两次 `Esc`，会打开 [rewind 菜单](https://code.claude.com/docs/zh-CN/checkpointing.md#rewind-and-summarize)，您可以在其中将代码、对话或两者回滚到更早的提示词。这让先尝试更大胆的方法、行不通再回滚变得风险很低。当对话的某部分已经过时，同一个菜单还可以对其进行总结。
438claude -p "Explain what this project does"514* `/clear` 会重新开始。如果您已经两次更正同一件事而它仍然是错的，第三次更正多半只是往一个已经包含两次失败尝试的对话中添加内容，而 Claude 会不断重读这些内容。`/clear` 加上一个融合了您所学内容的新提示词，几乎每次效果都更好。
439
440# Structured output for scripts
441claude -p "List all API endpoints" --output-format json
442 515
443# Streaming for real-time processing516> [!WARNING]
444claude -p "Analyze this log file" --output-format stream-json --verbose517>
445```518> 检查点涵盖的是 Claude 在主对话中使用其自身文件工具编辑的文件，因此只被 Bash 命令改动过的文件[不会被恢复](https://code.claude.com/docs/zh-CN/checkpointing.md#bash-command-changes-not-tracked)。它们与 git 配合使用，而不是取代 git。
446 519
447第一个命令打印纯文本。`json` 格式返回一个包含 `result` 字段的单个 JSON 对象。`stream-json` 格式每行打印一个 JSON 对象，从初始化事件开始。520还有两个较小的工具：[`/btw`](https://code.claude.com/docs/zh-CN/interactive-mode#side-questions-with-%2Fbtw) 可以回答一个快速问题，而不会向历史中添加任何内容。对于跨越数天的工作，在会话中使用 `/rename oauth-migration` 为其命名，之后就可以从 shell 中使用 [`claude --resume oauth-migration`](https://code.claude.com/docs/zh-CN/sessions#resume-by-session-id-or-name) 继续，包括检查点在内。`claude --continue` 会恢复最近的一个会话。
448 521
449### 运行多个 Claude 会话522## 让 Claude 在无人值守时运行
450 523
451> [!TIP]524> [!TIP]
452>525>
453> 并行运行多个 Claude 会话以加快开发、运行隔离的实验或启动复杂的工作流。526> 在让某次运行无人值守之前，确保它知道完成是什么样子、能检查自己的工作，并且只能触及它应该触及的内容。给它设置轮次或支出上限，并在最后由一个人批准结果。
454
455选择适合你想要自己进行多少协调的并行方法，并在会话需要相互传递发现时添加消息：
456 527
457* [Worktrees](https://code.claude.com/docs/zh-CN/worktrees.md)：在隔离的 git 检出中运行单独的 CLI 会话，以便编辑不会冲突528一旦您不在场去发现错误，本页上的所有内容就显得更加重要。当您在盯着时，Claude 缺少某部分上下文并不是什么大问题：您会在一两条消息内注意到并告诉它。而在您睡前启动的运行中，没有人告诉它，您第二天早上才发现它整晚都在基于错误的假设进行构建。
458* [跨会话消息](https://code.claude.com/docs/zh-CN/cross-session-messaging.md)：让你自己运行的会话相互传递发现
459* [桌面应用](https://code.claude.com/docs/zh-CN/desktop.md#work-in-parallel-with-sessions)：以视觉方式管理多个本地会话，每个会话都在自己的 worktree 中
460* [Claude Code 在网络上](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)：在云中运行会话，默认在 Anthropic 管理的基础设施上
461* [Agent view](https://code.claude.com/docs/zh-CN/agent-view.md)：研究预览。运行 `claude agents` 来分派在后台持续运行的会话，并从一个屏幕观看它们
462* [Agent teams](https://code.claude.com/docs/zh-CN/agent-teams.md)：实验性的，默认禁用。具有共享任务、消息和团队主管的多个会话的自动协调
463 529
464除了并行化工作，多个会话启用了质量关注的工作流。新鲜的 context 改进了代码审查，因为 Claude 不会偏向于它刚刚编写的代码。530在让任务自行运行之前，值得针对该具体任务逐一检查以下五个问题：
465 531
466例如，使用 Writer/Reviewer 模式：5321. 它知道完成是什么样子吗？一个目标条件、一个规范文件，或一个它必须让其通过的失败测试。
5332. 它能检查自己的工作吗？测试套件、`Stop` hook、某种审查步骤。
5343. 它被允许触及什么？权限规则、`dontAsk`、沙箱、worktree、它可以推送的那一个分支。
5354. 什么会让它停下来？`--max-turns`、`--max-budget-usd`、支出限额。
5365. 结果去哪里，谁来签核？一个 PR、一条评论或一份总结，然后由一个人批准合并、部署或任何其他无法撤回的操作。
467 537
468| 会话 A（Writer） | 会话 B（Reviewer） |538一旦开始运行，Claude 会自行完成一个长任务。仍由您负责的部分是：启动它、决定这一次"完成"意味着什么，以及在最后批准合并。
469| - | - |
470| `为我们的 API 端点实现速率限制器` | |
471| | `审查 @src/middleware/rateLimiter.ts 中的速率限制器实现。查找边界情况、竞态条件和与我们现有中间件模式的一致性。` |
472| `这是审查反馈：[会话 B 输出]。解决这些问题。` | |
473 539
474你可以用测试做类似的事情：让一个 Claude 编写测试，然后另一个编写代码来通过它们。540### 从脚本运行 Claude
475 541
476### 跨文件扇出542[`claude -p "prompt"`](https://code.claude.com/docs/zh-CN/headless) 运行一次后退出，Claude Code 就是这样进入 CI 作业、git 钩子和 shell 循环的。
477
478> [!TIP]
479>
480> 循环遍历任务，为每个任务调用 `claude -p`。使用 `--allowedTools` 为批量操作预先批准工具。
481 543
482对于大型迁移或分析，你可以跨许多并行 Claude 调用分配工作。运行 [`/batch <instruction>`](https://code.claude.com/docs/zh-CN/commands#all-commands) 让 Claude 将更改分割到 5 到 30 个子代理中。每个子代理在自己的 worktree 中工作。要从你自己的脚本驱动扇出，请循环遍历 `claude -p`：544在脚本中，您几乎总是需要再加几个标志：
483 545
484**1. 生成任务列表**546* [`--bare`](https://code.claude.com/docs/zh-CN/headless#start-faster-with-bare-mode) 会跳过 hook、skill、插件、MCP 服务器和 `CLAUDE.md` 文件（包括仓库的和机器的），因此无论在哪里运行，结果都一样。它也从不触及您的 claude.ai 登录：身份验证来自 `ANTHROPIC_API_KEY`、您通过 `--settings` 传入的文件中的 `apiKeyHelper`，或您的云提供商的凭据。
547* `--append-system-prompt`、`--mcp-config` 和 `--settings` 会显式传入运行*确实*需要的内容。
548* `--allowedTools` 会预先批准其工具，而 [`--permission-mode dontAsk`](https://code.claude.com/docs/zh-CN/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) 会拒绝其他任何原本会触发提示的操作。
549* `--output-format json` 会为您提供一个可供解析的单一结果对象，而搭配 `--verbose` 的 `stream-json` 会在事件发生时流式输出。
485 550
486让 Claude 将需要迁移的文件列表写入文件，以便下一步中的循环可以读取它，使用类似 `list all 2,000 Python files that need migrating and save the list to files.txt` 的提示551组合起来如下所示：
487
488**2. 编写脚本来循环遍历列表**
489 552
490```bash theme={null}553```bash theme={null}
491for file in $(cat files.txt); do554for file in $(cat files.txt); do
492 claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \555 claude --bare -p "Migrate $file to the new logger API and commit. Reply OK or FAIL." \
493 --allowedTools "Edit,Bash(git commit *)" \556 --allowedTools "Read,Edit,Bash(git add *),Bash(git commit *)" \
494 --permission-mode dontAsk557 --permission-mode dontAsk \
558 --max-turns 20
495done559done
496```560```
497 561
498**3. 先在几个文件上测试，然后在全部文件上运行**562运行结束时，Claude 会回复 `OK` 或 `FAIL`，而达到轮次上限的运行则会以错误退出。先在三个文件上试一试，看看哪里出了问题，修正提示词，然后再运行其余部分。
499
500根据前 2-3 个文件出现的问题改进提示词，然后在完整集合上运行。`--allowedTools` 标志预先批准迁移所需的工具。[`--permission-mode dontAsk`](https://code.claude.com/docs/zh-CN/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) 会拒绝其他任何需要批准的操作，这在无人值守运行时非常重要，不过您安装的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 仍可能批准其中部分调用。
501 563
502你也可以将 Claude 集成到现有的数据/处理管道中：564如果传入 `--permission-mode auto`，自动模式也可以与 `-p` 一起使用。在非交互式运行中，分类器的阻止只会拒绝那一个操作，Claude 会继续工作，而且重复的阻止不会像在终端中那样暂停运行。在依赖它之前，请阅读[阈值在那里如何应用](https://code.claude.com/docs/zh-CN/permission-modes.md#repeated-block-thresholds)。
503 565
504```bash theme={null}566### 按计划或事件启动运行
505claude -p "<your prompt>" --output-format json | your_command
506```
507 567
508### 使用 auto mode 自主运行568一旦运行开始，Claude 就能自行处理剩下的事情。它唯一做不到的是决定*开始*，所以必须有某样东西来启动它：您、一个计时器，或者一个事件，比如 CI 检查失败或新的 PR。
509 569
510为了不间断的执行和后台安全检查，使用 [auto mode](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)。分类器模型在命令运行前审查它们，阻止范围升级、未知基础设施和由敌对内容驱动的操作，同时让常规工作无提示进行。570在已打开的会话中，可以使用 [`/loop`](https://code.claude.com/docs/zh-CN/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop)，它会按间隔重复一个提示词：
511 571
512```bash theme={null}572```text theme={null}
513claude --permission-mode auto -p "fix all lint errors"573/loop 15m check CI on this branch, and if it's red pull the failing job's log, fix it and push
514```574```
515 575
516当分类器在使用 `-p` 标志的非交互运行中重复阻止操作时，Claude Code 不会停止运行。请参阅 [auto mode 何时回退](https://code.claude.com/docs/zh-CN/permission-modes.md#when-auto-mode-falls-back) 了解发生的情况以及阈值。576每次运行都是同一会话中的另一个轮次，所以不要在长对话中让它一直运行。对于任何应在您的笔记本电脑合上时进行的事情，[`/schedule`](https://code.claude.com/docs/zh-CN/routines#create-from-the-cli) 会设置一个按计时器运行的[云端定时任务](https://code.claude.com/docs/zh-CN/routines.md)。它需要 claude.ai 登录，而不是 API 密钥。您可以通过询问 Claude 添加 GitHub 事件触发器，或在 [claude.ai/code/routines](https://claude.ai/code/routines) 添加 API 触发器。
517
518### 添加对抗性审查步骤
519 577
520> [!TIP]578> [!WARNING]
521>579>
522> 在将任务视为完成之前，让一个子代理在新鲜的 context 中审查差异并报告缺陷。580> 在让云端定时任务持续运行之前，请使用[该任务无法绕过的 GitHub 分支规则](https://code.claude.com/docs/zh-CN/routines.md#repositories-and-branch-permissions)保护 `main`。对于任何新的任务，在信任它无人值守运行之前，请先观察最初的几次运行。
523
524Claude 无人值守工作的时间越长，在你将工作视为完成之前进行独立检查就越重要。在新鲜的 [subagent](https://code.claude.com/docs/zh-CN/sub-agents.md) context 中运行的审查者只看到差异和你给它的标准，而不是产生更改的推理，所以它按自己的条件评估结果。
525 581
526对于正确性检查，运行捆绑的 [`/code-review` skill](https://code.claude.com/docs/zh-CN/commands)，它在新鲜的子代理中审查当前差异以查找错误，并将发现返回到会话。要检查差异是否符合你的计划，请自己编写审查提示。命名要检查的工作、要检查的计划以及什么算作发现：582### 并行运行会话
527 583
528```text wrap theme={null}584当您同时进行多项独立的工作时，给每项工作分配独立的检出，以免编辑相互冲突。[`claude -w feature-auth`](https://code.claude.com/docs/zh-CN/worktrees#start-claude-in-a-worktree) 会在新的 worktree 中启动会话，[桌面应用](https://code.claude.com/docs/zh-CN/desktop.md#work-in-parallel-with-sessions)可以并排运行多个这样的会话，而[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)会在云端而不是您的机器上运行它们。
529Use a subagent to review the rate limiter diff against PLAN.md. Check that
530every requirement is implemented, the listed edge cases have tests, and
531nothing outside the task's scope changed. Report gaps, not style preferences.
532```
533 585
534因为审查者作为子代理运行，实现会话直接接收缺陷，可以修复它们并重新审查，而无需你在窗口之间复制发现。586worktree 是一个全新的检出，这意味着像 `.env` 这样被 gitignore 的文件不在其中，依赖也没有安装。对于前者，请在仓库根目录的 [`.worktreeinclude`](https://code.claude.com/docs/zh-CN/worktrees#copy-gitignored-files-into-worktrees) 中列出您需要的被 gitignore 的文件（语法与 `.gitignore` 相同），Claude Code 会将它们复制到它创建的每个 worktree 中：
535 587
536被提示查找缺陷的审查者通常会报告一些，即使工作是健全的，因为那是它被要求做的。追逐每个发现会导致过度工程：额外的抽象层、防御性代码和针对无法发生的情况的测试。告诉审查者只标记影响正确性或陈述要求的缺陷，将其余的视为可选。588```text .worktreeinclude theme={null}
589.env
590.env.local
591config/dev-credentials.json
592```
537 593
538***594只放小文件：它是复制而不是链接，所以如果把 `node_modules` 放进去，就意味着每个 worktree 都要完整复制一份。对于大型目录，可以使用 [`worktree.symlinkDirectories`](https://code.claude.com/docs/zh-CN/settings-reference#worktree-symlinkdirectories) 设置，或者将安装命令写在 `CLAUDE.md` 中，让 Claude 每次在新检出中启动时运行它。
539 595
540## 避免常见失败模式596您很少需要自己清理这些：
541 597
542这些是常见的错误。尽早识别它们可以节省时间：598* 当您退出一个未命名的 worktree 会话时，如果其中没有任何内容，Claude Code 会[删除该 worktree](https://code.claude.com/docs/zh-CN/worktrees.md#clean-up-worktrees)。对于已命名的会话或有更改的会话，它会询问如何处理。
599* 子代理的 worktree 会在子代理无更改地完成时消失。
600* 确实被遗留下来的子代理和后台会话 worktree，一旦超过 `cleanupPeriodDays` 且不包含任何工作，就会被清理掉。
543 601
544* **厨房水槽会话。** 你从一个任务开始，然后问 Claude 一些不相关的东西，然后回到第一个任务。Context 充满了无关的信息。602> [!NOTE]
545 > **修复**：在不相关的任务之间 `/clear`。603>
546* **一次又一次地改正。** Claude 做错了什么，你改正它，它仍然是错的，你再改正。Context 被失败的方法污染。604> `claude -p --worktree` 运行需要您自己清理，因为它退出时不会询问。使用 `git worktree remove <path>` 删除它们；如果 git 因 worktree 被锁定而拒绝，请先执行 `git worktree unlock <path>`。
547 > **修复**：在两次失败的改正后，`/clear` 并编写一个更好的初始提示，包含你学到的东西。
548* **过度指定的 CLAUDE.md。** 如果你的 CLAUDE.md 太长，Claude 会忽略一半，因为重要的规则在噪音中丢失。
549 > **修复**：无情地修剪。如果 Claude 已经在没有指令的情况下正确地做某事，删除它或将其转换为 hook。
550* **信任然后验证的差距。** Claude 产生一个看起来合理的实现，但不处理边界情况。
551 > **修复**：始终提供验证（测试、脚本、屏幕截图）。如果你不能验证它，不要发布它。
552* **无限探索。** 你要求 Claude "调查"某些东西而不限定范围。Claude 读取数百个文件，填充 context。
553 > **修复**：狭隘地限定调查或使用 subagents，以便探索不会消耗你的主 context。
554 605
555***606对于跨许多文件的一次大型机械性更改，[`/batch migrate every handler to the v2 response helpers`](https://code.claude.com/docs/zh-CN/commands) 会将工作拆分为 5 到 30 个单元并向您展示计划。然后它会在各自的 worktree 中运行每个单元，并为其创建 PR。从 shell 中，[`claude agents`](https://code.claude.com/docs/zh-CN/agent-view)（目前仍为研究预览版）可以在一个屏幕上显示您机器后台运行的所有内容。
556 607
557## 培养你的直觉608第二个会话也是您能获得的最简单的独立审查者。一个会话编写速率限制器，另一个会话在没有看到编写过程的情况下审查 `@src/middleware/rateLimiter.ts`，然后您将发现粘贴回第一个会话。这与 `/code-review` 的思路相同，只是由您来传递消息。
558 609
559本指南中的模式不是一成不变的。它们是通常效果很好的起点，但可能不是每种情况的最优选择。610## 您可以不再做的事
560 611
561有时你\_应该\_让 context 累积，因为你深入一个复杂的问题，历史很有价值。有时你应该跳过规划，让 Claude 弄清楚，因为任务是探索性的。有时模糊的提示正是你想要的，因为你想看看 Claude 如何解释问题，然后再限制它。612以下每一条在写下时都是好建议。其中大多数是对模型当时还不能可靠完成的事情的变通办法，而模型现在已经赶上来了。如果其中一些仍是您的习惯，以下是可以放心放弃它们的原因。
562 613
563注意什么有效。当 Claude 产生很好的输出时，注意你做了什么：提示结构、你提供的 context、你所在的模式。当 Claude 遇到困难时，问为什么。Context 太嘈杂了吗？提示太模糊了吗？任务对于一次通过来说太大了吗？614| 旧建议 | 为何不再需要 |
615| :- | :- |
616| 上下文窗口是您的主要约束，要积极地管理它 | 大多数当前模型拥有 1M token 的窗口，而且压缩会自动进行，因此很少会用完。在任务之间使用 `/clear` 仍然值得，因为专注的上下文能带来更好的答案，并且成本更低。 |
617| 对 Claude 一直遗漏的指令添加 IMPORTANT 或全大写 | 较旧的模型有时需要这种强调。当前模型能遵循措辞平实的一行，而堆砌强调多半会让 Claude 过度应用该规则。如果这是一条不能变通的规则，请将其改为 hook 或拒绝规则。如果这一行在长文件中被淹没，那就需要缩短文件。 |
618| 使用子代理来保护您的上下文窗口 | 用完上下文已经很少成为问题。子代理在并行工作、让嘈杂的输出不碍事以及独立审查方面仍然很好用，但每一种用法都要花费额外的 token。 |
619| 委派给子代理以获得更好的答案 | 把同一个任务交给子代理并不会让答案变得更好。新的审查者确实有帮助，因为它没有看到您的推理过程，但这与委派是两回事。 |
620| 在提示词中写 `think hard`、`think harder`、`be thorough` | Effort 才是控制这一点的手段。这些短语只是普通的提示词文本，会在 effort 设置范围内轻微推动 Claude，而不是提升 effort 的关键词。`ultrathink` 仍然有效：它会在单个轮次中请求更深入的推理，而不改变您的 effort 设置。 |
621| 告诉 Claude 继续下去、循环直到完成、不要偷懒 | 当前模型通常会在无需提醒的情况下完成已商定的任务，而这类话更可能导致过度工作，而不是解决停滞。给 Claude 一个必须通过的检查则不同，仍然值得去做。如果某次运行确实提前停止，说 `continue` 即可；对于无人盯着的运行，`/goal` 或 `Stop` hook 会强制执行这一点。 |
622| 在 `CLAUDE.md` 中描述您的架构和文件布局 | Claude 会自己阅读仓库。只写下其中没有的内容。 |
564 623
565随着时间的推移，你会培养没有指南能捕捉的直觉。你会知道何时具体，何时开放，何时规划，何时探索，何时清除 context，何时让它累积。624如果本页上的其他建议开始让您觉得是在做无用功，那很可能说明它也应该列入这张表。
566 625
567## 相关资源626## 相关资源
568 627
569* [Claude Code 如何工作](https://code.claude.com/docs/zh-CN/how-claude-code-works.md)：代理循环、工具和 context 管理628* [Claude Code 如何工作](https://code.claude.com/docs/zh-CN/how-claude-code-works.md)：循环、工具以及启动时加载的内容
570* [扩展 Claude Code](https://code.claude.com/docs/zh-CN/features-overview.md)：skills、hooks、MCP、subagents 和 plugins629* [探索上下文窗口](https://code.claude.com/docs/zh-CN/context-window.md)：会话中哪些内容占用空间以及何时加载
571* [常见工作流](https://code.claude.com/docs/zh-CN/common-workflows.md)：调试、测试、PR 等的分步配方630* [扩展 Claude Code](https://code.claude.com/docs/zh-CN/features-overview.md)：在 skill、hook、MCP、子代理和插件之间进行选择
572* [CLAUDE.md](https://code.claude.com/docs/zh-CN/memory.md)：存储项目约定和持久 context631* [选择权限模式](https://code.claude.com/docs/zh-CN/permission-modes.md)和[配置权限](https://code.claude.com/docs/zh-CN/permissions.md)
632* [有效管理成本](https://code.claude.com/docs/zh-CN/costs.md)
633* [以编程方式运行 Claude Code](https://code.claude.com/docs/zh-CN/headless.md)和[使用云端定时任务自动化工作](https://code.claude.com/docs/zh-CN/routines.md)
634* 面向团队负责人和管理员：[为您的组织设置 Claude Code](https://code.claude.com/docs/zh-CN/admin-setup.md)
