claude-code/docs/outline-output/user/06-agents-plan-tasks.md

第六章：让 Claude 帮你跑大任务 -- 子代理、Plan 模式、Task 系统

当任务太大、一步做不完时，如何让 Claude 自己拆分、规划和并行推进。

什么时候该"升级"任务处理方式

日常对话中，你给 Claude 一条指令，它执行一次就完成了。但有些任务天然不适合一口气干完：代码库迁移涉及几十个文件、排查 bug 需要同时在多处搜索、重构需要先理清依赖再动手。在这些场景下，三个工具能帮你把大任务拆小：子代理（Agent） 处理独立的子任务，Plan 模式 先想清楚再动手，Task 系统 跟踪进度和依赖。

一个简单的判断标准：如果你发现自己反复对 Claude 说"再看看那个文件"、"顺便改一下这个"，说明这个任务已经需要拆分了。

子代理：让 Claude 派一个"分身"去干活

Claude Code 有一个 Agent 工具，允许 Claude 在对话过程中派生出子代理来处理子任务。子代理有自己的上下文和工具集，完成后会把结果汇报给主对话。你不需要手动启动子代理 -- 当 Claude 判断某个子任务适合独立处理时，它会自动使用 Agent 工具。

内置的子代理类型

Claude Code 内置了几种专门化的子代理，各有分工：

• general-purpose -- 通用子代理，能使用全部工具。当你让 Claude 做一个需要多步骤研究或跨文件分析的任务时，它可能会派这个子代理去执行。
• Explore -- 只读搜索专家，不能修改任何文件。擅长用 Glob、Grep、FileRead 快速在代码库中定位文件和关键词。当你问"这个功能在代码里怎么实现的"时，Explore 子代理会并行搜索多个路径然后汇总结果。
• Plan -- 架构规划师，同样只读。它会深入阅读代码、理解现有架构，然后输出一份包含步骤和关键文件的实施方案。

你不需要记住这些类型名。Claude 会根据你的问题自动选择合适的子代理。

子代理是怎么工作的

当你给 Claude 一个复杂指令时，它可能会这样处理：

你: 把 src/utils/ 下所有用到 deprecatedFunction 的地方重构掉

Claude: [使用 Agent 工具，派出一个 Explore 子代理搜索所有引用]

  > Agent (Explore): 正在搜索 src/utils/ 下的 deprecatedFunction 引用...

  [子代理完成，返回搜索结果]

Claude: 找到了 12 处引用，分布在 5 个文件中。让我逐一替换...

子代理运行时，你会看到一个带颜色的进度提示，标明子代理的类型和当前状态。每个子代理的输出会作为一条消息出现在对话中，Claude 主线程会基于这些结果继续工作。

子代理之间也可以形成层级：主对话可以派子代理，子代理在复杂场景下还能继续派更小的子代理（取决于配置和 feature flag）。

关于并行子代理

当你使用一些 Skill（如 ultra-batch 或 dispatching-parallel-agents）时，可以显式要求 Claude 同时派发多个子代理并行处理不同子任务。这在需要同时探索多个代码路径、或同时修改多个独立文件时特别高效。

你: 用 3 个子代理同时查一下 authentication、authorization 和 session 管理的实现

Claude: [同时派出 3 个 Explore 子代理，并行搜索]
  > Agent #1 (Explore): 搜索 authentication 相关文件...
  > Agent #2 (Explore): 搜索 authorization 相关文件...
  > Agent #3 (Explore): 搜索 session 管理相关文件...

  [三个子代理各自返回结果，Claude 汇总]

Task 系统：跟踪任务进度和依赖

Task 系统提供了一套完整的任务管理工具，让 Claude 能够像使用待办清单一样跟踪工作进度。这套工具包括 TaskCreate、TaskUpdate、TaskList 和 TaskGet。

任务是怎么创建的

Claude 会在拆分大任务时自动使用 TaskCreate 创建子任务。你也可以在对话中明确要求它创建任务清单：

你: 帮我把用户模块重构拆成任务清单

Claude: [使用 TaskCreate 创建任务]

  > Task #1 created: 提取用户验证逻辑到独立 service
  > Task #2 created: 重构用户数据模型，添加类型约束
  > Task #3 created: 更新 API 路由使用新的 service 层
  > Task #4 created: 编写单元测试覆盖新 service

每个任务包含标题（subject）、描述（description）和状态（pending / in_progress / completed）。创建任务时，Claude 还可以设置 activeForm（进行中时显示的活动描述，如"Running tests"），以及任意的 metadata 键值对。

