【Claude】Claude Code 子代理（Subagents）完全指南：多 AI 编排与并行任务管理

---

前言

当你在 Claude Code 中处理一个大型任务——比如"重构整个认证模块并补充测试"——单个 Claude 实例往往力不从心：上下文越来越长、响应越来越慢、任务交织在一起难以追踪。

子代理（Subagents） 是 Claude Code 的并行化解决方案。它允许主代理将子任务分派给独立的 AI 实例处理，每个子代理拥有自己的上下文窗口、工具权限和会话状态，完成后将结果汇报给主代理。

本文基于 Claude Code v2.1+，全面讲解子代理的使用方法、内置类型、自定义配置以及多代理编排模式。

---

一、问题现象：单代理的瓶颈

1.1 单 Claude 实例的三大瓶颈

瓶颈一：上下文膨胀

任务：重构认证模块 + 补充测试 + 更新文档

单代理流程：
  读取 8 个源文件 → 修改代码 → 读取测试文件 → 写测试 → 读取文档 → 更新文档
  
  上下文不断增长，到第 6 个文件时：
  - 响应速度明显变慢
  - Claude 开始"忘记"前面的设计决策
  - Token 消耗指数增长

瓶颈二：任务交织

Claude 同时处理代码修改和测试编写：
  改了 auth.py → 开始写 test_auth.py → 发现需要再改 auth.py 
  → 回去改 auth.py → 测试又需要更新 → 循环...
  
  没有清晰的职责分离，容易顾此失彼

瓶颈三：无法并行

三个独立的子任务：
  1. 分析 API 性能瓶颈
  2. 编写安全审计报告  
  3. 生成 API 文档

这三个任务互不依赖，但单代理只能串行处理。
理想情况：三个 AI 同时工作，3 倍速完成。

1.2 子代理如何解决

主代理（你对话的 Claude）
  ├── 分派任务1 → 子代理A（独立上下文，只读权限）
  ├── 分派任务2 → 子代理B（独立上下文，读写权限）
  └── 分派任务3 → 子代理C（独立上下文，测试工具权限）

三个子代理并行工作，各自的结果汇总给主代理
主代理整合结果，返回给你

---

二、核心概念：子代理的工作原理

2.1 什么是子代理

子代理是在独立上下文窗口中运行的专用 AI 助手，具有以下特点：

特性	主代理	子代理
上下文窗口	与你对话的主上下文	完全独立的上下文
工具权限	拥有所有工具	可自定义限制
生命周期	整个会话	完成任务后结束
通信方式	直接对话	结果返回给主代理
模型	继承主会话设置	可指定不同模型

2.2 子代理的执行流程

你 → 主代理：分析这个项目的安全风险和性能瓶颈

主代理决策：
  这可以拆成两个独立任务 → 分派给两个子代理

  → 子代理A（安全审计）
      独立上下文：读取代码 → 分析安全漏洞 → 生成报告
      返回结果给主代理

  → 子代理B（性能分析）  
      独立上下文：读取代码 → 分析性能瓶颈 → 生成报告
      返回结果给主代理

主代理整合两个子代理的结果 → 返回给你综合报告

2.3 子代理 vs Agent Teams

特性	Subagents	Agent Teams
协作方式	单向汇报（结果返回主代理）	多向通信（队友间互发消息）
独立性	完全独立，不互相通信	可以讨论和协调
复杂度	低	中
适合场景	专注型任务，只需结果	需要讨论与协作的复杂工作
启用方式	内置，无需配置	需要实验开关

---

三、内置子代理一览

Claude Code 开箱即用以下内置子代理：

3.1 Explore（探索代理）

属性	值
模型	Claude Haiku（快速、低成本）
权限	只读（Read/Grep/Glob）
触发场景	搜索代码库、查找文件、理解项目结构

典型用途：

你：这个项目的认证逻辑在哪里？

主代理 → 分派 Explore 子代理：
  "搜索项目中与认证相关的文件和代码"

