6 6
7> 使用 Claude Code 探索代码库、修复错误、重构、测试和其他日常任务的分步指南。7> 使用 Claude Code 探索代码库、修复错误、重构、测试和其他日常任务的分步指南。
8 8
9本页涵盖日常开发的实用工作流程：探索陌生代码、调试、重构、编写测试、创建 PR 和管理会话。每个部分都包含示例提示，您可以根据自己的项目进行调整。有关更高级的模式和提示，请参阅[最佳实践](/zh-CN/best-practices)。9本页收集了日常开发的简短工作流程。有关提示和上下文管理的更高级指导，请参阅[最佳实践](/zh-CN/best-practices)。
10 10
11## 理解新的代码库11本页涵盖：
12 12
13### 快速获取代码库概览13* [提示工作流程](#prompt-recipes)，用于探索代码、修复错误、重构、测试、PR 和文档
14* [恢复以前的对话](#resume-previous-conversations)，以便任务可以跨越多个会话
15* [使用 worktrees 运行并行会话](#run-parallel-sessions-with-worktrees)，以便并发编辑不会冲突
16* [编辑前规划](#plan-before-editing)，以在更改接触磁盘前审查更改
17* [将研究委派给 subagents](#delegate-research-to-subagents)，以保持主上下文清洁
18* [将 Claude 管道输入脚本](#pipe-claude-into-scripts)，用于 CI 和批处理
19
20## 提示工作流程
21
22这些是日常任务的提示模式，如探索陌生代码、调试、重构、编写测试和创建 PR。每个都可以在任何 Claude Code 界面中工作；根据您的项目调整措辞。
23
24### 理解新的代码库
25
26#### 快速获取代码库概览
14 27
15假设您刚加入一个新项目，需要快速了解其结构。28假设您刚加入一个新项目，需要快速了解其结构。
16 29
56 * 请求项目特定术语的词汇表69 * 请求项目特定术语的词汇表
57</Tip>70</Tip>
58 71
59### 查找相关代码72#### 查找相关代码
60 73
61假设您需要定位与特定功能相关的代码。74假设您需要定位与特定功能相关的代码。
62 75
90 103
91***104***
92 105
93## 高效修复错误106### 高效修复错误
94 107
95假设您遇到了错误消息，需要找到并修复其来源。108假设您遇到了错误消息，需要找到并修复其来源。
96 109
124 137
125***138***
126 139
127## 重构代码140### 重构代码
128 141
129假设您需要更新旧代码以使用现代模式和实践。142假设您需要更新旧代码以使用现代模式和实践。
130 143
164 177
165***178***
166 179
167## 使用专门的 subagents180### 使用测试
168
169假设您想使用专门的 AI subagents 来更有效地处理特定任务。
170
171<Steps>
172 <Step title="查看可用的 subagents">
173 ```text theme={null}
174 /agents
175 ```
176
177 这显示所有可用的 subagents 并让您创建新的。
178 </Step>
179
180 <Step title="自动使用 subagents">
181 Claude Code 自动将适当的任务委派给专门的 subagents：
182
183 ```text theme={null}
184 review my recent code changes for security issues
185 ```
186
187 ```text theme={null}
188 run all tests and fix any failures
189 ```
190 </Step>
191
192 <Step title="明确请求特定的 subagents">
193 ```text theme={null}
194 use the code-reviewer subagent to check the auth module
195 ```
196
197 ```text theme={null}
198 have the debugger subagent investigate why users can't log in
199 ```
200 </Step>
201
202 <Step title="为您的工作流程创建自定义 subagents">
203 ```text theme={null}
204 /agents
205 ```
206
207 然后选择"Create New subagent"并按照提示定义：
208
209 * 描述 subagent 目的的唯一标识符（例如，`code-reviewer`、`api-designer`）。
210 * Claude 何时应该使用此代理
211 * 它可以访问哪些工具
212 * 描述代理角色和行为的系统提示
213 </Step>
214</Steps>
215
216<Tip>
217 提示：
218
219 * 在 `.claude/agents/` 中创建项目特定的 subagents 以供团队共享
220 * 使用描述性的 `description` 字段来启用自动委派
221 * 限制工具访问权限为每个 subagent 实际需要的内容
222 * 查看[subagents 文档](/zh-CN/sub-agents)了解详细示例
223</Tip>
224
225***
226
227## 使用 Plan Mode 进行安全的代码分析
228
229Plan Mode 指示 Claude 通过使用只读操作分析代码库来创建计划，非常适合探索代码库、规划复杂更改或安全地审查代码。在 Plan Mode 中，Claude 使用 [`AskUserQuestion`](/zh-CN/tools-reference) 在提出计划之前收集需求并澄清您的目标。
230
231### 何时使用 Plan Mode
232
233* **多步骤实现**：当您的功能需要对许多文件进行编辑时
234* **代码探索**：当您想在更改任何内容之前彻底研究代码库时
235* **交互式开发**：当您想与 Claude 迭代方向时
236
237### 如何使用 Plan Mode
238
239**在会话期间打开 Plan Mode**
240
241您可以在会话期间使用 **Shift+Tab** 循环切换权限模式来切换到 Plan Mode。
242
243如果您处于 Normal Mode，**Shift+Tab** 首先切换到 Auto-Accept Mode，在终端底部显示 `⏵⏵ accept edits on`。随后的 **Shift+Tab** 将切换到 Plan Mode，显示 `⏸ plan mode on`。
244
245**在 Plan Mode 中启动新会话**
246
247要在 Plan Mode 中启动新会话，请使用 `--permission-mode plan` 标志：
248
249```bash theme={null}
250claude --permission-mode plan
251```
252
253**在 Plan Mode 中运行"无头"查询**
254
255您也可以使用 `-p` 直接在 Plan Mode 中运行查询（即在["无头模式"](/zh-CN/headless)中）：
256
257```bash theme={null}
258claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"
259```
260
261### 示例：规划复杂的重构
262
263```bash theme={null}
264claude --permission-mode plan
265```
266
267```text theme={null}
268I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.
269```
270
271Claude 分析当前实现并创建全面的计划。通过后续问题进行细化：
272
273```text theme={null}
274What about backward compatibility?
275```
276
277```text theme={null}
278How should we handle database migration?
279```
280
281<Tip>按 `Ctrl+G` 在默认文本编辑器中打开计划，您可以在 Claude 继续之前直接编辑它。</Tip>
282
283当您接受计划时，Claude 会自动从计划内容为会话命名。该名称显示在提示栏和会话选择器中。如果您已经使用 `--name` 或 `/rename` 设置了名称，接受计划不会覆盖它。
284
285### 将 Plan Mode 配置为默认值
286
287```json theme={null}
288// .claude/settings.json
289{
290 "permissions": {
291 "defaultMode": "plan"
292 }
293}
294```
295
296有关更多配置选项，请参阅[设置文档](/zh-CN/settings#available-settings)。
297
298***
299
300## 使用测试
301 181
302假设您需要为未覆盖的代码添加测试。182假设您需要为未覆盖的代码添加测试。
303 183
333 213
334***214***
335 215
336## 创建拉取请求216### 创建拉取请求
337 217
338您可以通过直接要求 Claude 创建拉取请求（"create a pr for my changes"），或逐步指导 Claude：218您可以通过直接要求 Claude 创建拉取请求（"create a pr for my changes"），或逐步指导 Claude：
339 219
357 </Step>237 </Step>
358</Steps>238</Steps>
359 239
360当您使用 `gh pr create` 创建 PR 时，会话会自动链接到该 PR。您可以稍后使用 `claude --from-pr <number>` 恢复它。240当您使用 `gh pr create` 创建 PR 时，会话会自动链接到该 PR。要稍后返回它，请运行 `claude --from-pr <number>` 或将 PR URL 粘贴到[`/resume` 选择器](/zh-CN/sessions#use-the-session-picker)搜索中。
361 241
362<Tip>242<Tip>
363 在提交前审查 Claude 生成的 PR，并要求 Claude 突出显示潜在的风险或注意事项。243 在提交前审查 Claude 生成的 PR，并要求 Claude 突出显示潜在的风险或注意事项。
364</Tip>244</Tip>
365 245
366## 处理文档246### 处理文档
367 247
368假设您需要为代码添加或更新文档。248假设您需要为代码添加或更新文档。
369 249
403 283
404***284***
405 285
406## 在笔记和非代码文件夹中工作286### 在笔记和非代码文件夹中工作
407 287
408Claude Code 可以在任何目录中工作。在笔记库、文档文件夹或任何 markdown 文件集合中运行它，以搜索、编辑和重新组织内容，就像处理代码一样。288Claude Code 可以在任何目录中工作。在笔记库、文档文件夹或任何 markdown 文件集合中运行它，以搜索、编辑和重新组织内容，就像处理代码一样。
409 289
411 291
412***292***
413 293
414## 使用图像294### 使用图像
415 295
416假设您需要在代码库中使用图像，并希望 Claude 帮助分析图像内容。296假设您需要在代码库中使用图像，并希望 Claude 帮助分析图像内容。
417 297
471 351
472***352***
473 353
474## 引用文件和目录354### 引用文件和目录
475 355
476使用 @ 快速包含文件或目录，无需等待 Claude 读取它们。356使用 @ 快速包含文件或目录，无需等待 Claude 读取它们。
477 357
512 392
513***393***
514 394
515## 使用扩展思考（Thinking Mode）395### 按计划运行 Claude
516
517[扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)默认启用，为 Claude 提供空间在响应前逐步推理复杂问题。此推理在详细模式中可见，您可以使用 `Ctrl+O` 切换。在扩展思考期间，进度提示会出现在指示器下方，显示 Claude 正在积极工作。
518
519此外，[支持努力级别的模型](/zh-CN/model-config#adjust-effort-level)使用自适应推理：不是固定的思考令牌预算，而是模型根据您的努力级别设置和手头的任务动态决定是否以及如何思考。自适应推理让 Claude 能够更快地响应常规提示，并为受益于深度思考的步骤保留更深层的思考。
520
521扩展思考对于复杂的架构决策、具有挑战性的错误、多步骤实现规划和评估不同方法之间的权衡特别有价值。
522
523<Note>
524 "think"、"think hard" 和 "think more" 等短语被解释为常规提示指令，不分配思考令牌。
525</Note>
526
527### 配置 Thinking Mode
528
529思考默认启用，但您可以调整或禁用它。
530
531| 范围 | 如何配置 | 详细信息 |
532| -------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
533| **努力级别** | 运行 `/effort`，在 `/model` 中调整，或设置 [`CLAUDE_CODE_EFFORT_LEVEL`](/zh-CN/env-vars) | 控制[支持的模型](/zh-CN/model-config#adjust-effort-level)上的思考深度 |
534| **`ultrathink` 关键字** | 在提示中的任何地方包含 "ultrathink" | 添加上下文内指令，告诉模型在该轮进行更多推理。不改变努力级别本身；有关详细信息，请参阅[调整努力级别](/zh-CN/model-config#adjust-effort-level) |
535| **切换快捷键** | 按 `Option+T`（macOS）或 `Alt+T`（Windows/Linux） | 为当前会话切换思考开/关（所有模型）。可能需要[终端配置](/zh-CN/terminal-config)来启用 Option 键快捷键 |
536| **全局默认值** | 使用 `/config` 切换 Thinking Mode | 在所有项目中设置默认值（所有模型）。<br />保存为 `~/.claude/settings.json` 中的 `alwaysThinkingEnabled` |
537| **限制令牌预算** | 设置 [`MAX_THINKING_TOKENS`](/zh-CN/env-vars) 环境变量 | 将思考预算限制为特定数量的令牌。在具有自适应推理的模型上，仅当设置为 `0` 时才适用，除非禁用自适应推理。示例：`export MAX_THINKING_TOKENS=10000` |
538
539要查看 Claude 的思考过程，按 `Ctrl+O` 切换详细模式，并查看显示为灰色斜体文本的内部推理。
540
541### 扩展思考如何工作
542
543扩展思考控制 Claude 在响应前执行多少内部推理。更多思考提供更多空间来探索解决方案、分析边界情况和自我纠正错误。
544
545在[支持努力级别的模型](/zh-CN/model-config#adjust-effort-level)上，思考使用自适应推理：模型根据您选择的努力级别动态分配思考令牌。这是调整速度和推理深度之间权衡的推荐方式。如果您希望 Claude 比您的努力级别通常会产生的更多或更少地思考，您也可以直接在提示中或在 `CLAUDE.md` 中说明。
546
547对于较旧的模型，思考使用从您的输出分配中提取的固定令牌预算。预算因模型而异；有关详细信息，请参阅 [`MAX_THINKING_TOKENS`](/zh-CN/env-vars)。您可以使用该环境变量限制预算，或通过 `/config` 或 `Option+T`/`Alt+T` 切换完全禁用思考。
548
549在具有自适应推理的模型上，`MAX_THINKING_TOKENS` 仅在设置为 `0` 以禁用思考时适用，或当 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 将模型恢复为固定预算时。`CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 仅适用于 Opus 4.6 和 Sonnet 4.6。Opus 4.7 始终使用自适应推理，不支持固定思考预算。请参阅[环境变量](/zh-CN/env-vars)。
550
551<Warning>
552 您需要为所有使用的思考令牌付费，即使思考摘要被编辑。在交互模式中，思考默认显示为折叠的存根。在 `settings.json` 中设置 `showThinkingSummaries: true` 以显示完整摘要。
553</Warning>
554
555***
556
557## 恢复以前的对话
558
559启动 Claude Code 时，您可以恢复以前的会话：
560
561* `claude --continue` 继续当前目录中最近的对话
562* `claude --resume` 打开对话选择器或按名称恢复
563* `claude --from-pr 123` 恢复链接到特定拉取请求的会话
564
565从活跃会话内，使用 `/resume` 切换到不同的对话。
566
567当选定的会话足够旧且足够大，以至于重新阅读它会消耗您使用限额的大部分时，`--resume`、`--continue` 和 `/resume` 会提供从摘要恢复而不是加载完整记录的选项。此提示在 Amazon Bedrock、Google Cloud Vertex AI 或 Microsoft Foundry 上不可用。
568
569会话按项目目录存储。默认情况下，`/resume` 选择器显示来自当前 worktree 的交互式会话，带有键盘快捷键来扩展列表到其他 worktrees 或项目、搜索、预览和重命名。有关完整的快捷键参考，请参阅下面的[使用会话选择器](#use-the-session-picker)。
570
571当您从同一存储库的另一个 worktree 选择会话时，Claude Code 直接恢复它，无需您首先切换目录。从不相关项目选择会话会将 `cd` 和恢复命令复制到您的剪贴板。
572
573按名称恢复在当前存储库及其 worktrees 中解析。`claude --resume <name>` 和 `/resume <name>` 都查找精确匹配并直接恢复它，即使会话位于不同的 worktree 中。
574
575当名称不明确时，`claude --resume <name>` 打开选择器，名称预填充为搜索词。`/resume <name>` 从活跃会话内报告错误，因此运行 `/resume` 不带参数来打开选择器并选择。
576
577由 `claude -p` 或 SDK 调用创建的会话不会出现在选择器中，但您仍然可以通过将其会话 ID 直接传递给 `claude --resume <session-id>` 来恢复它。
578
579### 命名您的会话
580
581给会话起描述性名称以便稍后找到它们。这是在处理多个任务或功能时的最佳实践。
582
583<Steps>
584 <Step title="命名会话">
585 在启动时使用 `-n` 命名会话：
586
587 ```bash theme={null}
588 claude -n auth-refactor
589 ```
590
591 或在会话期间使用 `/rename`，这也会在提示栏上显示名称：
592
593 ```text theme={null}
594 /rename auth-refactor
595 ```
596
597 您也可以从选择器重命名任何会话：运行 `/resume`，导航到会话，然后按 `Ctrl+R`。
598 </Step>
599
600 <Step title="稍后按名称恢复">
601 从命令行：
602
603 ```bash theme={null}
604 claude --resume auth-refactor
605 ```
606
607 或从活跃会话内：
608
609 ```text theme={null}
610 /resume auth-refactor
611 ```
612 </Step>
613</Steps>
614
615### 使用会话选择器
616
617`/resume` 命令（或 `claude --resume` 不带参数）打开具有以下功能的交互式会话选择器：
618
619**选择器中的键盘快捷键：**
620
621| 快捷键 | 操作 |
622| :------------------------ | :------------------------------------------------------------- |
623| `↑` / `↓` | 在会话之间导航 |
624| `→` / `←` | 展开或折叠分组的会话 |
625| `Enter` | 选择并恢复突出显示的会话 |
626| `Space` | 预览会话内容。`Ctrl+V` 也适用于不将其捕获为粘贴的终端 |
627| `Ctrl+R` | 重命名突出显示的会话 |
628| `/` 或任何可打印字符（除 `Space` 外） | 进入搜索模式并过滤会话 |
629| `Ctrl+A` | 显示此机器上所有项目的会话。再次按下以恢复当前存储库 |
630| `Ctrl+W` | 显示当前存储库所有 worktrees 的会话。再次按下以恢复当前 worktree。仅在多 worktree 存储库中显示 |
631| `Ctrl+B` | 过滤到来自当前 git 分支的会话。再次按下以显示所有分支的会话 |
632| `Esc` | 退出选择器或搜索模式 |
633
634**会话组织：**
635
636选择器显示带有有用元数据的会话：
637
638* 会话名称（如果设置），否则对话摘要或第一个用户提示
639* 自上次活动以来经过的时间
640* 消息计数
641* Git 分支（如果适用）
642* 项目路径，在使用 `Ctrl+A` 扩展到所有项目后显示
643
644分叉的会话（使用 `/branch`、`/rewind` 或 `--fork-session` 创建）在其根会话下分组，使查找相关对话更容易。
645
646<Tip>
647 提示：
648
649 * **尽早命名会话**：在开始处理不同任务时使用 `/rename`——稍后找到"payment-integration"比"explain this function"容易得多
650 * 使用 `--continue` 快速访问当前目录中最近的对话
651 * 当您知道需要哪个会话时使用 `--resume session-name`
652 * 当您需要浏览和选择时使用 `--resume`（不带名称）
653 * 对于脚本，使用 `claude --continue --print "prompt"` 以非交互模式恢复
654 * 在选择器中按 `Space` 在恢复前预览会话
655 * 恢复的对话以与原始对话相同的模型和配置开始
656
657 工作原理：
658
659 1. **对话存储**：所有对话都自动保存在本地，包含完整的消息历史
660 2. **消息反序列化**：恢复时，整个消息历史被恢复以保持上下文
661 3. **工具状态**：来自以前对话的工具使用和结果被保留
662 4. **上下文恢复**：对话以所有以前的上下文完整恢复
663</Tip>
664
665***
666
667## 使用 Git worktrees 运行并行 Claude Code 会话
668
669当同时处理多个任务时，您需要每个 Claude 会话都有自己的代码库副本，以便更改不会冲突。Git worktrees 通过创建单独的工作目录来解决这个问题，每个目录都有自己的文件和分支，同时共享相同的存储库历史和远程连接。这意味着您可以让 Claude 在一个 worktree 中处理功能，同时在另一个 worktree 中修复错误，而不会相互干扰。
670
671使用 `--worktree`（`-w`）标志创建隔离的 worktree 并在其中启动 Claude。您传递的值成为 worktree 目录名称和分支名称：
672
673```bash theme={null}
674# 在名为 "feature-auth" 的 worktree 中启动 Claude
675# 创建 .claude/worktrees/feature-auth/ 和新分支
676claude --worktree feature-auth
677
678# 在单独的 worktree 中启动另一个会话
679claude --worktree bugfix-123
680```
681
682如果您省略名称，Claude 会自动生成一个随机名称：
683
684```bash theme={null}
685# 自动生成名称如 "bright-running-fox"
686claude --worktree
687```
688
689Worktrees 在 `<repo>/.claude/worktrees/<name>` 创建，并从默认远程分支分支。worktree 分支命名为 `worktree-<name>`。
690
691基础分支不能通过 Claude Code 标志或设置进行配置。`origin/HEAD` 是存储在您本地 `.git` 目录中的引用，Git 在您克隆时设置一次。如果存储库的默认分支稍后在 GitHub 或 GitLab 上更改，您的本地 `origin/HEAD` 会继续指向旧的，worktrees 将从那里分支。要重新同步您的本地引用与远程当前认为的默认值：
692
693```bash theme={null}
694git remote set-head origin -a
695```
696
697这是一个标准的 Git 命令，仅更新您的本地 `.git` 目录。远程服务器上没有任何更改。如果您希望 worktrees 基于特定分支而不是远程的默认值，请使用 `git remote set-head origin your-branch-name` 显式设置它。
698
699为了完全控制 worktrees 的创建方式，包括为每次调用选择不同的基础，配置 [WorktreeCreate hook](/zh-CN/hooks#worktreecreate)。该 hook 完全替换 Claude Code 的默认 `git worktree` 逻辑，因此您可以从您需要的任何 ref 获取和分支。
700
701您也可以在会话期间要求 Claude "work in a worktree" 或 "start a worktree"，它会自动创建一个。
702
703### Subagent worktrees
704
705Subagents 也可以使用 worktree 隔离来并行工作而不会冲突。要求 Claude "use worktrees for your agents" 或在[自定义 subagent](/zh-CN/sub-agents#supported-frontmatter-fields) 中通过在代理的 frontmatter 中添加 `isolation: worktree` 来配置它。每个 subagent 获得自己的 worktree，当 subagent 完成而没有更改时自动清理。
706
707### Worktree 清理
708
709当您退出 worktree 会话时，Claude 根据您是否进行了更改来处理清理：
710
711* **无更改**：worktree 及其分支自动删除
712* **存在更改或提交**：Claude 提示您保留或删除 worktree。保留会保留目录和分支，以便您稍后可以返回。删除会删除 worktree 目录及其分支，丢弃所有未提交的更改和提交
713
714Subagent worktrees 由崩溃或中断的并行运行孤立的，在启动时会自动删除，一旦它们超过您的 [`cleanupPeriodDays`](/zh-CN/settings#available-settings) 设置，前提是它们没有未提交的更改、没有未跟踪的文件和没有未推送的提交。使用 `--worktree` 创建的 Worktrees 永远不会被此扫描删除。
715
716要在 Claude 会话外清理 worktrees，请使用[手动 worktree 管理](#manage-worktrees-manually)。
717
718<Tip>
719 将 `.claude/worktrees/` 添加到您的 `.gitignore` 以防止 worktree 内容在主存储库中显示为未跟踪的文件。
720</Tip>
721
722### 复制 gitignored 文件到 worktrees
723
724Git worktrees 是新鲜检出，所以它们不包括来自主存储库的未跟踪文件，如 `.env` 或 `.env.local`。要在 Claude 创建 worktree 时自动复制这些文件，请将 `.worktreeinclude` 文件添加到项目根目录。
725
726该文件使用 `.gitignore` 语法列出要复制的文件。只有匹配模式且也被 gitignored 的文件才会被复制，因此跟踪的文件永远不会被复制。
727
728```text .worktreeinclude theme={null}
729.env
730.env.local
731config/secrets.json
732```
733
734这适用于使用 `--worktree` 创建的 worktrees、subagent worktrees 和[桌面应用](/zh-CN/desktop#work-in-parallel-with-sessions)中的并行会话。
735
736### 手动管理 worktrees
737
738为了更好地控制 worktree 位置和分支配置，直接使用 Git 创建 worktrees。当您需要检出特定的现有分支或将 worktree 放在存储库外时，这很有用。
739
740```bash theme={null}
741# 使用新分支创建 worktree
742git worktree add ../project-feature-a -b feature-a
743
744# 使用现有分支创建 worktree
745git worktree add ../project-bugfix bugfix-123
746
747# 在 worktree 中启动 Claude
748cd ../project-feature-a && claude
749
750# 完成时清理
751git worktree list
752git worktree remove ../project-feature-a
753```
754
755在[官方 Git worktree 文档](https://git-scm.com/docs/git-worktree)中了解更多。
756
757<Tip>
758 记住根据您的项目设置在每个新 worktree 中初始化您的开发环境。根据您的堆栈，这可能包括运行依赖项安装（`npm install`、`yarn`）、设置虚拟环境或遵循您的项目标准设置过程。
759</Tip>
760
761### 非 git 版本控制
762
763Worktree 隔离默认使用 git。对于其他版本控制系统如 SVN、Perforce 或 Mercurial，配置 [WorktreeCreate 和 WorktreeRemove hooks](/zh-CN/hooks#worktreecreate) 以提供自定义 worktree 创建和清理逻辑。配置后，这些 hooks 在您使用 `--worktree` 时替换默认的 git 行为，因此[`.worktreeinclude`](#copy-gitignored-files-to-worktrees) 不被处理。在您的 hook 脚本中复制任何本地配置文件。
764
765对于具有共享任务和消息的并行会话的自动协调，请参阅[代理团队](/zh-CN/agent-teams)。
766
767***
768
769## 在 Claude 需要您的注意时获得通知
770
771当您启动长时间运行的任务并切换到另一个窗口时，您可以设置桌面通知，以便在 Claude 完成或需要您的输入时了解。这使用 `Notification` [hook 事件](/zh-CN/hooks-guide#get-notified-when-claude-needs-input)，每当 Claude 等待权限、空闲并准备好新提示或完成身份验证时触发。
772
773<Steps>
774 <Step title="将 hook 添加到您的设置">
775 打开 `~/.claude/settings.json` 并添加一个 `Notification` hook，该 hook 调用您的平台的本机通知命令：
776
777 <Tabs>
778 <Tab title="macOS">
779 ```json theme={null}
780 {
781 "hooks": {
782 "Notification": [
783 {
784 "matcher": "",
785 "hooks": [
786 {
787 "type": "command",
788 "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
789 }
790 ]
791 }
792 ]
793 }
794 }
795 ```
796 </Tab>
797
798 <Tab title="Linux">
799 ```json theme={null}
800 {
801 "hooks": {
802 "Notification": [
803 {
804 "matcher": "",
805 "hooks": [
806 {
807 "type": "command",
808 "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
809 }
810 ]
811 }
812 ]
813 }
814 }
815 ```
816 </Tab>
817
818 <Tab title="Windows">
819 ```json theme={null}
820 {
821 "hooks": {
822 "Notification": [
823 {
824 "matcher": "",
825 "hooks": [
826 {
827 "type": "command",
828 "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
829 }
830 ]
831 }
832 ]
833 }
834 }
835 ```
836 </Tab>
837 </Tabs>
838
839 如果您的设置文件已经有 `hooks` 键，请将 `Notification` 条目合并到其中，而不是覆盖。您也可以通过在 CLI 中描述您想要的内容来要求 Claude 为您编写 hook。
840 </Step>
841
842 <Step title="可选地缩小匹配器范围">
843 默认情况下，hook 在所有通知类型上触发。要仅针对特定事件触发，请将 `matcher` 字段设置为以下值之一：
844
845 | 匹配器 | 触发时机 |
846 | :--------------------- | :------------------ |
847 | `permission_prompt` | Claude 需要您批准工具使用 |
848 | `idle_prompt` | Claude 完成并等待您的下一个提示 |
849 | `auth_success` | 身份验证完成 |
850 | `elicitation_dialog` | MCP 服务器打开一个引出表单 |
851 | `elicitation_complete` | MCP 引出表单被提交或关闭 |
852 | `elicitation_response` | MCP 引出响应被发送回服务器 |
853 </Step>
854
855 <Step title="验证 hook">
856 输入 `/hooks` 并选择 `Notification` 以确认 hook 出现。选择它显示将运行的命令。要端到端测试它，要求 Claude 运行需要权限的命令并切换离开终端，或要求 Claude 直接触发通知。
857 </Step>
858</Steps>
859
860有关完整的事件架构和通知类型，请参阅[通知参考](/zh-CN/hooks#notification)。
861
862***
863
864## 将 Claude 用作 unix 风格的实用程序
865
866### 将 Claude 添加到您的验证过程
867
868假设您想将 Claude Code 用作 linter 或代码审查工具。
869
870**将 Claude 添加到您的构建脚本：**
871
872```json theme={null}
873// package.json
874{
875 ...
876 "scripts": {
877 ...
878 "lint:claude": "claude -p 'you are a linter. please look at the changes vs. main and report any issues related to typos. report the filename and line number on one line, and a description of the issue on the second line. do not return any other text.'"
879 }
880}
881```
882
883<Tip>
884 提示：
885
886 * 在您的 CI/CD 管道中使用 Claude 进行自动代码审查
887 * 自定义提示以检查与您的项目相关的特定问题
888 * 考虑为不同类型的验证创建多个脚本
889</Tip>
890
891### 管道进入、管道输出
892
893假设您想将数据管道输入 Claude，并获得结构化格式的数据。
894
895**通过 Claude 管道数据：**
896
897```bash theme={null}
898cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt
899```
900
901<Tip>
902 提示：
903
904 * 使用管道将 Claude 集成到现有的 shell 脚本中
905 * 与其他 Unix 工具结合以实现强大的工作流程
906 * 考虑使用 `--output-format` 获得结构化输出
907</Tip>
908
909### 控制输出格式
910
911假设您需要 Claude 的输出采用特定格式，特别是在将 Claude Code 集成到脚本或其他工具时。
912
913<Steps>
914 <Step title="使用文本格式（默认）">
915 ```bash theme={null}
916 cat data.txt | claude -p 'summarize this data' --output-format text > summary.txt
917 ```
918
919 这仅输出 Claude 的纯文本响应（默认行为）。
920 </Step>
921
922 <Step title="使用 JSON 格式">
923 ```bash theme={null}
924 cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json
925 ```
926
927 这输出包含元数据（包括成本和持续时间）的消息的 JSON 数组。
928 </Step>
929
930 <Step title="使用流式 JSON 格式">
931 ```bash theme={null}
932 cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json
933 ```
934
935 这在 Claude 处理请求时实时输出一系列 JSON 对象。每条消息都是有效的 JSON 对象，但如果连接，整个输出不是有效的 JSON。
936 </Step>
937</Steps>
938
939<Tip>
940 提示：
941
942 * 对于简单集成（您只需要 Claude 的响应），使用 `--output-format text`
943 * 当您需要完整的对话日志时使用 `--output-format json`
944 * 对于每个对话轮次的实时输出，使用 `--output-format stream-json`
945</Tip>
946
947***
948
949## 按计划运行 Claude
950 396
951假设您想让 Claude 自动定期处理任务，如每天早上审查开放的 PR、每周审计依赖项或在夜间检查 CI 失败。397假设您想让 Claude 自动定期处理任务，如每天早上审查开放的 PR、每周审计依赖项或在夜间检查 CI 失败。
952 398
965 411
966***412***
967 413
968## 询问 Claude 关于其功能414### 询问 Claude 关于其功能
969 415
970Claude 内置访问其文档，可以回答关于其自身功能和限制的问题。416Claude 内置访问其文档，可以回答关于其自身功能和限制的问题。
971 417
972### 示例问题418#### 示例问题
973 419
974```text theme={null}420```text theme={null}
975can Claude Code create pull requests?421can Claude Code create pull requests?
1009 455
1010***456***
1011 457
458## 恢复以前的对话
459
460当任务跨越多个会话时，从您离开的地方继续，而不是重新解释上下文。Claude Code 在本地保存每个对话。
461
462```bash theme={null}
463claude --continue
464```
465
466这会恢复当前目录中最近的会话；如果还没有，它会打印 `No conversation found to continue` 并退出。使用 `claude --resume` 从列表中选择，或从运行中的会话内使用 `/resume`。有关命名、分支和完整选择器参考，请参阅[管理会话](/zh-CN/sessions)。
467
468## 使用 worktrees 运行并行会话
469
470在一个终端中处理功能，同时 Claude 在另一个终端中修复错误，而不会编辑冲突。每个 worktree 是其自己分支上的单独检出。
471
472```bash theme={null}
473claude --worktree feature-auth
474```
475
476在第二个终端中使用不同的名称运行相同的命令以启动隔离的并行会话。有关清理、`.worktreeinclude` 和非 git VCS 支持，请参阅 [Worktrees](/zh-CN/worktrees)。要从一个屏幕而不是单独的终端监视并行会话，请参阅[后台代理](/zh-CN/agent-view)。
477
478## 编辑前规划
479
480对于您想在接触磁盘前审查的更改，切换到 plan mode。Claude 读取文件并提出计划，但在您批准前不进行任何编辑。
481
482```bash theme={null}
483claude --permission-mode plan
484```
485
486您也可以在会话中按 `Shift+Tab` 切换到 plan mode。有关批准流程和在文本编辑器中编辑计划，请参阅 [Plan Mode](/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)。
487
488## 将研究委派给 subagents
489
490探索大型代码库会用文件读取填充您的上下文。委派探索，以便只有发现结果返回。
491
492```text theme={null}
493use a subagent to investigate how our auth system handles token refresh
494```
495
496subagent 在其自己的上下文窗口中读取文件并报告摘要。有关定义具有自己工具和提示的自定义代理，请参阅 [Subagents](/zh-CN/sub-agents)。
497
498## 将 Claude 管道输入脚本
499
500以非交互方式运行 Claude 用于 CI、预提交钩子或批处理。stdin 和 stdout 像任何 Unix 工具一样工作。
501
502```bash theme={null}
503git log --oneline -20 | claude -p "summarize these recent commits"
504```
505
506有关输出格式、权限标志和扇出模式，请参阅[非交互模式](/zh-CN/headless)。
507
1012## 后续步骤508## 后续步骤
1013 509
1014<CardGroup cols={2}>510<CardGroup cols={2}>
1016 充分利用 Claude Code 的模式512 充分利用 Claude Code 的模式
1017 </Card>513 </Card>
1018 514
1019 <Card title="Claude Code 如何工作" icon="gear" href="/zh-CN/how-claude-code-works">515 <Card title="管理会话" icon="rotate-left" href="/zh-CN/sessions">
1020 理解代理循环和上下文管理516 恢复、命名和分支对话
1021 </Card>517 </Card>
1022 518
1023 <Card title="扩展 Claude Code" icon="puzzle-piece" href="/zh-CN/features-overview">519 <Card title="Worktrees" icon="code-branch" href="/zh-CN/worktrees">
1024 添加 skills、hooks、MCP、subagents 和插件520 运行隔离的并行会话
1025 </Card>521 </Card>
1026 522
1027 <Card title="参考实现" icon="code" href="https://github.com/anthropics/claude-code/tree/main/.devcontainer">523 <Card title="扩展 Claude Code" icon="puzzle-piece" href="/zh-CN/features-overview">
1028 克隆开发容器参考实现524 添加 skills、hooks、MCP、subagents 和插件
1029 </Card>525 </Card>
1030</CardGroup>526</CardGroup>
