11：Multi-Agent / Subagent：Claude Code 什么时候需要多个 Agent

上一篇写 Hooks & Extension 时，我把 Claude Code 的扩展系统理解成一组 runtime 入口：command 管任务入口，skill 管可复用能力，MCP 把外部系统变成工具，hook 接在执行事件上。

写到最后，还剩下 subagent 没展开。

它和前面那些扩展入口不太一样。command、skill、MCP、hook 解决的是“能力怎么接进来”。subagent 追问的是另一件事：一段任务什么时候应该拆出去，交给另一个有边界的执行单元。

这一篇要拆的问题是：

Claude Code 为什么需要 subagent？什么时候值得把任务拆出去，拆出去以后上下文、工具、权限和结果边界怎么管？

我现在对 Multi-Agent / Subagent 的理解可以先收成一句话：

多 Agent 的重点在边界，不在热闹。它把局部复杂任务放进有上下文、工具、权限和输出约束的执行单元里。

为什么要拆出 subagent

单 Agent 已经能做很多事。它能读文件、搜代码、改文件、跑测试，也能处理权限、观测和失败恢复。

subagent 出现，通常是因为有些任务局部很重。

比如：

• 要读一批文件，最后只需要一份摘要。
• 要从安全视角审查一段改动，主 Agent 还要继续保持实现方向。
• 要分析很长的测试日志，找到几个可能相关的源码位置。
• 要并行调查前端、后端、测试三个互不依赖的线索。

这些任务都适合被拆出去。主 Agent 保留目标和最终决策，subagent 在自己的范围里探索，然后把压缩后的结果带回来。

所以 subagent 的核心价值，是把上下文压力、专业视角和局部探索隔离出去。

别把多 Agent 当角色扮演

我一开始也容易把多 Agent 想成几个角色 prompt。

一个 planner 负责计划。
一个 coder 负责写代码。
一个 reviewer 负责检查。
一个 tester 负责跑测试。

这个想法很顺手，也很容易让人兴奋。但参考资料里关于 Subagent 的源码解读和隔离设计反复指向一个问题：角色名本身不解决工程复杂度[1][2]。

真正要解决的是边界。

一个 reviewer subagent 如果能随便改代码、跑危险命令、读敏感文件，它已经越过了 review 的边界，变成了另一个执行入口。

一个 test subagent 如果只返回“我看完了，可能是配置问题”，主 Agent 也很难拿它继续决策。

所以多 Agent 的关键不在于名字，而在于它是否有清楚的输入、上下文、工具、权限和输出约束。

主 Agent 负责收束

从 Coordinator + Subagent 这类分析看，主 Agent 的位置应该更像 coordinator[4]。

它负责三件事。

第一，理解用户目标。

主 Agent 要知道这次任务到底要解决什么，哪些约束不能碰，什么时候需要问用户。

第二，决定是否委派。

委派要有选择。只有任务边界清楚、局部探索较重、结果能汇总时，拆出去才有意义。

第三，合并结果并做最终判断。

subagent 可以给出发现和建议，但主线要由主 Agent 收束。尤其是写文件、触发外部系统、改变执行方向这类动作，最好回到主 Agent 统一裁决。

委派任务也要具体。

“你来当 reviewer，看一下项目”太泛。更稳的写法是：

只审查当前 diff，重点看行为回归、安全风险、缺失测试和边界条件。只读，不要修改文件。返回问题、证据和建议优先级。

这个任务边界清楚，结果也容易被主 Agent 使用。

subagent 的四条边界

subagent 真正值得拆的地方，可以压成四条边界。

边界	要回答的问题	失控时会怎样
上下文边界	子 Agent 能看到什么	主线被无关信息污染，或关键证据丢失
工具边界	子 Agent 能调用什么	review agent 改代码，research agent 跑危险命令
权限边界	哪些动作需要继承、限制或重新确认	子 Agent 绕过主线权限策略
结果边界	子 Agent 必须返回什么	主 Agent 拿到一段二手摘要，无法继续判断

上下文边界让 subagent 可以读很多东西，但只把结论、证据和不确定点带回主线。

工具边界让不同 subagent 只拿自己需要的工具。review subagent 通常只需要 Read、Grep、Glob；test subagent 可能需要 Bash 跑测试；docs subagent 可能只需要读文档。

