第03章｜分而治之：Sub-Agents 的核心概念与应用价值

第03章｜分而治之：Sub-Agents 的核心概念与应用价值

学习目标：理解 Sub-Agent（子代理）的本质、工作原理和适用场景，掌握何时使用子代理来提升任务执行效率。

3.1 为什么需要 Sub-Agents？

单一 Agent 的局限性

想象你是一个项目经理，需要同时完成：

1. 分析需求文档

2. 设计数据库 Schema

3. 编写后端 API

4. 编写前端页面

5. 编写测试用例

6. 更新项目文档

   如果你一个人串行完成，效率低下。更好的方式是分配给不同的团队成员并行执行。

   Sub-Agents 就是 Claude Code 的"团队成员"。

单 Agent vs 多 Agent 对比

单 Agent 模式（串行）： ┌─────────────────────────────────────────────────────┐ │ 主 Agent │ │ 任务1 → 任务2 → 任务3 → 任务4 → 任务5 │ │ 总耗时 = T1 + T2 + T3 + T4 + T5 │ └─────────────────────────────────────────────────────┘ 多 Agent 模式（并行）： ┌─────────────────────────────────────────────────────┐ │ 主 Agent（协调者） │ │ ↓ 派发任务 │ │ ┌────────┐ ┌────────┐ ┌────────┐ │ │ │子Agent1│ │子Agent2│ │子Agent3│ │ │ │ 任务1 │ │ 任务2 │ │ 任务3 │ │ │ └────────┘ └────────┘ └────────┘ │ │ ↓ 汇总结果 │ │ 总耗时 ≈ max(T1, T2, T3) │ └─────────────────────────────────────────────────────┘

3.2 Sub-Agent 的本质

技术定义

Sub-Agent 是由主 Agent 通过Agent工具派生出的独立 Claude 实例，具有以下特征：

┌─────────────────────────────────────────────────────┐ │ Sub-Agent 特征 │ │ │ │ ✅ 独立的上下文窗口（与主 Agent 隔离） │ │ ✅ 独立的工具调用能力 │ │ ✅ 可以访问文件系统和执行命令 │ │ ✅ 完成任务后将结果返回给主 Agent │ │ ❌ 不共享主 Agent 的对话历史 │ │ ❌ 不能直接与用户交互 │ │ ❌ 生命周期由主 Agent 控制 │ └─────────────────────────────────────────────────────┘

上下文隔离的重要性

主 Agent 上下文： - 用户的完整对话历史 - 项目全局信息 - 任务协调逻辑 - 各子 Agent 的结果摘要 子 Agent 上下文： - 主 Agent 给的任务描述 - 完成任务所需的最小信息 - 任务执行过程 - 最终结果

为什么隔离很重要？

• 避免上下文污染（子任务的细节不会干扰主任务）
• 每个子 Agent 可以专注于自己的任务
• 并行执行时互不干扰
• 节省 Token（子 Agent 不需要知道其他子 Agent 的工作）

3.3 Sub-Agent 的工作原理

Agent 工具调用

主 Agent 通过调用Agent工具来派生子 Agent：

// 主 Agent 的工具调用（内部机制，用户不直接写这个）{"tool":"Agent","parameters":{"task":"分析 src/auth.py 文件，找出所有潜在的安全漏洞，以 JSON 格式返回结果","context":"这是一个 FastAPI 项目，使用 JWT 认证","allowed_tools":["Read","Bash"],"timeout":120}}

完整执行流程

用户：帮我对整个项目做安全审计 主 Agent： 1. 分析任务，决定拆分为3个子任务 2. 派生子 Agent A：审计认证模块 3. 派生子 Agent B：审计数据库操作 4. 派生子 Agent C：审计 API 输入验证 5. 等待所有子 Agent 完成 6. 汇总结果，生成综合报告 7. 返回给用户 子 Agent A（独立运行）： 1. 读取 src/auth/ 目录下的文件 2. 分析 JWT 实现 3. 检查密码哈希算法 4. 返回：["发现弱密码策略", "JWT 过期时间过长"] 子 Agent B（独立运行）： 1. 读取 src/repositories/ 目录 2. 检查 SQL 注入风险 3. 检查参数化查询使用情况 4. 返回：["发现1处潜在 SQL 注入", "建议使用参数化查询"] 子 Agent C（独立运行）： 1. 读取 src/api/ 目录 2. 检查输入验证逻辑 3. 检查文件上传安全 4. 返回：["文件上传缺少类型验证", "缺少请求大小限制"]

