Claude Code 子 Agent 与多 Agent 编排
单个 Agent 的上下文有限、单线程串行。Claude Code 用子 Agent（subagent） 和多 Agent 协作突破这两个限制：上下文隔离 + 并行执行。这一页讲清子 Agent 机制、协调者/蜂群模式、以及 Git worktree 隔离。多 Agent 通用范式见 多 Agent 与进阶范式。
一、为什么需要子 Agent？
单 Agent 干复杂任务有两个硬伤：
- 上下文污染：一个子任务（如「读懂整个 auth 模块」）会产生海量中间内容，全灌进主上下文会迅速塞满、引入噪声、干扰主线。
- 串行慢：多个独立子任务只能一个个做，无法并行。
子 Agent 同时解决这两点：派生独立的子 Agent，各自有自己的上下文，并行处理，只回传结论。
主 Agent（保持干净的主线上下文）
├─ 派生子 Agent A：调研 auth 模块 ──► 只回传「结论摘要」
├─ 派生子 Agent B：调研 payment 模块 ──► 只回传「结论摘要」
└─ 汇总 A/B 的结论，继续主任务这正是 上下文工程 的 Isolate 操作落地。
二、子 Agent 机制（Task / AgentTool）
- 派生：主 Agent 通过 Task 工具派生子 Agent，给它一个明确的子任务描述。
- 独立上下文：子 Agent 有自己的对话历史、自己的 token 预算，不共享主上下文。
- 工具继承/过滤：子 Agent 可被限定只能用某些工具（最小权限、聚焦职责）。
- 同步/异步生命周期：可阻塞等待子 Agent 结果，也可异步并行多个。
- 只回传结论：子 Agent 内部跑了多少轮、读了多少文件，主 Agent 都看不到，只拿到最终摘要——这是「省主上下文」的关键。
关键认知：子 Agent 不是「更多算力」，而是「上下文隔离的承包商」——把脏活累活（大量探索）外包出去，主 Agent 只对接干净的结论。
三、协调者 / 蜂群模式（Coordinator / Swarm）
更复杂的多 Agent 协作（社区分析的进阶模式）：
- 协调者模式（Coordinator）：一个主 Agent 当「项目经理」，把大任务拆解成子任务、派发给多个 worker Agent、收集并整合结果。对应 工作流 的 Orchestrator-Workers。
- 蜂群/Agent Teams（Swarm）：多个 Agent 组队协作，可能有更对等的分工。
- Mailbox 通信：Agent 之间通过「信箱」机制传递消息/结果，解耦协作。
这类模式适合可并行分解的大任务（如「给整个项目补测试」拆成按模块并行），但协调开销、子任务划分、结果整合都是难点（见 多 Agent 的取舍）。
四、Worktree 隔离：文件级并行的关键
多个 Agent 同时改同一个仓库会互相踩踏（改同一文件、git 冲突）。解法是 Git worktree：
- 每个 Agent 在独立的 worktree（同一仓库的独立工作目录 + 独立分支）里干活，文件互不干扰。
- 各自完成后再合并（merge）回主分支。
- 这让「多个 Agent 真正并行改代码」成为可能，而不是串行排队或互相覆盖。
Worktree 隔离是「上下文隔离」在文件系统层面的延伸：子 Agent 不仅上下文独立，工作区也独立。
五、什么时候用、什么时候别用
| 场景 | 建议 |
|---|---|
| 任务可并行分解、子任务独立 | ✅ 多 Agent（并行加速 + 上下文隔离） |
| 单个子任务上下文很重（大量探索） | ✅ 子 Agent 隔离，保护主上下文 |
| 简单线性任务 | ❌ 单 Agent 就够，多 Agent 是过度设计 |
| 子任务强耦合、需频繁交互 | ⚠️ 协调开销可能大于收益 |
务实原则同 工作流 vs Agent：别为了多 Agent 而多 Agent——它带来协调成本和 token 开销，只在「并行收益 / 上下文隔离需求」明确时才值得。
高频追问
Q：子 Agent 最大的价值是什么？ 上下文隔离。它把「会产生海量中间内容的子任务」外包出去，子 Agent 在自己的上下文里折腾、只回传结论，主 Agent 的上下文保持干净聚焦。这让主 Agent 能处理远超单上下文容量的复杂任务，而不被中间过程塞爆。
Q：子 Agent 是为了更快还是为了省上下文？ 两者都有，但「省上下文（隔离）」往往是更核心的动机。并行能加速独立子任务；但即使串行，把重上下文的子任务隔离出去、只回传摘要，也能极大缓解主上下文压力。隔离价值常大于并行价值。
Q：多个 Agent 同时改代码怎么不冲突？ 用 Git worktree：每个 Agent 在独立的工作目录 + 独立分支里改，文件层面互不干扰，完成后再 merge。这是把「上下文隔离」延伸到「文件系统隔离」，让真正的并行改代码成为可能。
Q：协调者模式和工作流的 Orchestrator-Workers 是一回事吗？ 本质相同：一个中心 Agent 拆任务、派发给多个 worker、整合结果。区别在 worker 是否是有独立上下文和工具的完整子 Agent。详见 工作流 vs Agent 和 多 Agent。
Q：什么时候不该用多 Agent？ 简单线性任务（单 Agent 足够，多 Agent 是过度设计）、子任务强耦合需频繁交互（协调开销大于并行收益）、对成本敏感（多 Agent 的 token 消耗显著更高）。先用最简单的单 Agent，确实遇到「上下文塞爆」或「明显可并行」才上多 Agent。