<!-- title: 子代理并行:批量活拆开分头干 -->

# 子代理并行:把一份大活拆给 N 个 Agent 分头干

## 概述

本教程教你用 Claude Code 的子代理(Subagent / Task 工具)机制,把一个大型批量任务拆成 N 份、派给 N 个独立上下文的子代理并行执行,再把结果聚总收口。学完你能掌握:子代理的两种形态、并行的四条判据、任务分片策略、子代理 prompt 模板设计、并行派发与兜底、上下文预算分配。适合已经会用 `-p` 模式、想突破"单会话串行慢"瓶颈的中级用户。

## 前置条件

- Claude Code **v2.1.198 及以上**(Explore/Plan 等内置子代理模型继承行为的关键版本)
- 一个 Opus 或 Sonnet 会话(子代理并行对模型推理能力有要求,Haiku 仅适合轻量子任务)
- 基本的命令行与 git 基础,理解上下文窗口(Context Window)概念
- 一个真实存在中等规模文件量的仓库(几十到几百个同类文件最适合验证)

---

## 步骤 1:先认清两套机制——Task 子任务 vs 自定义 subagent

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`):

```markdown
---
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 误触发。描述要写清"什么时候用",不要只写"做什么"。

---

## 步骤 2:判断该不该并行——四条判据

不是所有活都值得拆。并行有编排开销(主 Agent 分发、收集、合并都耗 token 和时间),小任务并行反而更慢。判断标准:

**判据 1:任务之间真的独立。** 改文件 A 不需要看文件 B 的结果。如果有依赖,串行更省。

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

**判据 3:需要不同"心态"做多视角。** 安全视角、性能视角、可维护性视角互相独立,一个 Agent 切来切去会偷懒——尤其到第 3、第 4 个视角就开始敷衍。

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

**反例——这些不能并行:**

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

> **经验阈值**:任务数 **≥ 8 且单任务 ≥ 10 秒**才考虑并行;小于这个规模串行就好。任务数 < 5 时,编排开销通常超过并行收益。

---

## 步骤 3:把任务拆成分片——分片策略

并行的第一步是把活切成互不重叠的 N 份。三种常见策略:

**按目录/路径分片**:最稳。`find` 出文件列表后,按目录分组,每组交给一个子 Agent。物理隔离,几乎不会撞车。

**按哈希取模分片**:当目录分布不均时,用文件路径 hash 后取模,保证每组数量均衡。比如 340 个组件分 8 组,每组 40–43 个。

**按职责/视角分片**:不按文件,按"角色"分。4 个子 Agent 分别从安全、性能、可维护、兼容四个视角 review 同一份 diff。

一个实用的 bash 预分片命令(把文件列表切成 N 份):

```bash
# 找出所有目标文件,按目录排序后均分 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 个文件以内。

---

## 步骤 4:写子代理 prompt 模板——共享规则 + 黑盒输出

这是并行编排成败的关键。子代理的 prompt 必须满足两个原则:

**原则一:共享规则只定义一次。** 所有子 Agent 带同一份规则清单,保证一致性。

**原则二:子代理是黑盒,只输出结论。** 子 Agent 很爱把中间过程贴回主 Agent,这会瞬间挤爆主上下文。必须在 prompt 里明令"只返回结论"。

实战中验证过的 prompt 模板(以批量迁移为例):

```text
<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 自作主张——它们的上下文看不到全局

---

## 步骤 5:在一个消息块里并行派发

并行之所以快,核心在于主 Agent 在**同一条回复里发起多个 Task 工具调用**——这些调用并发执行,而不是排队。

对用户而言,触发并行的三种方式:

**方式 A:自然语言并行指令。** 直接在会话里说:"并行处理 src/components 下 8 个子目录,每个目录交给一个子代理迁移,最后汇总。"主 Agent 会自动在一个块里派 8 个 Task。

**方式 B:显式 @ 调用多个自定义 subagent。** 如果你定义了多个角色 subagent,可以一条消息里同时 `@security-reviewer 帮我审这份 diff` 和 `@perf-reviewer 帮我审这份 diff`,触发并行多视角。

**方式 C:`-p` 模式 + bash 多进程并行。** 这是一种"进程级并行",和子代理并行不同——每个 `claude -p` 是一个独立会话进程,真正吃满多核:

