Claude Subagents 是 Claude Code 中的多代理架构功能,通过将复杂任务委托给在并行中运行、具有隔离上下文窗口的专业工作代理来实现分布式 AI 处理。这种编排器-工作者模式克服了单代理上下文窗口限制的根本性局限,在复杂任务上实现了 90% 以上的性能提升。

通过将大问题分解为由多个子代理同时处理的离散子任务,Claude Code 可以执行传统单线程方法无法完成的全面代码审查、深度研究和多维分析。

核心功能

1. 编排器-工作者架构

主代理(编排器)执行战略规划和任务分解,生成多个子代理(工作者),它们以独立的 256K 上下文窗口并行执行。结果被压缩和聚合,防止上下文污染同时实现大规模并行处理能力。

2. 专业化子代理类型

不同的子代理类型针对特定任务优化:Explore 用于代码库研究,Plan 用于战略设计,general-purpose 用于灵活操作,claude-code-guide 用于文档查询。每种类型都有针对最大效率定制的能力和工具访问权限。

3. 后台执行

子代理通过 run_in_background 参数在后台非阻塞运行,允许主代理在子代理处理时继续工作。多个子代理同时执行,大幅减少复杂操作的总完成时间。

4. 上下文隔离

每个子代理使用隔离的 256K 上下文窗口操作,处理详细信息而不污染主代理的上下文。子代理返回压缩摘要(数百个 tokens)而不是完整记录(数千个 tokens),为综合保持清洁的上下文。

5. 结果聚合

TaskOutput 工具检索已完成的子代理结果,SubagentStop hooks 在完成时触发以进行验证,主代理将发现综合成连贯的最终输出 - 将分布式处理与统一的用户体验相结合。

6. 并行处理能力

为独立的子任务同时启动多个子代理:安全扫描 + 性能审计 + 测试覆盖 + 样式检查并行运行而不是顺序运行。横向扩展使处理以前单代理限制下不可能的问题成为可能。

适用场景

谁应该使用子代理?

企业开发团队:跨超出单个上下文窗口的大型代码库进行全面代码审查
安全审计员:需要并行漏洞扫描、依赖性检查和合规验证的多维安全分析
ML/AI 工程师:同时测试多个配置排列的复杂实验管道
DevOps 专业人员:并行分析数十个服务、配置和部署管道的基础设施审计
技术研究人员:需要从多个代码库、文档源和仓库综合的深入调查

解决的问题

上下文窗口限制:单代理方法在大型任务上达到 256K token 限制 - 子代理通过并行上下文窗口提供有效无限的容量
顺序瓶颈:传统工作流逐个处理文件 - 并行子代理将完成时间从分钟减少到秒
上下文污染:中间工作细节使主对话变得混乱 - 子代理只返回基本发现,保持清洁的综合上下文
全面分析:单线程无法彻底审查 50+ 个文件 - 多个子代理各自分析部分并聚合完整覆盖
时间关键操作:部署前的代码审查不能等待顺序处理 - 并行执行提供即时的全面结果

子代理类型和能力

Explore 子代理

目的:深度代码库探索和架构研究

能力:

跨大型代码库系统地读取文件
关系和依赖性映射
架构理解
压缩摘要生成

使用案例示例: 用户:"研究身份验证实现" Explore 子代理:读取 20+ 个文件,追踪流程返回:"使用 JWT + OAuth2,核心逻辑在 auth/service.ts:120,token 刷新问题在 245 行,会话验证漏洞在 892 行" 主代理上下文:~500 tokens vs 50K+ 原始

Plan 子代理

目的:战略规划和多步骤工作流设计

能力:

将复杂问题分解为实施步骤
架构决策分析
路线图创建
权衡评估

使用案例示例: 用户:"计划从 REST 迁移到 GraphQL" Plan 子代理:分析现有 API,设计迁移策略,识别风险返回:具有具体步骤的分阶段实施计划

General-Purpose 子代理

目的:不需要专业化时的灵活任务委托

能力:

完整工具访问(Read、Write、Edit、Bash 等)
通用问题解决
适应多样化任务
默认后备选项

使用案例示例: 委托不需要专业知识的独立研究、测试或自动化任务。

claude-code-guide 子代理

目的:文档和最佳实践咨询

能力:

官方 Claude Code 文档访问
Skills、Hooks、Plugins 指导
Claude Agent SDK 专业知识
Claude API 使用模式

使用案例示例: 用户:"如何创建自定义 Skills?" claude-code-guide:检索官方文档,提供带示例的逐步指导。

生命周期和管理

启动子代理

通过 Task 工具:

Task(
    description="分析安全漏洞",
    prompt="扫描所有与身份验证相关的文件以查找安全问题",
    subagent_type="Explore",
    run_in_background=True  # 非阻塞执行
)

自动生成: 主代理根据任务复杂性、上下文限制或并行处理优势决定何时委托。

监控和控制

TaskOutput 工具:从已完成的后台子代理检索结果 SubagentStop Hook:子代理完成时执行验证脚本 实时状态:对话更新显示子代理进度 错误处理:失败的子代理向主代理报告问题以进行恢复

生命周期事件

UserPromptSubmit:用户发起请求
主代理决策:确定委托需求
PreToolUse:子代理生成之前
子代理执行:具有独立上下文的隔离工作
SubagentStop:完成通知(Hook 触发)
PostToolUse:结果集成后
Stop:整体会话完成

性能和成本考虑

性能改进

单代理基线:

顺序处理:文件 A → B → C → ... → 上下文溢出
时间:大型任务需要分钟
完整性:由于限制通常不完整

多代理性能:

并行处理:子代理 1-N 同时进行
时间:复杂任务几秒钟(90%+ 改进)
完整性:通过横向扩展实现全面覆盖

成本分析

Token 消耗:与单代理方法相比 15 倍

单代理任务:1x 基线
多代理等效:15x tokens
但实现 90%+ 性能提升

成本合理时:

✅ 高价值企业决策
✅ 关键安全审计
✅ 深度技术研究
✅ 时间敏感的全面审查
✅ 单线程不可能的问题

应避免时:

❌ 简单文件编辑
❌ 代码补全
❌ 日常对话
❌ 预算受限操作
❌ 顺序依赖工作流

有效上下文容量

单代理:256K 理论,<256K 实际(上下文退化) 多代理:256K × N 个子代理有效 主代理:通过压缩摘要维护清洁上下文

与 Claude Code 生态系统的集成

Skills 集成:

Skills 为主代理和子代理提供知识
子代理使用 Skills 的专业知识执行
结合:智能分布式处理

Hooks 集成:

SubagentStop hook 验证子代理完成
PreToolUse/PostToolUse hooks 监控委托
执行适用于主代理和子代理

Plugins 集成:

插件打包子代理使用的 Skills
MCP 服务器提供外部工具访问
完整工作流利用多代理架构

MCP 协议:

每个子代理可以独立访问 MCP 服务器
并行外部工具查询(GitHub + JIRA + Slack 同时)
未来:通过开放标准实现跨工具子代理共享

真实成功案例

Sionic AI - ML 训练管道

每天在 GPU 集群上运行 1000+ 个实验,Sionic AI 使用子代理:

选择硬件配置(NVIDIA A100 x8 集群)
设置框架参数(ms-swift + vLLM + DeepSpeed)
自动避免 20+ 个记录的失败路径

结果:通过并行配置验证使实验效率倍增。

企业代码审查

财富 500 强公司审查微服务代码库(50+ 个服务):

安全子代理:漏洞扫描 → 12 个关键发现
性能子代理:瓶颈分析 → 8 个优化机会
测试子代理:覆盖率报告 → 平均 78%
样式子代理:合规检查 → 45 个违规

30 秒内完成 vs 顺序 10+ 分钟。

Deep Research(Anthropic 产品)

Claude 的 Deep Research 功能使用子代理:

同时查询多个文档源
聚合不同代码库的发现
综合全面的技术报告
将数千个 tokens 压缩为可操作的摘要

最佳实践

任务分解策略

清晰边界:定义不重叠的子代理职责
并行思维:明确识别独立子任务
成功标准:预先指定预期输出
工具权限:对每个子代理应用最小权限原则
错误恢复:规划子代理失败和重试策略

上下文管理

主代理职责:

高层战略和综合
最小 token 消耗
子代理输出的质量控制
用户沟通

子代理职责:

战术执行和细节工作
隔离上下文中的全面分析
只返回关键发现(压缩)
工具密集型操作

成本优化

启用多代理时:

结果价值 >> 15x 成本
时间节省证明费用合理
单线程不可能进行复杂分析
并行执行提供关键优势

优化通过:

精确的子代理范围划分(避免重叠)
结果压缩(只返回基本内容)
选择性委托(并非每个任务都需要子代理)
并行设计(最大化并发执行)

常见问题

何时应该使用子代理 vs 直接工具调用?

对于超出单个上下文窗口的复杂任务、并行处理优势或中间细节会使主对话变得混乱时使用子代理。对于简单操作、顺序工作流或成本敏感任务使用直接工具调用。

子代理是否与主代理共享上下文?

不,每个子代理都有隔离的上下文。这防止了污染,但需要显式信息传递。主代理提供指令,子代理返回压缩的发现。

子代理可以生成自己的子代理吗?

基于当前架构,子代理是执行任务的工作者。分层生成会引入复杂性,但不是标准模式。编排器-工作者仍然是主要模型。

可以并行运行多少个子代理?

没有记录的硬限制,但实际限制包括成本(每个子代理 15x)、任务分解粒度和收益递减。典型:全面任务使用 3-6 个子代理。

子代理是否可以访问所有工具?

取决于子代理类型。Explore 侧重于读取/搜索,general-purpose 拥有完整工具集。可以为安全性和效率配置访问权限。

如何调试失败的子代理?

SubagentStop hooks 捕获完成事件,TaskOutput 显示结果/错误,主代理报告子代理失败。日志提供用于故障排除的执行详细信息。

替代方案

如果多代理架构不合适:

单代理顺序处理:简单任务的传统方法,成本更低
外部编排:LangChain、AutoGPT 等工具用于自定义多代理模式
手动分解:自己分解任务,单独提交给 Claude
竞争对手多代理工具:AI 开发领域的新兴替代方案

总结

Claude Subagents 代表 AI 辅助开发的根本性架构进步,应用分布式系统原理克服单代理限制。编排器-工作者模式通过智能分解、并行执行和结果压缩实现处理以前不可能的任务。

虽然 15 倍的 token 成本很重要,但 90%+ 的性能改进以及通过并行上下文窗口处理有效无限信息的能力使子代理对于高价值、复杂操作至关重要。与 Skills、Hooks 和 MCP 的集成创建了一个完整的可编程多代理平台,其中控制、规模和智能相结合,解决单线程方法根本无法处理的问题。

Claude Subagents