3.4 Sub-Agent 的三种模式

模式1：只读型（Read-Only）

子 Agent 只能读取信息，不能修改任何内容。

适用场景：

• 代码审计

• 文档分析

• 数据统计

• 问题诊断

  配置方式：

任务描述中明确说明： "只读取和分析，不要修改任何文件"

案例：

主 Agent 派发任务： "读取 src/ 目录下所有 Python 文件，统计： 1. 总代码行数 2. 函数数量 3. 类数量 4. 注释覆盖率 只读取，不要修改任何文件，以 JSON 格式返回统计结果"

模式2：执行型（Executor）

子 Agent 可以读写文件、执行命令，完成具体的实现任务。

适用场景：

• 代码生成

• 文件批量处理

• 自动化测试

• 数据转换

  案例：

主 Agent 派发任务： "在 tests/unit/ 目录下，为 src/services/user_service.py 中的每个公共方法创建对应的单元测试。 使用 pytest 框架，mock 所有外部依赖。 测试文件命名为 test_user_service.py"

模式3：验证型（Verifier）

子 Agent 专门用于验证其他子 Agent 的工作成果。

适用场景：

• 代码质量检查

• 测试结果验证

• 文档完整性检查

  案例：

主 Agent 工作流： 1. 子 Agent A：生成代码 2. 子 Agent B（验证型）：运行测试，检查代码质量 3. 如果验证失败，子 Agent A 修复问题 4. 重复直到验证通过

3.5 何时使用 Sub-Agents？

适合使用的场景

✅ 场景1：任务可以并行化

❌ 不适合并行（有依赖关系）： 步骤1：设计数据库 Schema 步骤2：根据 Schema 生成 ORM 模型（依赖步骤1） 步骤3：根据 ORM 模型写 Repository（依赖步骤2） ✅ 适合并行（相互独立）： 任务A：为用户模块写单元测试 任务B：为订单模块写单元测试 任务C：为支付模块写单元测试

✅ 场景2：任务需要专业化分工

主 Agent：协调整体任务 子 Agent A：专注于安全审计（只看安全相关代码） 子 Agent B：专注于性能分析（只看性能相关代码） 子 Agent C：专注于代码规范（只看代码风格）

✅ 场景3：任务范围超出单一上下文

大型项目有1000个文件，单个 Agent 无法全部加载 → 拆分为多个子 Agent，每个负责一个模块 → 主 Agent 汇总各模块的分析结果

✅ 场景4：需要隔离风险

子 Agent 在沙箱中执行危险操作 → 即使出错也不影响主 Agent 的状态 → 主 Agent 可以选择是否采用子 Agent 的结果

不适合使用的场景

❌ 场景1：简单的单步任务

❌ 过度设计： 用户：帮我把变量名 `usr` 改成 `user` 主 Agent：派生子 Agent 来完成这个修改... ✅ 直接执行： 主 Agent：直接修改文件

❌ 场景2：任务之间有强依赖

❌ 不适合并行： 子 Agent A：生成 API 接口 子 Agent B：根据 API 接口生成前端代码（必须等A完成） ✅ 串行执行： 主 Agent：先完成 API，再生成前端代码

3.6 实战案例：代码库全面分析

需求

对一个中型 Python 项目（约200个文件）进行全面分析，包括：

• 代码质量评估
• 安全漏洞扫描
• 性能瓶颈识别
• 文档完整性检查

实现方案

用户输入：

对我们的项目进行全面分析，包括代码质量、安全性、性能和文档完整性， 生成一份综合报告

主 Agent 的执行计划：