Explore 子代理（Haiku 模型，快速搜索）：
  - grep "auth" --include="*.py"
  - 读取找到的文件
  - 返回：发现 src/auth/middleware.py 是核心认证逻辑...

主代理返回结果给你

3.2 Plan（规划代理）

属性	值
模型	继承主会话
权限	只读
触发场景	Plan 模式下收集上下文

3.3 general-purpose（通用代理）

属性	值
模型	继承主会话
权限	全部工具
触发场景	复杂多步骤任务

典型用途：

你：帮我重构 src/utils/ 目录，提取公共函数到 src/shared/

主代理 → 分派 general-purpose 子代理：
  "重构 src/utils/ 目录，提取公共函数到 src/shared/"
  
子代理（拥有完整工具权限）：
  - 读取所有 utils 文件
  - 识别公共函数
  - 创建 src/shared/ 目录
  - 移动和重构代码
  - 更新所有引用
  - 返回结果：已重构 12 个文件，提取了 8 个公共函数

主代理返回结果给你

4.4 自定义子代理

你可以创建专属子代理，指定模型、工具权限和系统提示。

4.4.1 配置文件位置

.claude/agents/               # 项目级自定义子代理
~/.claude/agents/             # 全局级自定义子代理

4.4.2 配置文件格式

每个子代理是一个 Markdown 文件：

<!-- .claude/agents/security-auditor.md -->
---
name: security-auditor
model: claude-sonnet-20241022
allowedTools:
  - Read
  - Grep
  - Glob
---

你是一个安全审计专家。你的职责是分析代码中的安全风险。

## 审计维度
1. SQL 注入、XSS、CSRF
2. 认证与授权漏洞
3. 敏感信息泄露
4. 输入验证缺失
5. 依赖安全

## 输出格式
按严重程度分类：
- 🔴 高危：必须立即修复
- 🟡 中危：建议尽快修复
- 🟢 低危：可以计划修复

每个问题包含：文件路径、行号、问题描述、修复建议。

4.4.3 调用自定义子代理

在对话中，Claude 会根据任务自动选择合适的子代理。你也可以显式指定：

你：用 security-auditor 子代理审查 src/api/ 目录

---

五、多代理编排模式

5.1 模式一：Fan-out（扇出）

主代理将多个独立子任务分派给不同子代理，并行处理：

你：帮我完成以下任务：
  1. 审查 src/api/ 的安全性
  2. 分析 src/db/ 的查询性能
  3. 检查 src/utils/ 的代码质量

主代理（Fan-out 模式）：
  → security-auditor 子代理（安全审查）
  → performance-analyzer 子代理（性能分析）
  → code-reviewer 子代理（质量检查）

三个子代理并行工作...
各自返回报告...

主代理整合三份报告：
  安全：2个高危问题
  性能：3个 N+1 查询
  质量：5个命名不规范

返回综合报告给你

适合场景： 多个维度独立分析同一份代码

5.2 模式二：Pipeline（流水线）

子代理按顺序处理，前一个的输出是后一个的输入：

你：帮我实现一个用户导出功能，从设计到实现到测试

主代理（Pipeline 模式）：
  Step 1 → architect 子代理（设计方案）
     输出：API 设计、数据流、文件结构

  Step 2 → implementer 子代理（编码实现）
     输入：architect 的设计方案
     输出：已实现的代码

  Step 3 → tester 子代理（编写测试）
     输入：implementer 的代码
     输出：测试代码 + 测试结果

主代理返回最终成果

适合场景： 有明确阶段划分的任务

5.3 模式三：Specialist（专家咨询）

主代理遇到特定领域问题时，咨询专家子代理：

你：这段并发代码有竞争条件，帮我修复

主代理：
  分析代码 → 发现涉及并发安全
  
  咨询 concurrency-expert 子代理：
    "分析这段代码的竞争条件，给出修复方案"
  
  子代理（拥有并发安全专家提示）：
    深度分析 → 返回修复方案
  
