Claude Code 子代理系统完全指南Fork、Swarm 与 Coordinator 深度拆解当 Claude 学会“生儿子”编程的效率就彻底变了。如果你用过 Claude Code你可能已经习惯了让它帮你写代码、改 bug、跑测试。但你可能没有意识到Claude Code 最强大的能力其实藏在“子代理”Subagent系统里——它能让一个 Claude 分身出多个 Claude并行工作各司其职。本文从源码和设计理念出发系统讲解 Claude Code 的子代理系统重点拆解Fork 模式、SwarmAgent 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没有任何区别。调用它就像调用一个普通函数// 主 Agent 调用 AgentTool 就像调用 Bash(ls) 一样自然{name:Agent,input:{description:帮我搜索整个代码库中的认证逻辑,prompt:找到所有与 authentication 相关的文件...,subagent_type:Explore}}但AgentTool的真正身份是“工具的工厂”——调用它系统就会创建一个完整的子 Agent。这个子 Agent 拥有自己的对话循环、独立的上下文窗口、裁剪后的工具集甚至可以使用不同的模型。AgentTool 会根据参数走不同的路由路径默认不指定subagent_type→Fork 路径共享父上下文的轻量分身指定team_namename→ 生成持久化的TeammateSwarm 模式设置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可以递归创建子子 AgentExplore代码库探索与搜索只读、快速使用 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后台子 Agentremote_agent远程会话in_process_teammateSwarm 队友local_workflow工作流脚本执行monitor_mcpMCP 服务器监控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 的队友执行有三种 BackendBackend说明tmux/iTerm2 分屏每个队友获得自己的窗格你可以同时看到每个人的输出并点击窗格直接交互In-process队友跑在同一个 Node.js 进程里走 leader queue 同步Auto自动检测如果已经在 tmux 会话中运行则使用分屏否则使用 in-processSwarm 的关键不是“一定多进程”而是team file、mailbox、SendMessage 这套团队协议。6.4 任务分配与认领共享任务列表协调整个团队的工作。负责人创建任务队友完成它们。任务有三种状态待处理、进行中和已完成。任务也可以依赖其他任务——具有未解决依赖关系的待处理任务在这些依赖关系完成之前无法被认领。系统自动管理任务依赖关系。当队友完成其他任务依赖的任务时被阻止的任务会自动解除阻止。6.5 与 Subagents 的对比维度SubagentsAgent TeamsContext自己的 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 开启方式通过环境变量激活CLAUDE_CODE_COORDINATOR_MODE1claude重要Coordinator 和 Fork 是互斥的——开启 Coordinator 会自动禁用 Fork。7.2 核心机制彻底的上下文隔离在 Coordinator 模式下Claude Code 从单 Agent 转变为一个多 Agent 编排器。关键原则工作 Agent 无法看到协调者的对话。每个工作 Agent 都以零上下文启动。这意味着协调者必须编写自包含的提示词——包含工作所需的一切信息文件路径、行号、错误信息、什么算“完成”。这不是约定而是架构层面的强制隔离。7.3 协调者的工具箱Coordinator 模式下Agent 的工具集被严格限制工具用途Agent生成一个新的工作 AgentSendMessage向现有工作 Agent 发送后续消息TaskStop终止一个正在运行的工作 AgentSyntheticOutput合成输出subscribe_pr_activity/unsubscribe_pr_activityGitHub 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 通信机制XMLtask-notificationWorker 的输出通过XMLtask-notification在 user-role 消息中回传。这种模式的核心在于信息漏斗——用户只跟协调者对话协调者把复杂信息压缩成人能理解的摘要。Worker 的输出可能是几千 token但协调者只把关键信息提炼后告诉用户。7.6 会话持久化与动态切换Coordinator 模式支持会话持久化。当恢复一个会话时模式必须匹配。但 Claude Code 可以动态切换模式——环境变量是实时读取的不是缓存的。这意味着可以在进程中途切换模式以匹配恢复的会话。7.7 缓存共享情况Coordinator 模式下workers 之间不共享任何上下文。每个 worker 都以零上下文启动。这是架构层面的强制隔离——不是约定是代码强制。7.8 使用场景Coordinator 是 Claude Code 的“项目经理模式”。适合需要全局视野、多阶段流水线的大型任务——协调者自己不执行工具只拆任务、派活、综合结果。比如复杂工程任务研究→综合→实现→验证。八、三种模式完整对比维度Fork SubagentSwarm / Agent TeamsCoordinator Mode拓扑父进程分裂出 N 个子进程弱中心化lead 管生命周期队友可互发消息中心化协调者 N 个 worker通信方式无横向通信只回父进程SendMessage mailboxXMLtask-notification回传运行环境同进程异步tmux/iTerm2 面板或 in-process同进程异步上下文共享完整继承父对话 prompt cache无队友独立会话无worker 独立 prompt零上下文启动权限模型bubble 冒泡到父终端in-process 走 leader queuepane 模式走 mailbox 同步worker 工具受限互斥性与 Coordinator 互斥独立与 Fork 互斥适用场景快速并行探索/微任务长期运行的并行团队复杂工程任务令牌成本极低共享 Cache高每个队友独立实例高每个 worker 独立九、总结Claude Code 的子代理系统本质上解决的是“如何让一个 AI 同时做多件事”的问题。Claude Code 的答案是不是一种机制而是一层层的编排模式堆栈每一种都适合不同形状的工作Fork通过共享 Prompt Cache 实现了极低成本的分身适合轻量级、高频的快速并行探索。内置子 AgentExplore、Plan、Verification 等提供了开箱即用的专业化能力。Swarm / Agent Teams通过 Mailbox 系统和直接SendMessage让多个 Claude 实例像人类团队一样协作讨论适合需要并行探索和讨论的复杂项目。Coordinator Mode则是最彻底的自动化编排——协调者只负责调度所有实际工作由零上下文启动的 workers 完成适合需要全局视野、多阶段流水线的大型工程任务。从“单线程”到“多线程”从“一个人干活”到“组建团队”——Claude Code 的子代理系统正在重新定义 AI 编程助手的上限。理解这套系统你就能让 Claude 不只是帮你写代码而是帮你组织和管理一个 AI 团队。