一、场景：你还在让 AI 一个一个干活吗

用 Claude Code 干活的时候，你是不是经常这样：

- 让它重构 5 个文件，它一个接一个改，改了半小时

- 让它写 10 个单元测试，它写完一个再写下一个

- 让它检查 8 个接口的边界情况，它查完一个再查下一个

AI 很能干，但它默认是单线程的——一次只处理一个任务，做完一个才做下一个。

而你的项目里有大量任务其实是互相独立的：5 个文件的代码风格检查、10 个模块的测试补充、8 个接口的参数校验……它们之间没有依赖关系，完全可以同时干。

Claude Code 的 Subagent（子代理） 机制，就是干这个的：把一个大任务拆成多个小任务，分给多个子代理并行执行，最后汇总结果。一条命令，10 个任务同时开跑。

这篇文章讲清楚 Subagent 是什么、怎么用、什么场景收益最大。

二、Subagent 是什么：AI 的"团队模式"

理解 Subagent 最简单的方式，是把它想象成你手下的一支 AI 团队：

- 主代理（Main Agent）：你，负责拆任务、派活、汇总结果

- 子代理（Subagent）：团队成员，每人领一个任务，独立干活，干完交结果

主代理负责调度，子代理负责执行。它们之间互不干扰，各自有独立的上下文窗口——所以子代理越多，能同时处理的上下文总量就越大。

举个具体的例子：

claude "帮我检查项目中所有 Controller 的输入校验，找出缺失校验的接口。分别检查 order、user、product 三个模块，每个模块一个子任务，最后汇总成一份报告"

Claude Code 会自动创建 3 个子代理，一个查 order 模块、一个查 user 模块、一个查 product 模块。3 个任务同时跑，最后把结果合并成一份报告给你。

对比一下串行和并行的差别：串行 3 个任务，每个 2 分钟，总共 6 分钟；并行 3 个任务同时跑，总共 2 分钟多一点点。任务越多，节省的时间越明显。

三、什么任务适合拆给 Subagent

不是所有任务都适合并行。适合拆的任务有三个特征：

1. 任务互相独立

任务之间没有依赖关系——A 任务的输出不需要等 B 任务。比如：

- ✅ 检查多个模块的代码规范（每个模块独立）

- ✅ 给多个类写单元测试（每个类独立）

- ✅ 审查多个文件的 Bug（每个文件独立）

- ❌ 重构一个功能，改完 A 才能改 B（有依赖，不适合拆）

2. 任务数量多但单个不大

拆出来的每个子任务都应该是"小而明确"的。比如"给 10 个工具类各写一个单测"就比"重构整个项目"适合拆。任务太大会超子代理的上下文窗口，任务太小又浪费调度开销。

3. 结果容易合并

每个子任务的输出应该是独立的、可汇总的。比如"每个模块的检查报告"、"每个类的测试代码"，汇总起来就是完整结果。反过来，"让 3 个子代理合作写一个类"就不行——它们没法协调，结果会冲突。

四、实战：一次并行处理 6 个任务

直接看一个完整的实战。假设你的项目里有 6 个工具类需要补单元测试，传统做法是一个一个来，用 Subagent 可以一次搞定：

claude "给以下 6 个工具类各写一份单元测试，每个类一个子任务，并行执行：
1. StringUtils.java
2. DateUtils.java
3. JsonUtils.java
4. MoneyUtils.java
5. FileUtils.java
6. CryptoUtils.java
测试要覆盖正常路径和边界情况，运行 mvn test 确认通过，最后汇总测试结果"

Claude Code 会创建 6 个子代理，每个负责一个类。它们同时开工，各自写测试、各自跑测试、各自修问题。全部完成后，主代理汇总成一份报告：

✅ 测试汇总：
1. StringUtilsTest - 8 个用例全部通过
2. DateUtilsTest - 12 个用例全部通过
3. JsonUtilsTest - 9 个用例全部通过
4. MoneyUtilsTest - 11 个用例全部通过
5. FileUtilsTest - 7 个用例全部通过
6. CryptoUtilsTest - 10 个用例全部通过
覆盖率提升：38% → 71%

我实测过类似的场景：6 个类的测试，串行要 25 分钟左右，Subagent 并行 6 分钟搞定。节省了 75% 的时间，而且每个类的测试质量没有下降——因为每个子代理都是完整地读完那个类再写测试的。

五、更高级的用法：按需指定子代理数量

Claude Code 默认会根据任务复杂度自动决定开几个子代理，但你也可以手动指定：

claude "用 3 个子代理并行检查 src/main/java 下所有代码，重点找：
- 空指针风险
- 资源未关闭（连接、流、文件）
- 线程安全问题
每个子代理负责一部分目录，最后汇总问题清单"

指定数量之后，Claude Code 会严格按照你给的数字分配任务。这在任务量明确、你清楚需要多少个并发的时候很好用。

子代理的独立上下文是最大优势

为什么 Subagent 快？除了并行，还有一个关键点：每个子代理有独立的上下文窗口。

主代理的上下文是有限的。如果你让主代理一个人检查 10 个文件，它读到第 6 个文件时，前面 5 个的内容可能已经被挤掉了——这就是为什么任务一多，AI 的表现会明显下降。

但拆给 10 个子代理就不同了：每个子代理只需要读自己负责的 1-2 个文件，上下文非常充裕，理解更深入，输出质量更高。

六、注意事项：Subagent 的 4 个坑

坑 1：别拆有依赖的任务

两个任务之间有先后依赖（A 的输出是 B 的输入），拆开并行反而会出错。比如"先重构接口，再改调用方"——这俩必须串行。判断标准很简单：子任务之间能不能完全独立完成？能才拆。

坑 2：每个子任务要给足上下文

子代理没有主代理的全部记忆。每个子任务要自包含：说清楚文件路径、项目背景、期望输出格式。比如不要只说"检查 user 模块"，要说"检查 src/main/java/com/example/user/ 目录下所有类的输入校验，输出问题清单，格式：类名:行号:问题描述"。

坑 3：结果合并需要你检查

子代理各自干活，风格可能不完全统一——有的报告详细，有的报告简略。主代理汇总后，建议你抽查几个子任务的原始输出，确认没有遗漏或误报。

坑 4：注意 API 消耗

并行意味着同时发起多个请求，API 消耗会成倍增加。任务量特别大的时候，先算一下成本再决定要不要全并行。日常小任务（2-3 个）并行很划算，超大规模任务可以分批次跑。

七、总结

Subagent 并行是 Claude Code 被严重低估的能力之一。核心要点：

1. 独立任务拆开并行：检查多个模块、写多个测试、审多个文件，这些互不依赖的任务适合拆

2. 子代理有独立上下文：任务多的时候，拆开反而质量更高，不会因为上下文挤占而表现下降

3. 注意任务自包含：每个子任务要写清楚路径、背景、输出格式

4. 有依赖的任务别拆：串行就串行，强行并行只会出错

最后分享一个我的使用习惯：凡是"多个同类任务"的场景，先想想能不能拆。检查 5 个模块？拆。写 8 个测试？拆。审 10 个文件？拆。拆完你会发现，原来要等半小时的活，几分钟就出结果了。

---

*下一篇：Claude Code 安全红线——权限控制与危险操作防护，让 AI 帮你干活又不闯祸。*