本教程教你用 Claude Code 的子代理(Subagent / Task 工具)机制,把一个大型批量任务拆成 N 份、派给 N 个独立上下文的子代理并行执行,再把结果聚总收口。学完你能掌握:子代理的两种形态、并行的四条判据、任务分片策略、子代理 prompt 模板设计、并行派发与兜底、上下文预算分配。适合已经会用 -p 模式、想突破"单会话串行慢"瓶颈的中级用户。
Claude Code 里说"子代理"其实有两个含义,背后机制相同(新开一个上下文隔离的 agent 实例),但用法不同:
Task 工具派发的子任务:主 Agent 通过 Task 工具临时调出一个独立 agent 实例,独立上下文,跑完把结果回传,然后销毁,不保留状态。适合一次性、临时的并行。
自定义 subagent:在 .claude/agents/*.md 下定义的专用 agent,有自己的 system prompt、工具白名单、默认模型,可被主 Agent 自动委托,也可被用户用 @<agent-name> 显式调用。适合反复使用的固定角色(如 /test-runner、/reviewer)。
选型建议:大部分并行场景用 Task 就够了——它更轻、更灵活。只有那种"反复调用、固定角色"的才落地成 subagent 文件。本教程的批量并行以 Task 为主。
一个最小可用的自定义 subagent 文件长这样(.claude/agents/migrator.md):
---
name: migrator
description: 专门迁移 Chakra UI 1.x 到 3.x 的工程师。当用户要求批量迁移组件时使用。
tools: Read, Write, Grep, Glob
model: inherit
---
你是一个专门迁移 Chakra UI 1.x → 3.x 的工程师。
严格按迁移规则清单改写组件,拿不准就跳过并报告。
预期结果:文件保存后,在会话里输入
@migrator或描述迁移任务,主 Agent 会自动委托给它。常见问题:描述(description)写得太泛,导致主 Agent 误触发。描述要写清"什么时候用",不要只写"做什么"。
不是所有活都值得拆。并行有编排开销(主 Agent 分发、收集、合并都耗 token 和时间),小任务并行反而更慢。判断标准:
判据 1:任务之间真的独立。 改文件 A 不需要看文件 B 的结果。如果有依赖,串行更省。
判据 2:上下文读取量大但处理可隔离。 比如"读 200 个文件找某个模式",每个子 Agent 只看自己那批,主 Agent 只收结论,不收原文。
判据 3:需要不同"心态"做多视角。 安全视角、性能视角、可维护性视角互相独立,一个 Agent 切来切去会偷懒——尤其到第 3、第 4 个视角就开始敷衍。
判据 4:用户明确说"同时做 X 和 Y"。 这种明面上的并行意图不要违背。
反例——这些不能并行:
package.json 就是灾难)经验阈值:任务数 ≥ 8 且单任务 ≥ 10 秒才考虑并行;小于这个规模串行就好。任务数 < 5 时,编排开销通常超过并行收益。
并行的第一步是把活切成互不重叠的 N 份。三种常见策略:
按目录/路径分片:最稳。find 出文件列表后,按目录分组,每组交给一个子 Agent。物理隔离,几乎不会撞车。
按哈希取模分片:当目录分布不均时,用文件路径 hash 后取模,保证每组数量均衡。比如 340 个组件分 8 组,每组 40–43 个。
按职责/视角分片:不按文件,按"角色"分。4 个子 Agent 分别从安全、性能、可维护、兼容四个视角 review 同一份 diff。
一个实用的 bash 预分片命令(把文件列表切成 N 份):
# 找出所有目标文件,按目录排序后均分 8 份
find src/components -name "*.tsx" | sort > /tmp/all_files.txt
total=$(wc -l < /tmp/all_files.txt)
split -l $(( (total + 7) / 8 )) -d /tmp/all_files.txt /tmp/shard_
ls /tmp/shard_* # shard_00 ~ shard_07
预期结果:得到 8 个分片文件,每个 40–43 行路径。主 Agent 读取这些分片后派发。
常见问题:分片粒度太细(如每组只有 2 个文件),编排开销吃掉收益;太粗(每组 100 个),单子 Agent 上下文爆掉。单组建议控制在 30–50 个文件以内。
这是并行编排成败的关键。子代理的 prompt 必须满足两个原则:
原则一:共享规则只定义一次。 所有子 Agent 带同一份规则清单,保证一致性。
原则二:子代理是黑盒,只输出结论。 子 Agent 很爱把中间过程贴回主 Agent,这会瞬间挤爆主上下文。必须在 prompt 里明令"只返回结论"。
实战中验证过的 prompt 模板(以批量迁移为例):
<role>你是一个专门迁移 Chakra UI 1.x → 3.x 的工程师</role>
<rules>
(15 条迁移规则,所有子 Agent 共享同一份)
1. <Box> 的 shorthand 全部展开
2. emotion import 换成 vanilla extract
3. theme token 命名按新映射表替换
... 共 15 条
</rules>
<task>
对以下 42 个组件,逐个:
1. Read 原文件
2. 按 rules 改写
3. Write 回去
4. 拿不准就跳过,返回文件名到 <unsure> 标签
5. 不要运行测试,主 Agent 会统一跑
</task>
<files>
(本分片的文件路径列表)
</files>
返回格式(严格遵守,禁止贴原文或改后代码):
<done>成功的文件名列表</done>
<unsure>有疑问的文件名 + 一句话原因</unsure>
关键设计点: - 共享规则只定义一次,一致性有保障 - 子 Agent 不跑测试,把测试留给主 Agent 统一做,避免并发写入
.vitest-cache之类的问题 - 拿不准的抛回来,不让子 Agent 自作主张——它们的上下文看不到全局
并行之所以快,核心在于主 Agent 在同一条回复里发起多个 Task 工具调用——这些调用并发执行,而不是排队。
对用户而言,触发并行的三种方式:
方式 A:自然语言并行指令。 直接在会话里说:"并行处理 src/components 下 8 个子目录,每个目录交给一个子代理迁移,最后汇总。"主 Agent 会自动在一个块里派 8 个 Task。
方式 B:显式 @ 调用多个自定义 subagent。 如果你定义了多个角色 subagent,可以一条消息里同时 @security-reviewer 帮我审这份 diff 和 @perf-reviewer 帮我审这份 diff,触发并行多视角。
方式 C:-p 模式 + bash 多进程并行。 这是一种"进程级并行",和子代理并行不同——每个 claude -p 是一个独立会话进程,真正吃满多核:
# 8 个独立 claude 进程,各自处理一个分片,后台并发
for shard in /tmp/shard_*; do
claude -p "按迁移规则处理 $(cat $shard | tr '\n' ' ') 这些文件,只返回成功与失败文件名" \
--output-format json > "/tmp/result_$(basename $shard).json" &
done
wait
# 聚总 8 份 json 结果
两种并行的区别:子代理并行是"单会话内多上下文",共享权限和会话状态,适合需要在主 Agent 这层做协调、兜底的场景;
-p多进程并行是"多会话各自独立",隔离更彻底,适合无人值守的批量任务,但聚总要靠你自己写脚本。常见问题:子代理之间不能直接通信。子 Agent 1 干到一半发现问题,没法"告诉"子 Agent 3,所有通信必须经过主 Agent。所以任务间存在弱依赖时,要在主 Agent 这层先扫一遍全局、画清依赖图再分发。
并行派发完,主 Agent 要做三件事:
真实案例的数据:340 组件第一次跑 321/340 成功,19 个抛回来。第二轮主 Agent 串行处理 19 个,花 4 分 20 秒,全部过。
为什么兜底要串行:失败的 case 通常代表规则清单没覆盖的边界情况。串行处理时主 Agent 能看清这 19 个的共性,顺手补规则,而不是让子代理盲目重试。
这一步决定了并行会不会"加速却烧光上下文"。针对 Opus 4.x、200K 窗口的分配原则:
| 角色 | 上下文预算 | 用途 |
|---|---|---|
| 主 Agent | 控制在 50K 以内 | 决策、合并、兜底——整个 session 最珍贵的资源 |
| 每个子 Agent | 起步 6–10K,任务上下文 30K 内 | 单任务跑完即丢,不可惜 |
| 子 Agent 回传内容 | 严格压缩到 2K 以内 | 最容易爆炸的地方 |
真实案例里,每个子 Agent 回传平均 1847 字符(一个 done 列表 + 一个 unsure 列表)。主 Agent 合并 8 份结果总共才 15K 左右,绰绰有余。
反面教材:第一版方案让子 Agent 贴"原文 + 改后代码"回主 Agent 供 review。一个子 Agent 回来 23K,8 个就是 184K,直接把主 Agent context 挤爆。
核心教训:子 Agent 不是打工仔,是黑盒——黑盒只输出一行结论。
控制子 Agent 回传长度的硬办法:在 prompt 里明确写"返回格式严格遵守,禁止贴原文或改后代码,只返回文件名列表",必要时用 JSON schema 约束输出结构。
下面是一个你能在本地立刻复现的小型并行案例。场景:一个文档仓库下有 80 个 .md 文件缺少 YAML frontmatter,需要根据文件内容自动补全 title、tags、updated 三个字段。
第一步:分片
find docs -name "*.md" | sort > /tmp/md_all.txt
split -l 10 -d /tmp/md_all.txt /tmp/md_shard_ # 8 份,每份 10 个
第二步:在会话里发起并行指令
输入给主 Agent:
请并行处理 docs/ 下 80 个缺失 frontmatter 的 Markdown 文件。
我已把文件列表切成 8 份(/tmp/md_shard_00 ~ _07)。
请派 8 个子代理,每个处理一份,规则如下:
1. 读取每个文件
2. 根据正文第一行和正文内容,生成 title 和 2-4 个 tags
3. updated 字段填今天日期
4. 在文件开头插入 YAML frontmatter,不动正文
5. 拿不准 title 的,跳过并返回文件名
返回格式:只返回成功的文件数和跳过的文件名,禁止贴原文。
最后汇总 8 份结果,对跳过的文件串行精修。
第三步:观察主 Agent 行为
主 Agent 会:读取 8 个分片 → 在一条回复里派 8 个 Task(并发执行)→ 收集 8 份结论 → 合并跳过列表 → 串行精修 → 输出总报告。
第四步:验证
# 统计补全成功的文件数
grep -rl "^---" docs/ | wc -l
预期效果:相比串行处理,8 路并行在大约 1/4 到 1/3 的时间完成(不会到 1/8,因为有编排开销和串行兜底)。
flowchart TD
A["主 Agent 接收批量任务"] --> B{"四条判据检查"}
B -->|独立/量大/≥8个/≥10秒| C["分片策略"]
B -->|不满足| Z["串行处理即可"]
C --> C1["按目录分片"]
C --> C2["按哈希取模"]
C --> C3["按职责视角"]
C1 & C2 & C3 --> D["生成共享规则清单 + prompt 模板"]
D --> E["一条消息块内并行派发 N 个 Task"]
E --> F1["子代理 1<br/>独立上下文 黑盒输出"]
E --> F2["子代理 2<br/>独立上下文 黑盒输出"]
E --> FN["子代理 N<br/>独立上下文 黑盒输出"]
F1 & F2 & FN --> G["主 Agent 收集 N 份结论<br/>每份≤2K"]
G --> H{"有失败/拿不准?"}
H -->|有| I["串行精修<br/>补规则看全局"]
H -->|无| J["统一跑测试/校验"]
I --> J
J --> K["输出总报告"]
style E fill:#fde68a,stroke:#b45309
style G fill:#bfdbfe,stroke:#1e40af
style I fill:#fecaca,stroke:#b91c1c
关键看图中的两个"串行瓶颈":派发(E,虽然并发但主 Agent 有分发开销)和兜底精修(I,故意串行)。这解释了为什么 8 路并行不会得到 8 倍加速,实测通常是 3–4 倍。
适合的营型:中级进阶营、企业效能提升营、AI 工程实战营。不适合纯入门营——学员需要先掌握基本会话和 -p 模式。
前置衔接:建议排在"读懂 Agent 循环""自定义 subagent 创建"之后,作为"从单代理到多代理编排"的进阶课。
预计教学时长:3–4 学时。其中概念与判据约 1 学时,prompt 模板设计与上下文预算约 1 学时,实战案例(可替换为学员自己仓库的真实批量任务)约 1.5–2 学时。
考核点:学员能独立判断一个任务是否值得并行、能写出符合"黑盒输出"原则的子代理 prompt、能解释为什么 8 路并行只得到 3–4 倍加速。
易踩坑提示(教学重点):子代理回传内容挤爆主上下文、子代理并发改 shared state、把有依赖的任务链强行并行——这三个是学员最高频的翻车点,务必用反面案例讲透。
[!tip] 51学通信知识星球 星主：爱卫生（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 星球定位：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 当前规模：5200 篇主题 / 990 个回答，198 元/年。 加入福利：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 AI 加持：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。