主 Agent 思考： 这个任务可以拆分为4个独立的分析任务，并行执行效率更高 派发4个子 Agent： 子 Agent 1 - 代码质量分析： 任务：运行 pylint 和 flake8，分析代码质量问题 工具：Bash（运行分析工具）、Read（读取配置） 输出：代码质量报告 JSON 子 Agent 2 - 安全漏洞扫描： 任务：运行 bandit，检查常见安全漏洞 工具：Bash（运行 bandit）、Read（读取代码） 输出：安全漏洞列表 JSON 子 Agent 3 - 性能分析： 任务：识别潜在的性能问题（N+1查询、无索引查询等） 工具：Read（读取代码） 输出：性能问题列表 JSON 子 Agent 4 - 文档检查： 任务：检查所有公共函数是否有 docstring 工具：Bash（运行 pydocstyle）、Read 输出：文档覆盖率报告 JSON 主 Agent 汇总： 收集4个子 Agent 的结果 生成综合 Markdown 报告 保存到 reports/analysis-2026-06-21.md

综合报告示例输出

# 项目全面分析报告 生成时间：2026-06-21 ## 执行摘要 | 维度 | 评分 | 状态 | |------|------|------| | 代码质量 | 7.2/10 | ⚠️ 需改进 | | 安全性 | 8.5/10 | ✅ 良好 | | 性能 | 6.8/10 | ⚠️ 需改进 | | 文档完整性 | 45% | ❌ 较差 | ## 代码质量（子 Agent 1 结果） - 发现 23 个 pylint 警告 - 主要问题：函数过长（>50行）12处，未使用变量 8处 ## 安全漏洞（子 Agent 2 结果） - 发现 2 个中危漏洞 - 发现 5 个低危漏洞 - 主要问题：使用了不安全的 MD5 哈希 ## 性能问题（子 Agent 3 结果） - 发现 3 处 N+1 查询问题 - 发现 2 处缺少数据库索引 ## 文档完整性（子 Agent 4 结果） - 公共函数总数：156 - 有 docstring：70（45%） - 缺少 docstring：86（55%）

3.7 Sub-Agent 的限制与注意事项

成本考虑

每个子 Agent 都是独立的 Claude API 调用，会产生额外的 Token 消耗：

单 Agent 完成任务：消耗 X tokens 使用3个子 Agent：消耗约 3X tokens（每个子 Agent 有自己的上下文） 权衡： ✅ 并行执行节省时间 ❌ 增加 Token 成本 建议：只在任务真正需要并行化时使用子 Agent

结果质量控制

子 Agent 的输出质量需要主 Agent 验证：

最佳实践： 1. 要求子 Agent 以结构化格式（JSON）返回结果 2. 主 Agent 验证结果的完整性和合理性 3. 对关键任务，使用验证型子 Agent 二次确认

任务描述要清晰

❌ 模糊的任务描述： "分析一下代码" ✅ 清晰的任务描述： "读取 src/auth/ 目录下的所有 .py 文件， 检查以下安全问题： 1. 密码是否使用安全的哈希算法（bcrypt/argon2） 2. JWT 密钥是否从环境变量读取 3. 是否有 SQL 注入风险 以 JSON 格式返回：{issues: [{file, line, severity, description}]}"

3.8 本章小结

🧪 动手练习

练习1：体验子代理派发

# 在一个有多个模块的项目中，让 Claude Code 并行分析claude-p"分析这个项目的每个模块（src/ 下的每个子目录）， 为每个模块生成一个简短的功能说明， 最后汇总成一个 modules.md 文件"

练习2：观察并行执行

# 开启 verbose 模式，观察子 Agent 的派发过程claude--verbose# 输入需要并行处理的任务用户：同时为 user_service.py、order_service.py、 payment_service.py 各生成一个单元测试文件

练习3：设计子代理任务

思考你当前项目中，哪些任务适合用子代理并行处理？
写下你的设计方案：

任务：[描述你的任务] 拆分方案： 子 Agent 1：[负责什么] 子 Agent 2：[负责什么] 子 Agent 3：[负责什么] 并行化理由：[为什么这些任务可以并行]

⬅️ 上一章：第02章 - 记忆系统与 CLAUDE.md
➡️ 下一章：第04章 - 从 Sub-Agents 到 Multi-Agent 工程指南