Claude Code: 子代理（SubAgent）
最后更新：2026-08-31
子代理让 Claude Code 变成一个"团队管理者"——主代理分解任务，子代理并行执行，效率成倍提升。
💡 提示：子代理不是多开几个 Claude Code 实例，而是单个 Claude Code 会话内部的并行执行机制。主代理负责规划和协调，子代理负责具体执行。
📋 前置知识：第十二章 MCP
1. 你将学到
- 子代理的工作原理
- 何时使用子代理
- 并行任务执行
- 代理间协作模式
- 调度与资源管理
2. 子代理工作原理
(1) 架构模型
graph TB
M[主代理<br/>规划+协调] --> S1[子代理1<br/>前端重构]
M --> S2[子代理2<br/>后端API]
M --> S3[子代理3<br/>测试编写]
S1 --> R[结果汇总]
S2 --> R
S3 --> R
| 角色 | 职责 | 上下文 |
|---|---|---|
| 主代理 | 理解需求、分解任务、汇总结果 | 全局上下文 |
| 子代理 | 执行具体子任务 | 局部上下文 |
(2) 执行流程
TEXT
📖 仅展示
1. 用户下达复杂任务
2. 主代理分解为独立子任务
3. 为每个子任务创建子代理
4. 子代理并行执行（各自独立的上下文）
5. 主代理汇总所有子代理结果
6. 检查一致性，处理冲突
7. 输出最终结果
▶ 示例 1: 子代理自动触发
TEXT
📖 仅展示
> 给项目添加完整的用户管理模块：
> 数据模型、API 接口、前端页面、测试
Claude Code (主代理):
任务分解：
- 子任务1: 创建数据模型 (User model + migration)
- 子任务2: 创建 API 接口 (CRUD endpoints)
- 子任务3: 创建前端页面 (用户管理界面)
- 子任务4: 编写测试 (集成测试 + 单元测试)
[启动4个子代理并行执行]
子代理1: ✅ 数据模型创建完成
子代理2: ✅ API 接口创建完成
子代理3: ✅ 前端页面创建完成
子代理4: ✅ 测试编写完成
主代理: 汇总结果，检查接口一致性...
→ 发现 API 返回格式与前端预期不一致
→ 自动修正前端 API 调用
→ 运行全量测试
✅ All 24 tests passed
3. 何时使用子代理
(1) 适用场景
| 场景 | 是否适合子代理 | 原因 |
|---|---|---|
| 多文件独立修改 | ✅ 适合 | 各文件修改互不影响 |
| 前后端并行开发 | ✅ 适合 | 独立技术栈 |
| 批量测试编写 | ✅ 适合 | 每个测试文件独立 |
| 单文件深度重构 | ❌ 不适合 | 不需要并行 |
| 顺序依赖任务 | ❌ 不适合 | 无法并行执行 |
| 小修改 | ❌ 不适合 | 开销大于收益 |
(2) 触发方式
TEXT
📖 仅展示
# 自动触发：任务足够复杂时 Claude Code 自动使用子代理
> 重构整个项目的错误处理
# 手动触发：明确要求并行
> 并行处理：给每个 service 写测试
# 禁用子代理：简单任务不需要
> 只修改这一个函数
4. 并行任务执行
(1) 并行策略
TEXT
📖 仅展示
# Alice 让 Claude Code 并行修复多个 Bug
> 并行修复以下 Bug：
> 1. src/auth/jwt.ts: token 刷新逻辑错误
> 2. src/utils/date.ts: 时区处理问题
> 3. src/api/orders.ts: 分页参数验证缺失
> 4. src/services/payment.ts: 金额精度问题
Claude Code 启动 4 个子代理：
子代理1 [jwt.ts] → ✅ 修复完成 (2min)
子代理2 [date.ts] → ✅ 修复完成 (3min)
子代理3 [orders.ts] → ✅ 修复完成 (1min)
子代理4 [payment.ts] → ✅ 修复完成 (4min)
总耗时: 4min (串行需 10min)
节省: 60%
▶ 示例 2: 批量操作并行化
TEXT
📖 仅展示
> 为 src/services/ 下所有 8 个 service 补充测试
Claude Code:
检测到 8 个独立任务，启动并行模式...
子代理1: email.service.test.ts ✅ (5 tests)
子代理2: user.service.test.ts ✅ (8 tests)
子代理3: order.service.test.ts ✅ (7 tests)
子代理4: payment.service.test.ts ✅ (6 tests)
子代理5: search.service.test.ts ✅ (4 tests)
子代理6: auth.service.test.ts ✅ (9 tests)
子代理7: notification.service.ts ✅ (3 tests)
子代理8: report.service.test.ts ✅ (5 tests)
汇总: 47 个新测试，全部通过 ✓
5. 代理间协作
(1) 协作模式
| 模式 | 说明 | 适用场景 |
|---|---|---|
| 完全独立 | 子代理间无交互 | 批量独立任务 |
| 共享规范 | 共享 CLAUDE.md 和代码风格 | 团队约定一致 |
| 结果整合 | 主代理整合子代理结果 | 需要一致性检查 |
| 迭代协作 | 子代理输出作为另一个的输入 | 有依赖关系 |
(2) 冲突处理
TEXT
📖 仅展示
# 子代理可能产生冲突
子代理1 修改了 user.types.ts
子代理2 也修改了 user.types.ts
主代理检测到冲突：
→ 对比两个修改
→ 合并不冲突的部分
→ 冲突部分保留更完整的版本
→ 运行测试验证合并结果
6. 调度与资源管理
(1) 资源消耗
| 维度 | 单代理 | 子代理（4个） |
|---|---|---|
| API 调用 | 串行 | 并行 |
| Token 消耗 | 100K | 4 × 30K = 120K |
| 时间 | 10 min | 3 min |
| 成本 | $2.00 | $2.40 |
(2) 调度优化
TEXT
📖 仅展示
# 控制并行度
> 最多使用2个子代理并行处理
# 优先级调度
> 先处理 payment.service（最关键），
> 然后并行处理其他 service
# 资源限制
> 控制子代理上下文大小，每个不超过 50K tokens
▶ 示例 3: 大型项目并行策略
TEXT
📖 仅展示
# Alice 的 SaaS 项目大重构
> 将整个项目从 REST 迁移到 GraphQL，
> 按模块并行处理：
> 1. 用户模块
> 2. 订单模块
> 3. 支付模块
> 4. 通知模块
> 每个模块独立迁移，最后整合
Claude Code:
启动 4 个子代理，每个处理一个模块...
每个子代理：
- 读取对应模块文件
- 将 REST 路由转为 GraphQL resolver
- 修改数据获取方式
- 编写对应测试
整合阶段（主代理）：
- 合并 schema 定义
- 统一错误处理
- 运行全量测试
✅ All 134 tests passed
❓ 常见问题
Q 子代理会自动触发吗？
A 会。Claude Code 检测到任务可并行时自动使用子代理。也可以在指令中明确要求并行。
Q 子代理的数量有限制吗？
A 没有硬性限制，但每个子代理消耗独立上下文和 API 调用。建议不超过 5-6 个并行，避免资源消耗过大。
Q 子代理间能通信吗？
A 不能直接通信。它们通过主代理间接协调——主代理分配任务、汇总结果、处理冲突。
Q 并行执行会冲突吗？
A 可能。修改同一文件时可能冲突。主代理会检测并解决冲突，但建议并行任务操作不同文件。
Q 子代理比串行执行更贵吗？
A Token 总消耗略高（约 10-20%），但时间大幅缩短（约 50-70%）。时间敏感场景推荐并行。
Q 如何禁用子代理？
A 指令中明确要求串行执行，或任务足够简单时 Claude Code 不会使用子代理。
📖 小节
- 子代理是 Claude Code 内部的并行执行机制
- 主代理分解任务，子代理并行执行，主代理汇总结果
- 适合多文件独立修改、批量操作、前后端并行开发
- 不适合顺序依赖任务和简单修改
- 并行节省时间但略增成本，注意冲突处理
📝 作业
- 基础题（难度⭐）：给 Claude Code 一个可并行的任务，观察子代理的自动触发和执行过程。
- 进阶题（难度⭐⭐）：设计一个场景，让 Claude Code 并行处理 4 个独立模块，对比串行和并行的时间差异。
- 挑战题（难度⭐⭐⭐）：分析子代理并行时的 Token 消耗和成本，总结在什么情况下并行更划算。
