Claude Code 的 Sub-agent 模式——什么时候该把任务分派给子 Agent
Claude Code 的 Sub-agent 模式——什么时候该把任务分派给子 Agent
适读人群：用Claude Code做复杂任务的开发者 | 阅读时长：约12分钟 | 核心价值：多Agent协作的真实使用边界，不是炒概念
我第一次看到 Claude Code 支持 Sub-agent 的时候，觉得这很酷。然后在一个项目里立刻滥用了它，结果搞得一团糟。
那是一个需要同时修改前端、后端、数据库的功能需求。我觉得：完美，三个子任务，各派一个 Sub-agent 并行处理，效率翻三倍。
结果：前端 Agent 改了接口的字段名，后端 Agent 没有同步，两边对不上。Sub-agent 各自都觉得自己完成了任务，汇总结果的时候我才发现问题，而且这时候两个 Agent 对代码的改动已经交织在一起了，回滚都麻烦。
那之后我开始认真想这个问题：什么时候该分派子 Agent，什么时候单 Agent 反而更好？
Sub-agent 的本质
先说清楚机制。Claude Code 里的 Sub-agent 模式，实际上是在主 Agent 的任务执行过程中，用独立的上下文启动一个新的 Agent 实例，让它完成一个子任务，然后把结果返回给主 Agent。
关键词是"独立的上下文"。
独立上下文意味着：
- Sub-agent 不知道主 Agent 在其他地方改了什么
- Sub-agent 不知道其他 Sub-agent 在做什么
- Sub-agent 只知道你给它的那一部分任务描述
这既是它的优势（隔离、专注），也是它的限制（无法感知全局状态）。
适合用 Sub-agent 的场景
场景一：真正独立的子任务
"独立"的标准：任务 A 的执行不依赖任务 B 的输出，任务 A 的改动不会影响任务 B 操作的代码或文件。
例子：
- 为不同的工具类写测试：
StringUtils的测试和DateUtils的测试完全独立，可以并行 - 多个文档文件的生成：写 API 文档的某个模块，各模块互不干扰
- 批量代码格式化或静态分析：对不同模块跑 linter，互相独立
真实案例。我有一次需要为 5 个 Repository 接口都写单元测试，每个接口大约需要 10-15 个测试用例。这 5 个 Repository 之间没有依赖关系，测试文件也是独立的。
这是使用 Sub-agent 的教科书级场景：
主任务描述：
为以下5个Repository接口生成完整的单元测试：
- OrderRepository
- ProductRepository
- UserRepository
- InventoryRepository
- PaymentRepository
每个Repository启动一个Sub-agent，任务：
1. 读取Repository接口定义
2. 理解每个方法的功能和参数
3. 生成覆盖正常路径、边界情况、异常情况的测试用例
4. 使用Mockito mock数据库层
5. 测试文件命名规范：{接口名}Test.java
注意：各Sub-agent只处理自己负责的Repository，不要跨文件修改。结果：5 个 Sub-agent 并行跑，25 分钟完成了 5 个测试文件，我大概验证了 1.5 小时，发现 4 处需要调整的地方。总计省了大约 3 小时的手写时间。
场景二：需要隔离上下文的探索性任务
有时候你需要探索多个方案，但不想让这些探索性的代码改动污染工作区。
比如：对一个性能问题，你想同时探索三种优化方案（加缓存、优化查询、批量处理），但这三个方案的代码改动是互斥的，不能同时存在。
可以给每个方案派一个 Sub-agent，在独立的分支上实现，最后你来评估哪个方案更好。
这种用法更像是"让 AI 帮我并行思考"，而不是真正的并行执行。
场景三：长任务的分块处理
一个很长的任务（比如生成一份 50 页的技术方案，包含多个独立章节），单 Agent 的上下文可能不够用，而且中间出错了要整个重来。
把任务切成独立的章节，每个 Sub-agent 处理一个章节，可以降低整体失败风险。
不适合用 Sub-agent 的场景
场景一：任务之间有共享状态
这是最容易踩的坑。如果两个 Sub-agent 都需要修改同一个文件、同一个接口、同一个数据库表，就会产生冲突。
我在文章开头举的例子就是这个问题：前端和后端看起来是两个"独立"的任务，但它们共享了接口契约（API 字段名），修改接口时必须两边同步，这件事不能并行。
判断标准：如果任务 A 和任务 B 完成后，你需要手动检查它们的输出是否一致，那就不应该用 Sub-agent 并行处理。
场景二：需要迭代反馈的任务
Sub-agent 拿到任务就去做，做完了返回结果。如果任务需要"先做一步，看看结果，再调整，继续做"这种迭代循环，Sub-agent 做不到这个，因为它完成任务后就结束了，中间的反馈没有办法给到它。
这种场景应该用主 Agent 的多轮对话，而不是 Sub-agent。
场景三：任务很小、上下文本来就够
如果整个任务的上下文在一个 Agent 的窗口里放得下，分派 Sub-agent 不仅不会更快，还会增加协调开销（任务描述、结果汇总、冲突处理）。
一个粗略的标准：如果任务在一个对话里用 1-2 次工具调用就能完成，不要用 Sub-agent。
工作流设计建议
我现在对"要不要用 Sub-agent"的决策流程是：
任务分析
|
v
任务之间有依赖关系？
|YES -> 用单Agent，串行处理
|NO
v
任务共享文件或接口契约？
|YES -> 不能并行，即便用Sub-agent也要串行
|NO
v
每个子任务的上下文 > 2000 token？
|YES -> 考虑Sub-agent（上下文隔离有价值）
|NO -> 单Agent直接搞定这个决策树不是金科玉律，但能避免大多数滥用。
给 Sub-agent 写好任务描述
Sub-agent 的质量很大程度上取决于你给它的任务描述。几个要点：
明确边界，不要含糊
// 差的描述
"帮我优化一下这个模块"
// 好的描述
"只修改 OrderQueryService.java，将方法 findByUserId 的实现从循环查询改为批量查询。
不要修改接口定义、不要修改调用方。"把输入的依赖都提供清楚
Sub-agent 的上下文是独立的，它不知道你之前在主 Agent 里做了什么。需要它知道的上下文，要在任务描述里显式提供。
告诉它完成的标准
"任务完成标准：
1. 生成 src/test/java/OrderQueryServiceTest.java
2. 文件能成功编译
3. 测试用例覆盖正常路径、空列表、userId不存在三个场景"有明确的完成标准，Sub-agent 自我验证的质量会好很多。
一个我现在的真实使用习惯
说实话，我日常用 Sub-agent 的频率并不高。多数任务单 Agent 就能处理好。
Sub-agent 真正让我感觉值的场景是：写测试。
每次我写完一个新功能，我会把所有需要测试的方法列一个清单，然后一次性派出多个 Sub-agent 并行生成测试。这个场景完美符合"独立、不共享状态、上下文清晰"的条件。
其他场景，我都会先想一想：这件事单 Agent 做，到底哪里不够？如果答案是"没什么不够的"，我就不用 Sub-agent。
工具是为了解决问题，不是为了看起来更高级。