权限边界让 subagent 的能力和来源匹配。项目、插件、用户、团队配置带来的 subagent，信任级别并不一样。

结果边界让主 Agent 能继续决策。subagent 的输出应该是一份可检查、可合并、可追问的结果。

结果必须带证据

补充资料里有一个点很重要：subagent 的结果回到主线时必须带 evidence；缺少 evidence 的结果只能算二手摘要[6]。

这句话几乎可以当作 11 的硬规则。

一个 subagent 返回：

没发现明显问题。

这个结果很难用。

更好的返回应该包括：

返回内容	作用
inspected_scope	它看了哪些文件、命令输出或外部信息
conclusion	它得到什么结论
evidence	支撑结论的文件、位置或输出摘要
uncertainty	哪些地方还不确定
suggested_next_step	建议主 Agent 下一步做什么

主 Agent 只有拿到这些信息，才能判断要不要采纳、要不要继续查、要不要让另一个 subagent 交叉验证。

这也是 subagent 和普通聊天角色的差别。subagent 的输出要服务主线决策，不是展示自己说得像专家。

task state 和 subagent 的区别

Subagent 和 task state 容易混。

task state / todo 记录的是主任务进度。比如哪一步 pending，哪一步 in_progress，哪一步 completed。

subagent 是执行某个子任务的隔离执行单元。它有自己的上下文、工具范围、权限边界和输出要求。

主 Agent 可以把 todo 里的某一步交给 subagent，但两者职责不同。

todo 让任务可见。
subagent 让某段任务独立执行。

这个区别能避免一个误解：列了计划，并不会自动变成多 Agent 协作；起了一个子 Agent，也不会自动让任务状态变清楚。

来源也是信任边界

subagent 从哪里来，也会影响它能做什么。

参考资料里关于用户代理、项目代理、插件代理和权限限制的讨论，本质上都在处理信任边界[2]。

用户自己定义的 subagent，信任度通常更高。
项目仓库里的 subagent，需要用户审查。
插件带来的 subagent，要有更强约束。
团队或企业托管的 subagent，可能带有组织级规则。

这个来源差异会影响可配置字段。

比如一个插件来源的 subagent，如果能随便定义 hooks、MCP server 或 permission mode，它就可能从“一个专业助手”变成新的执行入口。

所以 subagent 更像带来源、工具、权限和生命周期约束的执行配置。

什么时候值得使用

多 Agent 有成本。

主 Agent 要决定拆什么、交给谁、何时合并结果。
subagent 看到的信息和主线不一样。
多个结果可能互相冲突。
每个 subagent 都需要权限和观测记录。

所以 subagent 适合这些场景：

• 局部复杂：子任务需要读很多材料或做一段独立调查。
• 边界清楚：知道它该看什么、能做什么、不能碰什么。
• 结果可汇总：它能返回证据、结论和建议。
• 视角专门：安全审查、测试分析、文档整理这类固定视角比较明确。

有些场景留给主 Agent 更合适。

任务很小，主 Agent 直接做就行。
边界模糊，拆出去只会制造协调成本。
多个 subagent 都要改同一区域，冲突会变多。
结果无法验证，主 Agent 只会拿到一堆看似专业的摘要。

测试失败就是一个很好的分界例子。

如果只是一个明确报错，比如某个字段缺失，主 Agent 直接修更快。
如果日志很长、跨多个模块、需要读很多文件，可以让 test subagent 只做 diagnosis：分析失败原因、定位可能文件、返回证据和修复建议。真正修改仍然回到主 Agent。

例子：代码审查 subagent

代码审查比较适合 subagent，因为它天然有边界。

它可以只读当前 diff 和相关文件，重点找风险，不直接修改代码。

主 Agent 可以这样委派：

请审查当前 diff，重点看行为回归、安全风险、缺失测试和边界条件。只读，不要修改文件。输出发现、证据和建议优先级。

review subagent 做的事情很清楚：

1. 读取当前 diff。
2. 根据 diff 找相关文件。
3. 检查行为变化、边界条件和测试缺口。
4. 返回风险、证据、建议优先级。

它的结果可以长这样：

