Claude Code Subagent 子代理指南

什么是 Subagent

Subagent (子代理) 是 Claude Code 的专业化 AI 代理,通过 Agent 工具启动,拥有独立的上下文窗口,专注于特定任务。

核心概念

类比理解: 主代理像项目经理,子代理像专业工程师

主代理: 统筹全局,分配任务
子代理: 专注领域,独立执行
并行协作: 多个子代理同时工作

价值

| 对比维度 | 单一代理 | 多代理协作 | |----------|---------|-----------| | 效率 | 串行处理 | 并行处理 | | 专业性 | 通用能力 | 领域专家 | | 上下文 | 共享窗口 | 独立窗口 | | 适用场景 | 简单任务 | 复杂项目 |

快速开始

基本使用

启动单个子代理:

请开一个 code-reviewer 子代理,检查这次改动的代码质量

并行启动多个子代理:

并行开两个子代理:
1. backend-developer 检查后端接口
2. frontend-developer 检查前端样式

子代理定义位置

| 位置 | 作用域 | 优先级 | |------|--------|--------| | .claude/agents/ | 项目级 | 高 | | ~/.claude/agents/ | 用户级 | 低 |

查看可用代理

在 Claude Code 中输入:

/agents

官方子代理机制

Agent 工具

Claude Code 内置的 Agent 工具用于启动子代理。

工作流程:

主代理识别任务
    ↓
调用 Agent 工具
    ↓
启动子代理(独立上下文)
    ↓
子代理执行任务
    ↓
返回结果给主代理

子代理定义文件

子代理通过 .md 文件定义,包含角色、能力和行为规范。

基本结构:

# Agent Name

## Role
简短描述代理的角色和职责

## Capabilities
- 能力1
- 能力2
- 能力3

## Guidelines
- 行为准则1
- 行为准则2

## Examples
具体使用示例

创建自定义子代理

步骤 1: 创建定义文件

创建 .claude/agents/api-reviewer.md:

# API Reviewer

## Role
API 设计和实现审查专家,专注于 RESTful API 最佳实践。

## Capabilities
- 审查 API 端点设计
- 检查 HTTP 状态码使用
- 验证请求/响应格式
- 评估错误处理机制
- 检查 API 文档完整性

## Guidelines
- 遵循 RESTful 设计原则
- 确保 API 版本控制策略
- 验证认证和授权机制
- 检查速率限制和缓存策略
- 评估 API 性能和可扩展性

## Examples
审查 `/api/v1/users` 端点:
- 检查 HTTP 方法使用是否正确
- 验证状态码 (200, 201, 400, 404, 500)
- 确认响应格式一致性
- 评估错误消息清晰度

步骤 2: 使用自定义代理

请用 api-reviewer 代理检查我的用户管理 API

社区代理资源

VoltAgent 代理集合

VoltAgent 提供了丰富的社区代理定义,可选择性安装。

安装方式:

# 克隆仓库
git clone https://github.com/VoltAgent/awesome-claude-code-subagents.git
cd awesome-claude-code-subagents

# 运行安装脚本
./install-agents.sh

或快捷安装:

curl -sO https://raw.githubusercontent.com/VoltAgent/awesome-claude-code-subagents/main/install-agents.sh
chmod +x install-agents.sh
./install-agents.sh

常用代理类别

1. 核心开发

backend-developer: 服务器端开发专家
frontend-developer: UI/UX 开发专家
fullstack-developer: 全栈开发专家
api-designer: API 架构设计专家

2. 语言专家

python-pro: Python 生态系统专家
typescript-pro: TypeScript 开发专家
rust-engineer: Rust 系统编程专家
golang-pro: Go 并发编程专家

3. 基础设施

devops-engineer: CI/CD 和自动化专家
kubernetes-expert: 容器编排专家
cloud-architect: 云架构设计专家
database-admin: 数据库管理专家

4. 质量与安全

code-reviewer: 代码质量审查专家
security-auditor: 安全漏洞检测专家
qa-automation-engineer: 测试自动化专家
performance-engineer: 性能优化专家

5. 数据与 AI

ai-engineer: AI 系统设计专家
ml-engineer: 机器学习专家
data-engineer: 数据管道架构师
data-scientist: 数据分析专家

实战场景

场景 1: 代码审查

需求: 全面审查代码变更

并行启动三个审查代理:
1. code-reviewer - 检查代码质量和最佳实践
2. security-auditor - 检查安全漏洞
3. performance-engineer - 检查性能问题

场景 2: 全栈开发

需求: 同时开发前后端功能

并行开发:
1. backend-developer - 实现 REST API
2. frontend-developer - 实现用户界面
3. qa-automation-engineer - 编写集成测试

场景 3: 系统重构

需求: 大规模代码重构

分工协作:
1. refactoring-expert - 制定重构方案
2. backend-developer - 重构后端代码
3. frontend-developer - 重构前端代码
4. qa-automation-engineer - 更新测试用例

场景 4: 问题诊断

需求: 排查生产问题

并行诊断:
1. debugging-expert - 分析错误日志
2. performance-engineer - 检查性能瓶颈
3. database-admin - 检查数据库查询
4. devops-engineer - 检查基础设施