```bash
# 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 这层先扫一遍全局、画清依赖图再分发。

---

## 步骤 6:聚总结果与失败兜底

并行派发完,主 Agent 要做三件事:

1. **收集** N 份结果(每份严格压缩到 2K 以内的结论)
2. **合并去重**,把失败/拿不准的 case 合成一个新列表
3. **串行精修**——这部分故意串行,因为失败 case 往往有共性,需要主 Agent 看全局

真实案例的数据:340 组件第一次跑 **321/340 成功**,19 个抛回来。第二轮主 Agent 串行处理 19 个,花 4 分 20 秒,全部过。

> **为什么兜底要串行**:失败的 case 通常代表规则清单没覆盖的边界情况。串行处理时主 Agent 能看清这 19 个的共性,顺手补规则,而不是让子代理盲目重试。

---

## 步骤 7:上下文预算分配——新手最容易翻车的地方

这一步决定了并行会不会"加速却烧光上下文"。针对 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 个 Markdown 文件补 frontmatter

下面是一个你能在本地立刻复现的小型并行案例。场景:一个文档仓库下有 80 个 `.md` 文件缺少 YAML frontmatter,需要根据文件内容自动补全 `title`、`tags`、`updated` 三个字段。

**第一步:分片**

```bash
find docs -name "*.md" | sort > /tmp/md_all.txt
split -l 10 -d /tmp/md_all.txt /tmp/md_shard_   # 8 份,每份 10 个
```

**第二步:在会话里发起并行指令**

输入给主 Agent:

```text
请并行处理 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 份结论 → 合并跳过列表 → 串行精修 → 输出总报告。

**第四步:验证**

```bash
# 统计补全成功的文件数
grep -rl "^---" docs/ | wc -l
```

**预期效果**:相比串行处理,8 路并行在大约 1/4 到 1/3 的时间完成(不会到 1/8,因为有编排开销和串行兜底)。

---

## Mermaid 流程图:子代理并行编排全流程

```mermaid
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 倍。

---

## 延伸阅读

- [Claude Code 官方文档:创建自定义 subagents](https://code.claude.com/docs/zh-CN/sub-agents) — frontmatter 字段、内置子代理、并行模式、恢复与分叉的权威说明
- [Claude Code 官方文档:Agent view 与运行代理团队](https://code.claude.com/docs/zh-CN/sub-agents) — 跨会话并行与 background agents 的进阶用法
- [Anthropic 工程博客:How and when to use subagents](https://www.anthropic.com/engineering) — 子代理设计哲学与上下文节省原理
- [awesome-claude-code 社区代理包](https://github.com/) — 社区贡献的可复用 subagent 集合

---

## 训练营适用性评估

**适合的营型**:中级进阶营、企业效能提升营、AI 工程实战营。不适合纯入门营——学员需要先掌握基本会话和 `-p` 模式。

**前置衔接**:建议排在"读懂 Agent 循环""自定义 subagent 创建"之后,作为"从单代理到多代理编排"的进阶课。

**预计教学时长**:3–4 学时。其中概念与判据约 1 学时,prompt 模板设计与上下文预算约 1 学时,实战案例(可替换为学员自己仓库的真实批量任务)约 1.5–2 学时。

**考核点**:学员能独立判断一个任务是否值得并行、能写出符合"黑盒输出"原则的子代理 prompt、能解释为什么 8 路并行只得到 3–4 倍加速。

**易踩坑提示(教学重点)**:子代理回传内容挤爆主上下文、子代理并发改 shared state、把有依赖的任务链强行并行——这三个是学员最高频的翻车点,务必用反面案例讲透。

---

## 参考来源

1. [Claude Code 里用子 Agent 做并行任务,实测快了 4.2 倍](https://claude.cocoloop.cn/posts/claude-code-subagents-orchestration/) — 340 组件 Chakra UI 迁移的真实编排案例,含五种分派模式、上下文预算分配、失败并行案例
2. [Claude Code 子代理(Subagents)深度解析:架构、机制与最佳实践](https://www.iceyao.com.cn/2026/04/16/claude-code-subagents-deep-dive/) — 子代理核心概念、五种触发方式、四大实用工作模式(研究/并行/审查/管道)
3. [创建自定义 subagents - Claude Code 官方文档](https://code.claude.com/docs/zh-CN/sub-agents) — 内置 subagents、frontmatter 字段、并行研究模式、前台/后台运行、恢复与分叉的官方规范
4. [Claude Code 并行开发完全指南:Subagents + Agent Teams + Git Worktree + 工作流编排](https://zhuanlan.zhihu.com/p/2033183908523718494) — 子代理、代理团队、worktree 隔离三种并行路径的对比与选型
5. [Claude Code Subagents:.claude/agents 工作流的可视化管理器](https://agentsroom.dev/zh/claude-code-subagents) — subagent 文件结构、隔离上下文委派机制与可视化管理实践

> [!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 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)