字段	示例
risk	支付状态在失败分支没有回滚
evidence	payment/service.ts 的状态更新逻辑和对应测试缺口
severity	high
uncertainty	没看到异步重试任务的完整调用链
next_step	主 Agent 继续读重试任务入口，再决定是否修改

这里 subagent 负责局部审查，主 Agent 负责最终判断。

是否采纳问题、是否修改代码、是否请求用户确认，都回到主线。这样既利用了 subagent 的专业视角，也保留了主 Agent 的收束权。

我会怎么设计 subagent

如果自己写一个 coding agent，我会先把单 Agent 底座做稳，再引入 subagent。

单 Agent 的底座包括：Agent Loop、工具协议、上下文管理、计划状态、权限裁决、观测记录、失败恢复和扩展入口。

引入 subagent 时，我会至少设计三个对象。

第一个是 SubagentSpec。

它描述这个 subagent 是什么：

字段	作用
name	子 Agent 名称
purpose	它解决什么子任务
allowed_tools	它能调用哪些工具
permission_scope	它继承或限制哪些权限
context_policy	它能读哪些上下文，结果怎么压缩
audit_policy	它的 transcript / trace 怎么记录

第二个是 TaskDelegation。

它描述主 Agent 这次交出去的任务：

字段	作用
task_goal	这次子任务要解决什么
input_context	主 Agent 给它哪些信息
hard_limits	哪些动作保持禁止或只读
expected_output	返回结构和粒度

第三个是 SubagentResult。

它描述结果怎么回到主线：

字段	作用
conclusion	子任务结论
evidence	支撑结论的证据
uncertainty	不确定点
suggested_next_step	建议主 Agent 下一步
trace_ref	对应的 transcript 或 trace

这样设计以后，subagent 更像可审计的任务执行单元。

主 Agent 负责目标、计划和最终决策。subagent 负责边界清楚的局部调查、审查或整理。它们之间通过结构化输入输出连接。

参考资料

Claude Code Subagent 机制

• [1] 深入解析 Claude Code 的 Subagent 机制 - 知乎
  本文主要参考它关于 Subagent 如何创建、管理上下文、访问工具、并行执行、嵌套，以及和 Task 系统区别的分析。

• [2] 拆解 Claude Code SubAgent：隔离、专业化与权限设计 - 博客园
  本文主要参考它关于子代理来源、优先级、权限限制、插件代理安全边界和隔离设计的分析。

• [3] Claude Code Subagents 完全指南：构建专业化 AI 助手体系 - 博客园
  本文主要参考它关于专业化助手、工具权限和任务拆分场景的整理。

编排模式与系统背景

• [4] Claude Code 源码泄露：5 个 Agent 设计模式拆解，全网首发！ - 腾讯云
  本文主要参考它关于 Coordinator + Subagent、Fork Subagent、权限链和文件记忆如何协作的分析。

• [5] Claude Code 源代码泄露？万字解析深入其 Agent 编排系统的架构与实现 - GitCode
  本文主要参考它关于 Agent tool、tools、commands、services 和 hooks 在编排系统里的分工。

• [6] 非官方源码分析文章检索补充
  本文主要参考其中关于 fork / teammate / worktree 三种 subagent execution model、forked subagent、Coordinator + Subagent、结果回主线必须带 evidence 的整理。

• [7] Dive into Claude Code - GitHub
  本文只作为系统性背景，参考其中关于 multi-agent、subagent 和 agent design space 的整理。

系列收束

这一篇把 Multi-Agent / Subagent 理解成 Agent Runtime 的任务委派和隔离层。

核心结论是：

subagent 是带上下文、工具、权限和输出边界的任务执行单元，它的价值来自边界清楚的委派。

从 01 到 11，这个系列一直在回答 00 里那个问题：

AI Agent 如何从一次聪明的回答，变成一个可维护、可调试、可协作的工程系统？

我的答案现在更清楚了。

Agent 更像一套 runtime，而不是一个模型加几个工具。

这套 runtime 需要主循环，需要工具，需要上下文，需要提示协议，需要计划，需要记忆，需要权限，需要观测，需要恢复，需要扩展，也需要在必要时把任务拆给有边界的 subagent。

这些模块组合起来，才是 coding agent 真正的工程形态。真正值得学的地方，也不只是某个单点功能，而是这些模块怎么互相咬合。