Agent Teams (实验性)

什么是 Agent Teams

Agent Teams 是多代理团队协作功能,支持代理间通信和任务共享。

与普通 Subagent 的区别:

| 特性 | 普通 Subagent | Agent Teams | |------|--------------|-------------| | 协作模式 | 一对一 | 多对多 | | 任务管理 | 独立 | 共享任务列表 | | 通信方式 | 返回结果 | 代理间通信 | | 生命周期 | 任务完成退出 | 持续运行 |

启用 Agent Teams

设置环境变量:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

使用示例

组建开发团队:
1. Team Lead - 协调任务分配
2. Backend Developer - 开发 API
3. Frontend Developer - 开发界面
4. QA Engineer - 编写测试

要求团队成员通过共享任务列表协作

核心概念

Team Lead: 团队领导,分配任务和协调进度
Teammate: 团队成员,执行任务并汇报
TaskList: 共享任务列表,实时同步进度
SendMessage: 代理间通信机制

最佳实践

1. 合理选择代理

原则:

任务边界清晰 → 使用子代理
需要协作 → 使用 Agent Teams
简单任务 → 主代理直接处理

2. 控制并行数量

建议:

2-3 个代理: 适中,效率高
4-5 个代理: 较多,需要协调
6+ 个代理: 过多,管理复杂

3. 明确任务边界

好的任务分配:

✅ backend-developer: 实现用户认证 API
✅ frontend-developer: 实现登录界面
✅ qa-engineer: 编写认证流程测试

不好的任务分配:

❌ developer1: 做一些后端工作
❌ developer2: 帮忙看看前端
❌ developer3: 处理其他事情

4. 注意 Token 消耗

消耗计算:

每个子代理 = 独立上下文窗口
3 个并行代理 ≈ 3x Token 消耗
建议按需启动,及时关闭

5. 定期同步进度

协作模式:

主代理定期检查子代理进度
子代理主动汇报关键节点
遇到阻塞及时沟通

常见问题

Q: 子代理和主代理有什么区别?

主代理: 统筹全局,分配任务
子代理: 专注领域,独立执行

Q: 如何选择使用哪个代理?

根据任务类型选择:

代码审查 → code-reviewer
安全检查 → security-auditor
性能优化 → performance-engineer
API 设计 → api-designer

Q: 可以同时启动多少个子代理?

理论上无限制,但建议:

2-3 个: 最佳效率
4-5 个: 需要协调
6+ 个: 管理复杂

Q: 子代理之间可以通信吗?

普通 Subagent: 不能直接通信
Agent Teams: 支持代理间通信

Q: 如何创建自定义代理?

在 .claude/agents/ 创建 .md 文件
定义角色、能力、准则
使用 /agents 查看
通过名称调用

Q: VoltAgent 是官方的吗?

不是,VoltAgent 是社区维护的第三方代理集合。

Q: Agent Teams 稳定吗?

当前是实验性功能,需要显式启用。

故障排查

子代理无法启动

检查清单:

代理定义文件是否存在
文件格式是否正确
代理名称是否正确
使用 /agents 确认可用

子代理执行缓慢

可能原因:

任务过于复杂
上下文窗口过大
并行代理过多

解决方案:

拆分任务
减少上下文
控制并行数量

代理间协作混乱

建议:

明确任务边界
定期同步进度
使用 Agent Teams
主代理统一协调

配置示例

项目级代理配置

创建 .claude/agents/project-reviewer.md:

# Project Reviewer

## Role
项目代码审查专家,熟悉本项目架构和规范。

## Capabilities
- 审查代码符合项目规范
- 检查架构一致性
- 验证测试覆盖率
- 评估文档完整性

## Project Context
- 技术栈: Next.js + FastAPI + PostgreSQL
- 代码规范: ESLint + Black
- 测试要求: 70% 覆盖率
- 文档要求: JSDoc + Docstring

## Guidelines
- 确保符合项目架构设计
- 验证 API 接口一致性
- 检查数据库迁移脚本
- 评估性能影响

用户级代理配置

创建 ~/.claude/agents/my-reviewer.md:

# My Code Reviewer

## Role
个人代码审查助手,按照我的偏好审查代码。

## Capabilities
- 检查代码风格
- 评估可读性
- 建议重构方案
- 识别潜在问题

## My Preferences
- 偏好函数式编程
- 注重代码简洁性
- 重视错误处理
- 强调类型安全

## Guidelines
- 优先建议而非强制
- 提供具体改进示例
- 解释推荐理由
- 考虑性能影响

总结

通过本指南,你已经掌握了:

Subagent 概念 - 理解子代理的作用和价值
基本使用 - 启动和管理子代理
自定义代理 - 创建项目专用代理
社区资源 - 使用 VoltAgent 代理集合
实战场景 - 多代理并行协作
Agent Teams - 团队协作模式(实验性)

下一步学习:

Skills 技能定制
高级多代理编排
自定义代理开发

参考资源

更新日期: 2026年4月29日
适用版本: Claude Code v2.1.92+

Claude Code Subagent 子代理指南

分享这篇文章