任务状态流转

任务创建后默认是 pending 状态。Claude 会用 TaskUpdate 把任务标记为 in_progress（开始执行）、completed（完成）或 deleted（删除）。

你: 继续执行任务清单

Claude: [使用 TaskUpdate 更新状态]

  > Updated task #1 in_progress, status
  [开始执行第一个任务...]

  > Updated task #1 completed, status
  > Updated task #2 in_progress, status
  [继续下一个任务...]

用 TaskList 可以随时查看所有任务的当前状态：

#1 [in_progress] 提取用户验证逻辑到独立 service
#2 [pending] 重构用户数据模型，添加类型约束
#3 [pending] 更新 API 路由使用新的 service 层
#4 [pending] 编写单元测试覆盖新 service

TaskGet 则用于查看单个任务的完整详情，包括描述和依赖关系。

任务依赖

任务之间可以设置阻塞关系。如果任务 A 阻塞了任务 B（task B 被 task A blocked），那么在 A 完成之前，B 无法开始。Claude 在规划执行顺序时会参考这些依赖关系：

#1 [completed] 提取用户验证逻辑到独立 service
#2 [in_progress] 重构用户数据模型，添加类型约束
#3 [blocked by #2] 更新 API 路由使用新的 service 层
#4 [blocked by #3] 编写单元测试覆盖新 service

任务钩子

Task 系统支持 hooks 集成。你可以在 settings.json 中配置 hooks，让特定事件（如任务创建、任务完成）触发自定义逻辑。比如，当某个关键任务完成时自动运行测试套件。

Plan 模式：先想清楚再动手

Plan 模式是处理复杂任务的最佳实践。进入 Plan 模式后，Claude 会切换到只读状态：它可以搜索代码、阅读文件、分析架构，但不能修改任何文件。等方案设计完毕并获得你的批准后，才退出 Plan 模式开始实际编码。

进入 Plan 模式

有两种方式进入 Plan 模式：

方式一：用 /plan 命令

/plan 重构用户模块的数据层

这会启用 Plan 模式，并把你给出的描述作为规划目标。Claude 会在只读状态下探索代码库、设计实施方案。

方式二：让 Claude 自动进入

对于足够复杂的任务，Claude 会自动调用 EnterPlanMode 工具进入 Plan 模式。你不需要显式要求，但可以用 /plan 强制进入。

Plan 模式下发生了什么

进入 Plan 模式后，权限模式会切换为 plan。在这个模式下：

• Claude 只能使用只读工具（Read、Glob、Grep、Bash 的只读操作）
• 文件编辑工具（Edit、Write）被禁用
• Claude 会深入探索代码库，理解现有模式和架构
• Claude 可能会问你一些问题来澄清需求

Claude 会把规划结果写入一个计划文件。你可以随时用 /plan 查看当前计划，或用 /plan open 在你的默认编辑器中打开并手动修改计划内容。

退出 Plan 模式并开始执行

当 Claude 完成规划后，它会调用 ExitPlanMode 工具。这时你会看到一个审批对话框，显示完整的计划内容。你可以：

• 批准 -- Claude 立即开始按计划编码
• 编辑 -- 在编辑器中修改计划，然后批准修改后的版本
• 拒绝 -- 让 Claude 重新规划

批准后，权限模式会恢复到进入 Plan 模式之前的状态（通常是 default 或 auto），Claude 开始按计划执行。

VerifyPlanExecution：确认计划已正确执行

在较新的版本中，Claude 在退出 Plan 模式之前可能会调用 VerifyPlanExecution 工具，对计划的执行情况进行校验。它会检查：

• 计划中的所有步骤是否都已完成
• 测试是否通过
• 关键文件是否已正确创建或修改

如果某些步骤被跳过或失败了，验证结果中会包含说明。

Goal 命令：给 Claude 一个自主推进的目标

/goal 命令让你给 Claude 设定一个长期目标，然后 Claude 会自主地持续工作直到目标达成，而不是等你一轮一轮地下指令。

设置和查看目标

/goal 把所有 API 端点从 REST 迁移到 GraphQL

这会设定一个目标。Claude 会开始自主规划、拆分任务、执行修改，每完成一轮会自动继续下一轮。你可以随时查看目标状态：

/goal status

输出会显示目标描述、当前状态、已用 token 数量、活跃时间和已执行的轮次。

控制目标进度

/goal 支持几个子命令来控制执行：

