文档子代理——AgentsClaude Code 子代理系统 - AI 团队协作模式

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%

相关资源

核心概念详细指南

性能优化

实战应用


掌握 Claude Code 的子代理系统,就像拥有了一个随时待命的 AI 开发团队。合理使用子代理,让 AI 协作的力量为你加速开发进程!

关于我