Claude Code 里用子 Agent 做并行任务，实测快了 4.2 倍

92 分钟和 20 分钟的差距从哪来

先把场景说清楚。甲方是一家上市物流公司的前端团队，他们两年前基于 Chakra UI 1.x 写了 340 个业务组件。Chakra 3 改了一大堆 API，emotion 换成 vanilla extract，<Box> 的 shorthand 全变了。

我第一天用 Claude Code 一个会话串行干，大概一个组件平均 16 秒——读文件、改 import、改 props、改 theme token、跑测试。干到第 70 个的时候，时钟显示 18 分 47 秒。按这个速度走完要 1 小时 32 分，还没算上中间可能卡住的调试时间。

我就停下来想，这活有完美的并行性：340 个组件之间几乎没有依赖，改第 1 个和改第 200 个不会冲突。为什么我要串行？

第二天重开一个会话，用主 Agent 派 8 个子 Agent 并行。每个子 Agent 领 40-43 个组件自己搞。主 Agent 负责分发、收集失败 case 兜底。

总耗时 20 分 47 秒。加速比 4.2x（不是 8x 是因为主 Agent 本身有 overhead，另外后期失败 case 收拢还是串行的）。

这个案例之后我琢磨了挺久子 Agent 到底应该怎么编排，哪些场景真能并行，写出来分享。

Agent Tool 和 Task 子任务不是一回事

先正名。Claude Code 里说”子 Agent”其实有两个含义：

Task 工具派发的子任务：主 Agent 通过 Task 工具调出一个独立的 agent 实例，独立上下文，跑完把结果回传。跑完就销毁，不保留状态。

自定义 subagent：在 .claude/agents/ 下面定义的专用 agent，有自己的 system prompt、工具白名单、默认模型。可以被主 Agent 调用，也可以被用户显式 @<agent-name> 调用。

这两个背后机制是一样的——新开一个上下文隔离的 agent 实例。差别在于 Task 是临时一次性的，subagent 是可复用的。我大部分并行都用 Task，只有那种反复用的（比如 /test-runner）才写成 subagent。

具体的 agent 架构想深入的话看 Agent SDK 架构，那里有完整的消息传递图。

什么时候该派子 Agent，我的 4 条判据

不是所有活都值得拆。判断标准：

判据 1：任务之间真的独立。 改组件 A 不需要看组件 B 的结果。如果有依赖就别并行，串行还省 token。

判据 2：上下文读取量大但处理可隔离。 比如”读 200 个文件找某个模式”，每个子 Agent 只需要看自己那批文件，主 Agent 只收结论，不收原文。

判据 3：需要不同的”心态”做多视角 review。 安全视角、性能视角、可维护性视角互相独立，一个 Agent 切来切去效果不好。

判据 4：用户明确说”同时做 X 和 Y”。 这种明面上的并行意图不要违背。

反过来说什么不能并行：

• 任何涉及 shared state 的编辑（都改同一个 package.json 就是灾难）
• 需要中间决策的任务链（拿到结果 A 才能决定要不要做 B）
• 会话总 token 预算吃紧的时候（每个子 Agent 起步就吃 6-10K 的系统提示）

5 种我反复用的分派模式

模式 1：扇出搜索

“在仓库里找所有还在用 deprecated API 的地方”这种活，派 5 个子 Agent 分目录扫，各自 grep + 读相关代码 + 总结。主 Agent 合并结果去重。

比单 Agent 跑快 3 倍左右，主要原因是每个子 Agent 的 context 只装它那块目录的信息，attention 更集中。

模式 2：并行文件读取

需要批量读 30+ 个文件做总结时（比如 “看看 src/hooks/ 下所有 hook 的命名规范”），分组派发。主 Agent 最后只拿到每个子 Agent 的一句话结论，保住了自己的 context budget。

这个跟 Context 预算策略 是一套思路——主 Agent 的上下文是最宝贵的资源，能甩出去的粗活都甩。

模式 3：独立测试跑批

改了一个 util 函数，想跑整个测试套件但又怕单进程太慢。派 4 个子 Agent 分 testsuite 跑，每个跑一个 shard。失败的测试收拢给主 Agent 分析。

模式 4：多视角 review

前面 /review 那篇提到的 4 视角（安全/性能/可维护/兼容）。如果让一个 Agent 切换身份做，它会偷懒——尤其到第 3、第 4 个视角就开始敷衍。

派 4 个子 Agent 同时各做一个视角，质量差异巨大。我们做过 A/B 对比，多 Agent 并行版本抓到的 issue 数量是串行 1.6 倍。

