第03章分而治之Sub-Agents 的核心概念与应用价值学习目标理解 Sub-Agent子代理的本质、工作原理和适用场景掌握何时使用子代理来提升任务执行效率。3.1 为什么需要 Sub-Agents单一 Agent 的局限性想象你是一个项目经理需要同时完成分析需求文档设计数据库 Schema编写后端 API编写前端页面编写测试用例更新项目文档如果你一个人串行完成效率低下。更好的方式是分配给不同的团队成员并行执行。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 - 性能分析 任务识别潜在的性能问题N1查询、无索引查询等 工具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 处 N1 查询问题 - 发现 2 处缺少数据库索引 ## 文档完整性子 Agent 4 结果 - 公共函数总数156 - 有 docstring7045% - 缺少 docstring8655%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 本章小结核心概念要点Sub-Agent 本质主 Agent 派生的独立 Claude 实例上下文隔离三种模式只读型审计、执行型实现、验证型检查适用场景可并行任务、专业化分工、超大范围任务核心优势并行执行、上下文隔离、专注度高注意事项增加 Token 成本、需要清晰的任务描述 动手练习练习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 工程指南