主代理：根据专家建议执行修复

适合场景： 需要特定领域专业知识的任务

---

六、Agent View：多代理可视化管理

Claude Code v2.1.139 引入了 Agent View，统一管理所有并行会话：

6.1 查看所有运行中的子代理

在 Claude Code 交互界面中按 Ctrl+T（或特定快捷键），可以看到：

╔══════════════════════════════════════════════╗
║  Agent View - 活跃子代理                      ║
╠══════════════════════════════════════════════╣
║  🔄 security-auditor    [运行中]              ║
║     任务：审查 src/api/ 安全性                ║
║     已运行：45s                              ║
║                                              ║
║  🔄 performance-analyzer [运行中]             ║
║     任务：分析 src/db/ 查询性能               ║
║     已运行：32s                              ║
║                                              ║
║  ✅ code-reviewer       [已完成]              ║
║     任务：检查 src/utils/ 代码质量             ║
║     结果：发现 5 个问题（3 P1, 2 P2）         ║
╚══════════════════════════════════════════════╝

6.2 查看子代理的详细输出

选择某个子代理可以查看其详细工作过程：

• 读取了哪些文件
• 执行了哪些命令
• 中间推理过程
• 最终输出结果

---

七、Dynamic Workflows：动态工作流

Claude Code 2026年5月推出的 Dynamic Workflows 让 Claude 能自己编写多 Agent 编排逻辑：

7.1 什么是 Dynamic Workflows

不再需要你手动指定用哪个子代理、按什么顺序执行——Claude 会根据任务复杂度自动决定：

你：帮我做一个完整的代码质量提升任务

Claude 自动决策：
  评估任务复杂度 → 需要工作流
  
  自动编写编排逻辑：
  1. 并行启动 3 个 Explore 子代理（分别扫描不同目录）
  2. 汇总结果后，启动 Plan 子代理设计方案
  3. 方案确认后，启动 2 个 general-purpose 子代理并行实施
  4. 实施完成后，启动 tester 子代理验证
  
  全程自动编排，无需你干预

7.2 启用方式

# 通过 effort 级别激活
/effort ultracode

# 或设置环境变量
export CLAUDE_CODE_DYNAMIC_WORKFLOWS=1

---

八、实战案例：完整功能开发流

8.1 任务描述

你：帮我实现一个"用户数据导出"功能，要求：
  1. 支持 CSV 和 JSON 两种格式
  2. 支持按日期范围筛选
  3. 大数据量时支持流式导出
  4. 需要完整的单元测试
  5. 更新 API 文档

8.2 Claude 的自动编排

主代理分析：
  这是一个中等复杂度的任务，可以拆分为：
  - 设计阶段（Plan 模式）
  - 实现阶段（编码）
  - 测试阶段（测试编写）
  - 文档阶段（文档更新）

Step 1：Plan 子代理设计方案
  输出：
  - 新文件：src/api/export.py, src/services/export_service.py
  - 修改文件：src/routes/api.py（添加路由）
  - 测试文件：tests/test_export.py

Step 2：general-purpose 子代理实现代码
  输入：Plan 子代理的设计方案
  输出：已创建/修改 4 个文件

Step 3：general-purpose 子代理编写测试
  输入：已实现的代码
  输出：tests/test_export.py（12个测试用例）

Step 4：Explore 子代理更新文档
  输入：新 API 的接口信息
  输出：已更新 docs/api.md

主代理汇总：
  ✅ 功能实现完成
  ✅ 12个测试全部通过
  ✅ 文档已更新
  修改文件列表：...

---

九、子代理配置最佳实践

9.1 模型选择策略

子代理类型	推荐模型	原因
Explore（搜索）	Haiku	快速、低成本，搜索不需要深度推理
Plan（规划）	Sonnet	需要一定推理能力，但不需要最强
Code Review（审查）	Sonnet/Opus	需要深度分析能力
Implementation（实现）	Sonnet	日常编码足够
Testing（测试）	Haiku/Sonnet	测试编写相对直接
Documentation（文档）	Haiku	文档生成不需要深度推理

