【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特性SubagentsAgent 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个 N1 查询 质量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 交互界面中按CtrlT或特定快捷键可以看到╔══════════════════════════════════════════════╗ ║ 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_WORKFLOWS1八、实战案例完整功能开发流8.1 任务描述你帮我实现一个用户数据导出功能要求 1. 支持 CSV 和 JSON 两种格式 2. 支持按日期范围筛选 3. 大数据量时支持流式导出 4. 需要完整的单元测试 5. 更新 API 文档8.2 Claude 的自动编排主代理分析 这是一个中等复杂度的任务可以拆分为 - 设计阶段Plan 模式 - 实现阶段编码 - 测试阶段测试编写 - 文档阶段文档更新 Step 1Plan 子代理设计方案 输出 - 新文件src/api/export.py, src/services/export_service.py - 修改文件src/routes/api.py添加路由 - 测试文件tests/test_export.py Step 2general-purpose 子代理实现代码 输入Plan 子代理的设计方案 输出已创建/修改 4 个文件 Step 3general-purpose 子代理编写测试 输入已实现的代码 输出tests/test_export.py12个测试用例 Step 4Explore 子代理更新文档 输入新 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 系统提示编写技巧子代理的系统提示应当包含角色定义你是做什么的专家任务范围只做什么不做什么输出格式期望的输出结构注意事项特定的约束或规则!-- .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(5K5K历史) 任务3(5K10K历史) 30K tokens 3个子代理并行处理 子代理A(5K) 子代理B(5K) 子代理C(5K) 汇总(2K) 17K tokens 节省43%子代理避免了历史对话积累反而更省 Token。Q子代理能访问主代理的对话历史吗不能。子代理的上下文是完全独立的它只看到主代理分派任务时给的信息。如果子代理需要某些上下文主代理需要在分派时明确提供。Q如何知道 Claude 是否使用了子代理在 Claude Code 界面中子代理的工作会以缩进或特殊标记显示按CtrlT打开 Agent View 查看活跃子代理/tasks 命令可以查看任务分配情况Q子代理失败了怎么办主代理会收到子代理的失败信息可以重试重新分派给同一子代理换一个子代理自己接手处理你也可以在 Agent View 中看到失败状态手动干预。十一、避坑清单不要过度拆分每个子任务太小反而增加调度开销建议每个子代理任务至少需要 3 步操作注意子代理间的数据一致性如果两个子代理同时修改相关文件可能产生不一致——尽量让修改同一区域的任务由同一子代理处理自定义子代理需要测试创建后先用简单任务验证其行为确保系统提示有效模型选择影响成本Haiku 子代理成本极低善用它处理简单任务不要在子代理中做需要用户交互的操作子代理是自治的无法暂停等待用户输入总结子代理是 Claude Code 从单一 AI 助手进化为AI 开发团队的核心能力内置子代理Explore、Plan、general-purpose覆盖大多数场景自定义子代理让你为特定领域创建专家Fan-out / Pipeline / Specialist三种编排模式满足不同需求Agent View提供可视化管理和进度追踪Dynamic Workflows让 Claude 自己决定编排策略当任务复杂到单个 Claude 实例难以高效处理时就是该启用子代理的时候了。