Claude Code 子代理系统指南
Claude Code 最强大的功能之一是它的子代理(Sub-Agents)系统。通过子代理,你可以让 AI 同时处理多个任务,或者让专门的子代理处理特定类型的工作,实现真正的”AI 团队协作”。
🚀 核心理念:就像人类团队中不同角色各司其职,子代理让不同的 AI 专注于各自的专长,协同完成复杂任务。
子代理系统概述
什么是子代理
子代理是 Claude Code 中的独立 AI 实例,每个子代理都有自己的:
- 🎯 专门任务:处理特定类型的工作
- 🧠 独立上下文:有自己的工作记忆和思考过程
- 🔄 并发执行:多个子代理可以同时工作
- 📊 结果汇总:主代理整合所有子代理的结果
为什么需要子代理
单一 AI 的局限:
- ⏱️ 串行处理:一次只能做一件事
- 📊 上下文限制:复杂任务容易迷失方向
- 🎯 专长不足:通用 AI 在特定领域不够深入
子代理团队的优势:
- ✅ 并行处理:多个任务同时进行,效率提升 3-5 倍
- ✅ 专精专长:每个子代理专注于自己的领域
- ✅ 结构化思维:复杂任务分解为简单子任务
- ✅ 容错能力:单个子代理失败不影响整体
子代理的应用场景
最适合使用子代理的场景:
| 场景描述 | 子代理分工 | 效率提升 |
|---|---|---|
| 大型代码库分析 | 不同子代理分析不同模块 | 5x |
| 多技术栈集成 | 每个子代理专注一种技术 | 4x |
| 全面代码审查 | 多个子代理从不同角度审查 | 3x |
| 并行测试生成 | 不同测试类型同时生成 | 6x |
| 文档和代码同步 | 文档和代码分别处理 | 3x |
核心概念详解
🛠️ 任务子代理工具
核心内容:了解 Claude Code 内置的任务子代理类型和各自的专长。
内置子代理类型
Claude Code 提供了多种专门化的子代理,每个都有独特的工具集和能力:
Explore 代理 - 代码库探索专家
擅长任务:
- 快速浏览和理解大型代码库
- 查找特定功能或模式的实现
- 分析代码架构和依赖关系
- 生成代码导航和可视化
工具能力:
- Glob:模式匹配查找文件
- Grep:内容搜索和代码查询
- Read:读取文件内容
- 无执行权限:只读探索,不修改代码
使用场景:
# 让 Explore 代理分析代码库
请用 Explore 代理帮我找到所有与用户认证相关的代码子代理选择决策树
任务类型判断
├── 只需要读取代码?
│ └── 是 → Explore 代理
├── 需要架构设计?
│ └── 是 → Plan 代理
├── 需要执行命令?
│ └── 是 → Bash 代理
└── 需要综合处理?
└── 是 → 通用代理🤖 子代理系统
核心内容:深入理解子代理的工作原理、通信机制和最佳实践。
子代理的生命周期
子代理创建
触发条件:
- 主代理明确请求子代理处理任务
- 并行任务需求(多个任务同时进行)
- 专门化任务需求(特定类型的工作)
创建参数:
# 子代理创建示例
sub_agent = create_agent(
type="explore", # 子代理类型
task="分析认证模块", # 具体任务
context={ # 上下文信息
"module": "auth",
"focus": "security"
},
tools=["glob", "grep"] # 可用工具
)任务执行
执行模式:
- 独立执行:子代理完全自主完成
- 协作执行:与主代理保持沟通
- 并行执行:多个子代理同时工作
通信机制:
# 主代理与子代理通信
main_agent.send(
to=sub_agent,
message="找到认证中间件了吗?"
)
# 子代理响应
sub_agent.respond(
to=main_agent,
message="找到了,在 src/auth/middleware.ts"
)结果汇总
汇总方式:
- 子代理完成后返回结果
- 主代理整合所有子代理的输出
- 生成统一的结论或建议
子代理终止
终止条件:
- 任务完成
- 超时限制
- 主代理主动取消
- 遇到无法处理的错误
多子代理协作模式
并行协作模式:
主代理
├── 子代理 A:分析前端代码
├── 子代理 B:分析后端代码
└── 子代理 C:分析数据库设计
↓
主代理汇总:生成架构分析报告流水线协作模式:
主代理
├── 子代理 A:探索代码库
↓ 传递发现
├── 子代理 B:设计方案
↓ 传递方案
└── 子代理 C:实施代码专家协作模式:
主代理(协调者)
├── 安全专家子代理:审查安全性
├── 性能专家子代理:优化性能
├── 测试专家子代理:生成测试
└── 文档专家子代理:编写文档🎯 子代理优先设计
核心思想:在设计解决方案时,优先考虑如何使用子代理来实现,而不是单打独斗。
子代理优先的设计原则
💡 设计原则:任何可以分解的任务,都应该考虑使用子代理。就像人类团队协作一样,合理分工能带来效率的质的飞跃。
原则 1:任务分解优先
面对复杂任务,首先思考:
- 这个任务可以分解成哪些子任务?
- 哪些子任务可以并行处理?
- 哪些子任务需要专门化技能?
原则 2:并行优先
如果多个子任务相互独立:
- 创建多个子代理并行处理
- 等待所有子代理完成
- 汇总所有结果
原则 3:专精优先
对于需要专门知识的任务:
- 使用专门化的子代理类型
- 让子代理专注于自己的领域
- 避免让通用代理处理所有事情
原则 4:通信最小化
子代理之间的通信应该:
- 明确:清晰传达需求和期望
- 必要:只传递必要的信息
- 结构化:使用统一的格式
子代理优先的设计流程
任务分析
识别子任务:
## 原始任务:重构用户认证系统
### 子任务分解
1. 分析现有认证代码
2. 研究最佳实践
3. 设计新架构
4. 实施新代码
5. 编写测试
6. 更新文档子代理分配
分配策略:
# 子代理分配方案
sub_agents = {
"代码分析": ExploreAgent(focus="auth"),
"最佳实践": ExploreAgent(
task="搜索认证模式",
sources=["github", "docs"]
),
"架构设计": PlanAgent(),
"代码实施": GeneralAgent(),
"测试生成": GeneralAgent(task="测试"),
"文档编写": GeneralAgent(task="文档")
}协作设计
协作流程:
## 并行阶段 1
- 代码分析 ← → 最佳实践研究
(两个子代理同时工作)
## 串行阶段 2
- 代码分析 + 最佳实践 → 架构设计
(汇总分析结果进行设计)
## 并行阶段 3
- 代码实施 ← → 测试生成 ← → 文档编写
(三个子代理同时工作)执行监控
监控要点:
- 每个子代理的进度
- 子代理之间的依赖关系
- 是否需要干预或调整
🔧 自定义子代理
核心内容:创建符合你特定需求的自定义子代理,扩展 Claude Code 的能力。
何时需要自定义子代理
内置子代理不够用的场景:
- 需要特定的工具组合
- 需要特殊的行为模式
- 需要与特定服务集成
- 需要领域特定的知识
自定义子代理创建
基本结构:
# 自定义子代理定义
class CustomAgent:
def __init__(self, config):
self.name = config["name"]
self.tools = config["tools"]
self.system_prompt = config["system_prompt"]
self.behavior = config["behavior"]
def execute(self, task, context):
# 1. 理解任务
understanding = self.understand(task)
# 2. 制定计划
plan = self.plan(understanding)
# 3. 执行任务
result = self.perform(plan, context)
# 4. 返回结果
return self.format_result(result)实战示例:代码审查子代理:
# 专门的代码审查子代理
code_review_agent = {
"name": "代码审查专家",
"system_prompt": """你是一位资深的代码审查专家。
你的职责是:
1. 检查代码质量和可读性
2. 识别潜在的性能问题
3. 发现安全漏洞
4. 建议最佳实践
5. 提供具体的改进建议
你总是:
- 建设性批评
- 提供具体示例
- 考虑上下文
- 尊重团队风格""",
"tools": ["read", "grep"],
"behavior": {
"review_style": "thorough",
"focus_areas": [
"security",
"performance",
"maintainability"
],
"output_format": "markdown"
}
}子代理模板库
常用自定义子代理模板:
测试工程师子代理
test_engineer = {
"name": "测试工程师",
"system_prompt": """你是测试专家,专注于生成全面的测试用例。
关注点:
- 单元测试覆盖率
- 边界条件测试
- 错误场景处理
- 集成测试设计
输出格式:
- 测试用例清单
- Mock 数据设计
- 断言说明""",
"tools": ["read", "write"],
"specialization": "testing"
}子代理最佳实践
实践原则
1. 合理使用子代理
⚠️ 避免滥用:不是所有任务都需要子代理。简单任务直接处理更高效。
适合子代理:
- ✅ 大型代码库分析(500+ 文件)
- ✅ 并行独立任务(3+ 个子任务)
- ✅ 专门化需求(特定领域知识)
- ✅ 复杂架构设计
不需要子代理:
- ❌ 单文件修改
- ❌ 简单查询
- ❌ 快速原型
2. 子代理数量控制
推荐的子代理数量:
- 小型任务:1-2 个子代理
- 中型任务:3-5 个子代理
- 大型任务:5-10 个子代理
过多子代理的问题:
- 协调成本增加
- 通信复杂度上升
- 调试难度加大
3. 明确子代理职责
职责分配原则:
- 每个子代理有明确的职责范围
- 避免职责重叠
- 确保完整覆盖任务需求
职责定义示例:
## 子代理职责分配
### 前端分析子代理
- 职责:分析前端代码
- 范围:src/frontend/
- 输出:前端架构报告
### 后端分析子代理
- 职责:分析后端代码
- 范围:src/backend/
- 输出:后端架构报告
### 数据库分析子代理
- 职责:分析数据库设计
- 范围:database/
- 输出:数据库设计报告实战案例
案例:大型项目代码审查
任务背景:
- 项目规模:1000+ 文件
- 审查目标:全面代码质量审查
- 时间限制:1 周
子代理方案:
# 代码审查子代理团队
code_review_team = {
"安全审查": SecurityAgent(),
"性能审查": PerformanceAgent(),
"测试审查": TestCoverageAgent(),
"文档审查": DocumentationAgent(),
"风格审查": CodeStyleAgent()
}
# 并行执行
results = parallel_execute(
agents=code_review_team,
context=project_context
)
# 汇总报告
report = consolidate(results)实施效果:
- 审查时间:从 2 周缩短到 3 天
- 问题发现:增加 40%(多角度审查)
- 覆盖率:从 60% 提升到 95%
相关资源
核心概念详细指南
- 🛠️ 任务子代理工具 - 内置子代理类型详解
- 🤖 子代理系统 - 子代理工作原理
- 🎯 子代理优先设计 - 设计原则和流程
- 🔧 自定义子代理 - 创建自定义子代理
性能优化
实战应用
- 🔄 探索-规划-编码工作流 - 使用子代理的完整工作流
- 🔧 MCP 服务器配置 - 扩展子代理能力
掌握 Claude Code 的子代理系统,就像拥有了一个随时待命的 AI 开发团队。合理使用子代理,让 AI 协作的力量为你加速开发进程!