9.2 工具权限最小化原则

<!-- 安全审计子代理：只读权限 -->
---
allowedTools:
  - Read
  - Grep
  - Glob
---

<!-- 实现子代理：需要写权限 -->
---
allowedTools:
  - Read
  - Write
  - Edit
  - Bash
---

<!-- 测试子代理：需要执行测试 -->
---
allowedTools:
  - Read
  - Write
  - Bash
---

原则： 只授予子代理完成其任务所需的最小权限，避免意外修改。

9.3 系统提示编写技巧

子代理的系统提示应当包含：

1. 角色定义：你是做什么的专家
2. 任务范围：只做什么，不做什么
3. 输出格式：期望的输出结构
4. 注意事项：特定的约束或规则

<!-- .claude/agents/test-writer.md -->
---
name: test-writer
model: claude-sonnet-20241022
allowedTools:
  - Read
  - Write
  - Bash
---

你是一个测试工程师专家。你的唯一任务是编写高质量的单元测试。

## 规则
- 每个测试只验证一件事
- 测试名称：test_[功能]_[条件]_[期望结果]
- 使用 Mock 隔离外部依赖
- 覆盖正常路径、边界条件、异常路径

## 禁止
- 不要修改被测代码（只能读）
- 不要修改非测试文件
- 不要运行除测试以外的命令

## 输出
1. 先列出测试计划（覆盖哪些场景）
2. 然后给出完整测试代码
3. 最后运行测试并报告结果

---

十、常见问题

Q：子代理会消耗额外的 Token 吗

是的。每个子代理有独立的上下文窗口，消耗单独计算。但总体来看：

单代理处理3个任务（串行）：
  任务1(5K) + 任务2(5K+5K历史) + 任务3(5K+10K历史) = 30K tokens

3个子代理并行处理：
  子代理A(5K) + 子代理B(5K) + 子代理C(5K) + 汇总(2K) = 17K tokens

节省：43%

子代理避免了历史对话积累，反而更省 Token。

Q：子代理能访问主代理的对话历史吗

不能。子代理的上下文是完全独立的，它只看到主代理分派任务时给的信息。

如果子代理需要某些上下文，主代理需要在分派时明确提供。

Q：如何知道 Claude 是否使用了子代理

• 在 Claude Code 界面中，子代理的工作会以缩进或特殊标记显示
• 按 Ctrl+T 打开 Agent View 查看活跃子代理
• /tasks 命令可以查看任务分配情况

Q：子代理失败了怎么办

主代理会收到子代理的失败信息，可以：

1. 重试（重新分派给同一子代理）
2. 换一个子代理
3. 自己接手处理

你也可以在 Agent View 中看到失败状态，手动干预。

---

十一、避坑清单

1. 不要过度拆分：每个子任务太小反而增加调度开销，建议每个子代理任务至少需要 3+ 步操作

2. 注意子代理间的数据一致性：如果两个子代理同时修改相关文件，可能产生不一致——尽量让修改同一区域的任务由同一子代理处理

3. 自定义子代理需要测试：创建后先用简单任务验证其行为，确保系统提示有效

4. 模型选择影响成本：Haiku 子代理成本极低，善用它处理简单任务

5. 不要在子代理中做需要用户交互的操作：子代理是自治的，无法暂停等待用户输入

---

总结

子代理是 Claude Code 从"单一 AI 助手"进化为"AI 开发团队"的核心能力：

• 内置子代理（Explore、Plan、general-purpose）覆盖大多数场景
• 自定义子代理让你为特定领域创建专家
• Fan-out / Pipeline / Specialist 三种编排模式满足不同需求
• Agent View 提供可视化管理和进度追踪
• Dynamic Workflows 让 Claude 自己决定编排策略

当任务复杂到单个 Claude 实例难以高效处理时，就是该启用子代理的时候了。