Claude Code 子代理系统完全指南：Fork、Swarm 与 Coordinator 深度拆解
当 Claude 学会"生儿子"，编程的效率就彻底变了。
如果你用过 Claude Code，你可能已经习惯了让它帮你写代码、改 bug、跑测试。但你可能没有意识到，Claude Code 最强大的能力其实藏在"子代理"（Subagent）系统里------它能让一个 Claude 分身出多个 Claude，并行工作，各司其职。
本文从源码和设计理念出发，系统讲解 Claude Code 的子代理系统，重点拆解 Fork 模式 、Swarm（Agent Teams） 和 Coordinator Mode 三种多 Agent 协作方式，帮你理解这套系统到底解决了什么问题、怎么用、以及各自适合什么场景。
一、为什么要有多 Agent？------单 Agent 的瓶颈
先回答一个根本问题：为什么需要子代理？
单 Agent 模式下，Claude 一次只能想一件事、做一件事。面对复杂任务时，会面临几个致命瓶颈：
串行阻塞 。模型在做调研时，你什么都干不了，只能等。一个大型重构需要更新 40 个文件、每批后运行测试、验证有没有破坏什么------这些不是更难的问题，而是更宽的问题，需要同时做多件事的能力。
上下文污染。让同一个 Agent 既做调研又做实现又做验证，每一步都在消耗上下文窗口，相互干扰。
能力不匹配。探索代码库只需要 Haiku + 只读工具，但实现功能需要 Sonnet/Opus + 全量工具。单 Agent 只能用一个配置。
多 Agent 不是为了"看起来很酷"，而是用架构解决资源分配问题------让不同的 Agent 用不同的模型、不同的工具集、不同的权限，并行处理不同的子任务。
但多 Agent 也有自己的问题：上下文传递的开销、权限管理的复杂度、子 Agent 之间的协调成本。Claude Code 的三种模式就是在不同维度上做取舍。
二、一切从 AgentTool 开始------统一入口
在 Claude Code 中，所有子代理的创建都通过一个统一的工具------AgentTool。
从主 Agent 的视角看，AgentTool 和其他工具（如 Bash、Edit）没有任何区别。调用它就像调用一个普通函数：
typescript
// 主 Agent 调用 AgentTool 就像调用 Bash("ls") 一样自然
{
name: "Agent",
input: {
description: "帮我搜索整个代码库中的认证逻辑",
prompt: "找到所有与 authentication 相关的文件...",
subagent_type: "Explore"
}
}但 AgentTool 的真正身份是 "工具的工厂"------调用它，系统就会创建一个完整的子 Agent。这个子 Agent 拥有自己的对话循环、独立的上下文窗口、裁剪后的工具集，甚至可以使用不同的模型。
AgentTool 会根据参数走不同的路由路径：
- 默认不指定
subagent_type→ Fork 路径（共享父上下文的轻量分身） - 指定
team_name+name→ 生成持久化的 Teammate（Swarm 模式） - 设置
isolation: 'remote'→ 发送到云端运行 - 设置
run_in_background: true→ 后台异步执行
三、Fork 模式------最轻量级的"分身"
Fork 是 Claude Code 中最有特色、也最经济的子 Agent 模式。它的核心设计思路是 Prompt Cache 共享。
3.1 什么是 Fork？
当调用 AgentTool 时不指定 subagent_type，默认走 Fork 路径。
Fork 子 Agent 会完整继承父 Agent 的对话上下文 。系统会构建一个所有 Fork 子 Agent 共享的、字节完全一致的 API 请求前缀------所有 fork 子进程共享父 Agent 的完整 assistant 消息（所有 tool_use 块），用相同的占位符 tool_result 填充，只有最后一个 text 块包含各自的指令。
通俗来说：就像一个班级里，所有学生共用同一本教材（共享的 Prompt Cache），只在最后一页写各自的作业（不同的任务指令）。
3.2 Fork 的核心特点
成本极低。由于前缀字节完全一致，API 请求可以命中 Prompt Cache。官方文档明确说："Forks are cheap because they share your prompt cache。"启动多个 Fork 子 Agent 的成本远低于启动多个独立的普通子 Agent。
上下文受限。Fork 继承了父 Agent 的完整上下文------这既是优势也是劣势。好处是不需要重新描述背景；坏处是子 Agent 无法拥有一个"干净"的独立上下文，可能会受到父对话中无关信息的干扰。
无横向通信。Fork 子 Agent 之间没有横向通信，只向父进程返回结果。
运行时隔离。尽管共享了缓存上下文，但每个 Fork 子 Agent 在运行时拥有自己独立的消息历史、文件状态缓存、中断控制器和工具权限上下文，互不干扰。子 Agent 完成后只返回一个结果字符串，不共享其他状态。
不要换模型。官方特别提醒：不要在 Fork 上设置不同的模型------换了模型就无法复用父 Agent 的 Prompt Cache 了。
3.3 Fork 的使用场景
Fork 最适合快速并行探索/微任务------比如同时搜索三个不同模块的代码、并行读取多个文件并做初步分析、快速验证多个不同的假设。它是最轻量的选择。
四、五种内置子 Agent------开箱即用的专业角色
Claude Code 内置了五种预配置的子 Agent 类型，覆盖从研究到验证的完整链路：
| 类型 | 核心职责 | 特点 |
|---|---|---|
| GeneralPurpose | 通用型子 Agent | 工具集中包含 AgentTool，可以递归创建子子 Agent |
| Explore | 代码库探索与搜索 | 只读、快速，使用 Haiku 模型 |
| Plan | 任务规划 | 专注于制定方案和步骤 |
| Verification | 验证与审查 | 代码审查、测试结果验证 |
| Fork | 轻量级分身 | 共享父 Agent 的 Prompt Cache |
⚠️ 注意：大多数内置角色（Explore、Plan、Verification 等）在工具层面禁用了 AgentTool------也就是说它们不能再 spawn 子子 Agent。只有 GeneralPurpose 拥有完整的递归能力。
五、后台任务系统------异步执行的基石
子 Agent 支持后台运行，背后是一套 Task 系统在支撑。
5.1 七种任务类型
Claude Code 将后台操作建模为七种任务类型：
| 类型 | 用途 |
|---|---|
local_bash |
后台 Shell 命令 |
local_agent |
后台子 Agent |
remote_agent |
远程会话 |
in_process_teammate |
Swarm 队友 |
local_workflow |
工作流脚本执行 |
monitor_mcp |
MCP 服务器监控 |
dream |
推测性后台思考（等待用户输入时让 Agent 默默思考） |
其中 local_bash 和 local_agent 是最常用的工作马。每个任务类型都有一个单字符 ID 前缀用于即时视觉识别。
用户可以通过 /tasks 命令查看当前后台运行的任务列表，实现"主对话继续，子任务在后台默默干活"的异步协作体验。
六、Swarm / Agent Teams------对等协作的"团队模式"
如果说 Fork 是"分身"，那 Swarm 就是 "组队"。
Swarm 模式（官方名称 Agent Teams）是一个实验性功能 ，默认禁用。需要通过将 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 添加到 settings.json 或环境变量来启用。
6.1 核心机制
一个 Claude Code 会话充当团队负责人 ，协调工作、分配任务和综合结果。队友独立工作，每个都在自己的 context window 中，并直接相互通信。
与 subagents 不同------subagents 在单个会话中运行，只能向主代理报告------在 agent teams 中，队友共享任务列表、认领工作并直接相互通信。
6.2 消息传递机制：Mailbox 系统
Swarm 最核心的设计就是它的消息传递系统。
消息面接近点对点，控制面仍然以 lead 为中心。更具体地说：
- 队友之间可以直接
SendMessage，不需要经过负责人中转 - 但团队创建、团队清理、成员发现、权限聚合、UI 呈现仍然围着 lead 打转
- 这就是为什么它看起来比 Coordinator 更自由，但又没有真的变成一个"无主集群"
在代码层面，消息传递通过 Mailbox（信箱）系统实现------一个基于文件的信箱系统，带有锁文件并发控制。团队和任务都存储在本地：Team lead 创建团队，teammates 各自处理分配的任务，Task list 是队友认领和完成的共享工作项列表，Mailbox 是代理之间通信的消息系统。
关键约束：你的文本输出别人看不到，必须通过 SendMessage 工具通信。模型必须明确知道：直接写回复文本不会让队友看到，必须调用工具。
6.3 三种 Backend（运行模式）
Swarm 的队友执行有三种 Backend：
| Backend | 说明 |
|---|---|
| tmux/iTerm2 分屏 | 每个队友获得自己的窗格，你可以同时看到每个人的输出，并点击窗格直接交互 |
| In-process | 队友跑在同一个 Node.js 进程里，走 leader queue 同步 |
| Auto | 自动检测：如果已经在 tmux 会话中运行则使用分屏，否则使用 in-process |
Swarm 的关键不是"一定多进程" ，而是 team file、mailbox、SendMessage 这套团队协议。
6.4 任务分配与认领
共享任务列表协调整个团队的工作。负责人创建任务，队友完成它们。任务有三种状态：待处理、进行中和已完成。任务也可以依赖其他任务------具有未解决依赖关系的待处理任务在这些依赖关系完成之前无法被认领。
系统自动管理任务依赖关系。当队友完成其他任务依赖的任务时，被阻止的任务会自动解除阻止。
6.5 与 Subagents 的对比
| 维度 | Subagents | Agent Teams |
|---|---|---|
| Context | 自己的 context window；结果返回给调用者 | 自己的 context window；完全独立 |
| 通信 | 仅向主代理报告结果 | 队友直接相互发送消息 |
| 协调 | 主代理管理所有工作 | 具有自我协调的共享任务列表 |
| 最适合 | 只有结果重要的专注任务 | 需要讨论和协作的复杂工作 |
| 令牌成本 | 较低：结果汇总回主 context | 较高：每个队友是一个独立的 Claude 实例 |
6.6 使用场景
Agent teams 最适合用于并行探索能增加真实价值的任务：
- 研究和审查：多个队友同时调查问题的不同方面，然后分享和质疑彼此的发现
- 新模块或功能：队友各自拥有一个独立的部分，不会相互干扰
- 使用竞争假设进行调试：队友并行测试不同的理论，更快地收敛到答案
- 跨层协调：跨越前端、后端和测试的更改，每个由不同的队友负责
6.7 缓存共享情况
Swarm 模式下，队友之间不共享 Prompt Cache。每个队友都是一个独立的 Claude 实例，拥有自己独立的 context window。令牌使用量随活跃队友数量而增加。
七、Coordinator Mode------最隐秘的"编排模式"
Coordinator Mode 是 Claude Code 中最隐秘也最强大的模式------它被隐藏在一个编译时的功能标志后面。
7.1 开启方式
通过环境变量激活：
bash
CLAUDE_CODE_COORDINATOR_MODE=1 claude重要 ：Coordinator 和 Fork 是互斥的------开启 Coordinator 会自动禁用 Fork。
7.2 核心机制：彻底的上下文隔离
在 Coordinator 模式下，Claude Code 从单 Agent 转变为一个多 Agent 编排器。
关键原则：工作 Agent 无法看到协调者的对话。每个工作 Agent 都以零上下文启动。
这意味着协调者必须编写自包含的提示词------包含工作所需的一切信息：文件路径、行号、错误信息、什么算"完成"。这不是约定，而是架构层面的强制隔离。
7.3 协调者的工具箱
Coordinator 模式下，Agent 的工具集被严格限制：
| 工具 | 用途 |
|---|---|
Agent |
生成一个新的工作 Agent |
SendMessage |
向现有工作 Agent 发送后续消息 |
TaskStop |
终止一个正在运行的工作 Agent |
SyntheticOutput |
合成输出 |
subscribe_pr_activity / unsubscribe_pr_activity |
GitHub PR 事件订阅（如果配置了 GitHub 集成） |
注意缺失了什么 ：BashTool、FileReadTool、FileWriteTool、GrepTool------协调者把所有实际工作都委托给 workers。
7.4 四阶段工作流
Coordinator 的系统提示定义了一个 4 阶段工作流：
Phase 1: Research（研究） ------ 多个 workers 并发调查代码库。协调者同时派出多个研究者 Agent，各自聚焦不同方面（数据模型、API 层、测试套件等）。
Phase 2: Synthesis（综合） ------ 协调者综合研究发现，撰写实现规格说明。规格必须精确到每个文件、每个函数名、每行代码的改动。
Phase 3: Implementation（实现） ------ 协调者派出实现者 Agent，按照规格编写代码。多个实现者不能同时编辑同一个文件。
Phase 4: Verification（验证） ------ 协调者派出验证者 Agent，运行测试、检查类型、质疑实现。
7.5 通信机制：XML <task-notification>
Worker 的输出通过 XML <task-notification> 在 user-role 消息中回传。
这种模式的核心在于信息漏斗------用户只跟协调者对话，协调者把复杂信息压缩成人能理解的摘要。Worker 的输出可能是几千 token，但协调者只把关键信息提炼后告诉用户。
7.6 会话持久化与动态切换
Coordinator 模式支持会话持久化 。当恢复一个会话时，模式必须匹配。但 Claude Code 可以动态切换模式------环境变量是实时读取的，不是缓存的。这意味着可以在进程中途切换模式以匹配恢复的会话。
7.7 缓存共享情况
Coordinator 模式下，workers 之间不共享任何上下文。每个 worker 都以零上下文启动。这是架构层面的强制隔离------不是约定，是代码强制。
7.8 使用场景
Coordinator 是 Claude Code 的 "项目经理模式" 。适合需要全局视野、多阶段流水线的大型任务------协调者自己不执行工具，只拆任务、派活、综合结果。比如复杂工程任务（研究→综合→实现→验证）。
八、三种模式完整对比
| 维度 | Fork Subagent | Swarm / Agent Teams | Coordinator Mode |
|---|---|---|---|
| 拓扑 | 父进程分裂出 N 个子进程 | 弱中心化：lead 管生命周期，队友可互发消息 | 中心化：协调者 + N 个 worker |
| 通信方式 | 无横向通信，只回父进程 | SendMessage + mailbox | XML <task-notification> 回传 |
| 运行环境 | 同进程异步 | tmux/iTerm2 面板或 in-process | 同进程异步 |
| 上下文共享 | 完整继承父对话 + prompt cache | 无（队友独立会话） | 无（worker 独立 prompt，零上下文启动） |
| 权限模型 | bubble 冒泡到父终端 | in-process 走 leader queue，pane 模式走 mailbox 同步 | worker 工具受限 |
| 互斥性 | 与 Coordinator 互斥 | 独立 | 与 Fork 互斥 |
| 适用场景 | 快速并行探索/微任务 | 长期运行的并行团队 | 复杂工程任务 |
| 令牌成本 | 极低（共享 Cache） | 高（每个队友独立实例） | 高（每个 worker 独立） |
九、总结
Claude Code 的子代理系统，本质上解决的是 "如何让一个 AI 同时做多件事" 的问题。
Claude Code 的答案是不是一种机制，而是一层层的编排模式堆栈，每一种都适合不同形状的工作：
- Fork 通过共享 Prompt Cache 实现了极低成本的分身，适合轻量级、高频的快速并行探索。
- 内置子 Agent（Explore、Plan、Verification 等）提供了开箱即用的专业化能力。
- Swarm / Agent Teams 通过 Mailbox 系统和直接
SendMessage让多个 Claude 实例像人类团队一样协作讨论，适合需要并行探索和讨论的复杂项目。 - Coordinator Mode 则是最彻底的自动化编排------协调者只负责调度，所有实际工作由零上下文启动的 workers 完成，适合需要全局视野、多阶段流水线的大型工程任务。
从"单线程"到"多线程"，从"一个人干活"到"组建团队"------Claude Code 的子代理系统正在重新定义 AI 编程助手的上限。理解这套系统，你就能让 Claude 不只是帮你写代码，而是帮你组织和管理一个 AI 团队。