• /goal pause -- 暂停自动继续
• /goal resume -- 从暂停恢复
• /goal continue -- 在达到最大轮次限制后重置计数器继续
• /goal complete -- 手动标记目标已完成
• /goal clear -- 清除当前目标

当 Claude 遇到无法自行解决的阻塞时，它会用 GoalTool 将目标标记为 blocked 并说明原因。连续 3 轮遇到同样的阻塞条件后，目标会被自动标记为阻塞状态，等待你介入。

Goal 与 Task 系统的配合

/goal 通常会与 Task 系统配合使用。Claude 设定目标后会自动创建任务清单，然后逐个执行。你可以在 /workflows 面板中同时看到目标和任务的状态。

Worktree 隔离：在独立分支里做实验

当你需要做一些可能有风险或需要独立验证的改动时，Claude 可以用 EnterWorktree 工具创建一个 git worktree -- 一个独立的工作目录，关联到一个新的 git 分支。

Claude 如何使用 Worktree

你不需要手动管理 worktree。当你告诉 Claude 做一些需要隔离的操作时，它可能会自动调用 EnterWorktree：

你: 试试把 ORM 从 Prisma 换成 Drizzle，先在一个独立分支上验证可行性

Claude 会创建一个 worktree，在新分支上做实验，完成后汇报结果。你的主工作目录完全不受影响。

Worktree 的生命周期

• 创建：EnterWorktree 创建 worktree 和关联分支，会话切换到 worktree 目录
• 退出 -- 保留：ExitWorktree(action: "keep") 保留 worktree 和分支，会话切回原目录
• 退出 -- 删除：ExitWorktree(action: "remove") 删除 worktree 和分支。如果有未提交的改动或未合并的 commit，Claude 会先列出它们，需要你确认并传入 discard_changes: true 才会执行删除

你也可以在启动 Claude 时直接指定 worktree 模式：

claude --tmux --worktree

这会自动创建一个 worktree 并在 tmux 会话中运行。

Coordinator 模式：多 Worker 协作

Coordinator 模式是一个高级特性（需要 COORDINATOR_MODE feature flag），把 Claude 变成一个任务调度器。启用后，Claude 只能使用 Agent（派发子任务）、SendMessage（给子代理发消息）和 TaskStop（停止子任务）三个工具，不再直接执行任何操作。

启用 Coordinator 模式

/coordinator

启用后，Claude 会变成一个编排者。你给它一个大任务，它会拆分成多个子任务，然后派发给不同的 worker 子代理并行执行：

你: 把这个 monorepo 的所有包从 CommonJS 迁移到 ESM

Claude (Coordinator): 我把这个任务拆成 5 个子任务，派发给 worker 执行...

  > Agent (worker #1): 迁移 packages/utils/ ...
  > Agent (worker #2): 迁移 packages/core/ ...
  > Agent (worker #3): 迁移 packages/api/ ...
  ...

  [Worker 完成后汇报结果，Coordinator 汇总]

再次输入 /coordinator 可以关闭 Coordinator 模式，恢复正常的工具使用。

Workflow 脚本：固化可重放的多步工作流

/workflows 命令打开一个监控面板，实时显示当前工作流的运行状态、各阶段进度和子代理活动。这个面板适合在 Claude 执行复杂多步任务时监控整体进展。

在面板中，你可以看到：

• 当前工作流的运行状态（running / paused / completed）
• 各阶段的进度
• 活跃的子代理列表及其状态
• 用键盘快捷键控制工作流（暂停、继续、取消）

/workflows

面板以终端 UI 形式展示，不阻塞主对话。

如何选择合适的方式

面对一个大任务，选择哪种方式取决于任务的性质：

场景	推荐方式
需要先理解代码再动手	Plan 模式
需要长时间自主推进	/goal
需要并行处理多个独立子任务	Agent 子代理 / Coordinator 模式
需要在隔离环境做实验	Worktree
需要跟踪多个子任务的进度	Task 系统
需要监控复杂工作流的执行	/workflows 面板

这些方式可以组合使用。比如，你可以先用 Plan 模式设计方案，然后 Claude 自动创建 Task 清单，再派子代理并行执行各任务，同时你在 /workflows 面板中监控进度。

下一步

• 想了解如何让 Claude 定时或后台执行任务，看 第七章：Daemon、Background Sessions、Schedule
• 想了解如何通过 Bridge 或 RCS 远程控制这些任务，看 第八章：跨机器与跨团队协作
• 想了解权限模式如何影响子代理和 Plan 模式的行为，看 第九章：省钱、提速、定制