模式 5：worktree 并行重构

这个是我 2026 年 3 月发现的骚操作。git worktree 开 3-4 个工作区，每个子 Agent 跑一个方向的重构方案，最后人工挑一个。

比如”把这个状态管理重构一下”，让子 Agent 1 用 zustand 重构，子 Agent 2 用 jotai 重构，子 Agent 3 保持 redux 但清理冗余。并行跑 25 分钟，比我自己决策后让 Claude 走一条路再回头重试省事得多。

那 340 个组件迁移的完整编排

回到开头那个案例。具体怎么编排的：

主 Agent 做的事：

1. 先读 migration guide、扫一个代表性组件，生成迁移规则清单（15 条）
2. find 出 340 个组件文件列表
3. 按目录 hash 分成 8 组，每组 40-43 个
4. 派 8 个 Task，每个传入：迁移规则清单（共享）+ 自己那组的文件列表
5. 收集 8 份结果，把失败 case 合成一个新列表
6. 对失败 case 串行精修（19 个组件，花了 4 分 20 秒）
7. 跑一次全量测试套件

子 Agent 的 prompt 模板：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

<role>你是一个专门迁移 Chakra UI 1.x → 3.x 的工程师</role>

<rules>
（这里是 15 条迁移规则，共享内容）
</rules>

<task>
对以下 42 个组件，逐个：
1. Read 原文件
2. 按 rules 改写
3. Write 回去
4. 如果你拿不准，跳过并返回文件名到 <unsure> 标签
5. 不要运行测试，主 Agent 会统一跑
</task>

<files>
（文件路径列表）
</files>

返回格式：
<done>成功的文件名</done>
<unsure>有疑问的文件名 + 一句话原因</unsure>

关键设计：

• 共享规则只定义一次，每个子 Agent 都带上，一致性有保障
• 子 Agent 不跑测试，把测试留给主 Agent 统一做，避免并发写入 .vitest-cache 之类问题
• 拿不准的抛回来，不让子 Agent 自作主张——它们的上下文看不到全局

第一次跑 321/340 成功，19 个抛回来。第二轮主 Agent 串行处理，全部过。

主 Agent 和子 Agent 的上下文预算怎么分

这块是新手最容易翻车的地方。

我的分配原则（针对 Opus 4.7，200K 窗口）：

• 主 Agent：工作上下文控制在 50K 以内。这是整个 session 最珍贵的资源，要留给决策、合并、兜底。
• 每个子 Agent：起步 6-10K（system + tools），任务上下文控制在 30K 内。单个任务跑完就丢，不可惜。
• 子 Agent 回传主 Agent 的内容：严格压缩到 2K 以内。这是最容易爆炸的地方——子 Agent 很爱把中间过程贴回来，必须在 prompt 里明令禁止，只返回结论。

那 340 组件迁移里，我每个子 Agent 回传的平均长度是 1847 字符（一个 列表 + 一个 列表）。主 Agent 最后合并 8 份结果总共才 15K 左右，绰绰有余。

对比一下第一版失败方案：最开始我让子 Agent 贴原文 + 改完的文件回主 Agent 供 review。一个子 Agent 回来 23K，8 个就是 184K，直接把主 Agent context 挤爆。学到的教训：子 Agent 不是打工仔，是黑盒，黑盒只输出一行结论。

一个被坑过的点：子 Agent 之间不能通信

这个文档里写得不够显眼。子 Agent 1 干到一半发现个问题，它没法”告诉”子 Agent 3。所有通信必须经过主 Agent。

所以当任务之间存在弱依赖时（比如 “要是组件 A 用了新 API，组件 B 就得跟着改”），要在主 Agent 这一层先扫一遍全局，把依赖图画清楚再分发。别指望子 Agent 自己协调。

想深入理解 agent 之间的通信机制可以翻 MCP Server 内部工具——MCP 某种意义上也是一种”子进程”通信，设计哲学上是相通的。

最后：什么情况下并行反而更慢

我跑过几次并行比串行慢的案例。规律是：

• 任务数 < 5 的时候，主 Agent 编排开销超过并行收益
• 任务本身很快（每个 < 5 秒），并行纯粹是浪费
• 任务之间有隐式共享资源（比如都要访问同一个 API，有 rate limit）

所以我的经验值是：任务数 ≥ 8 且单任务 ≥ 10 秒，才考虑并行。小于这个规模串行就好。

整个 Claude Code 的编排体系其实就是 agent 工程的一个缩影，想把理论打通可以看 Agent SDK 架构，想把 sub-agent 的 context 工程吃透看 Context 预算策略。