Subagents 子代理详解
Subagents 子代理详解
Subagents 是 Claude Code 中可以并行处理任务的独立 AI 代理，每个子代理拥有独立的 200K 上下文窗口，可以分配不同任务以提高效率。
一、什么是 Subagents？
核心概念
Subagents 是可以并行处理任务的独立 AI 代理，具有以下特点：
- 独立性：每个子代理独立运行
- 并行性：多个子代理同时工作
- 专用性：每个子代理专注于特定领域
- 大上下文：每个子代理拥有 200K token 上下文窗口
核心理念
把常用工作流看作自动化运行的"子智能体"，就像圣诞老人分派任务给精灵一样，每个子智能体专注于特定领域。
Subagent 架构
┌─────────────────────────────────────────────────────────────────┐
│ 主代理 Claude Code │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │子代理1 │ │子代理2 │ │子代理3 │ │子代理4 │ │
│ │代码审查 │ │测试编写 │ │文档生成 │ │性能优化 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │
│ └──────────────┴──────────────┴──────────────┘ │
│ ↓ │
│ ┌─────────────────┐ │
│ │ 结果汇总 │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
二、Subagent 配置
方式一：通过 /agents 命令
# 查看和管理 Subagents
claude /agents
方式二：配置文件
在 ~/.claude/agents.json 或项目 .claude/agents.json 中配置：
{
"agents": {
"code-reviewer": {
"description": "专门负责代码审查的子代理",
"model": "claude-opus-4-5",
"instructions": "你是一个专业的代码审查专家，专注于检查代码质量、安全漏洞和性能问题。",
"tools": ["read", "search", "git"],
"permissions": {
"allowWrite": false
}
},
"test-writer": {
"description": "专门负责编写测试的子代理",
"model": "claude-sonnet-4-5",
"instructions": "你是一个测试工程师，专注于编写全面的单元测试和集成测试。",
"tools": ["read", "write", "bash"]
},
"doc-generator": {
"description": "专门负责生成文档的子代理",
"model": "claude-sonnet-4-5",
"instructions": "你是一个技术文档专家，专注于生成清晰、准确的技术文档。",
"tools": ["read", "write"]
},
"performance-optimizer": {
"description": "专门负责性能优化的子代理",
"model": "claude-opus-4-5",
"instructions": "你是一个性能优化专家，专注于识别和解决性能瓶颈。",
"tools": ["read", "bash", "search"]
}
}
}
配置参数说明
| 参数 | 说明 | 必填 |
|------|------|------|
| description | 子代理描述 | 是 |
| model | 使用的模型 | 否 |
| instructions | 系统指令 | 是 |
| tools | 允许使用的工具 | 否 |
| permissions | 权限设置 | 否 |
三、Subagent 使用示例
场景：完成一个功能开发
# 主任务
我需要完成用户认证功能,请帮我:
1. 使用 code-reviewer agent 审查现有认证代码
2. 使用 test-writer agent 编写测试用例
3. 使用 doc-generator agent 更新 API 文档
这三个任务并行执行
Claude Code 会自动：
- 创建三个独立的子代理
- 分配各自的上下文（200K × 3）
- 并行执行任务
- 汇总结果返回
执行流程
1. 接收主任务
↓
2. 解析子代理需求
↓
3. 创建子代理实例 (code-reviewer, test-writer, doc-generator)
↓
4. 并行执行 (同时进行)
↓
5. 收集结果
↓
6. 汇总报告
四、实战子代理案例
案例 1：code-simplifier
创建 .claude/agents/code-simplifier.md：
# .claude/agents/code-simplifier.md
你是一个代码精简专家。在 Claude 完成工作后，你的任务是：
1. 分析代码的复杂度和可读性
2. 识别可以简化的逻辑
3. 提供优化建议但保持功能不变
4. 优先考虑性能和可维护性
## 工作流程
1. 阅读完整代码
2. 识别复杂部分
3. 提出简化方案
4. 给出具体建议
## 输出格式
```markdown
## 简化建议
### 建议1: [标题]
- 当前代码: [代码片段]
- 问题: [问题描述]
- 建议: [简化方案]
- 预期效果: [效果说明]
### 建议2: [标题]
...
注意事项
- 不要改变代码功能
- 优先使用标准库
- 保持代码可读性
### 案例 2：verify-app
创建 `.claude/agents/verify-app.md`：
```markdown
# .claude/agents/verify-app.md
你是一个端到端测试专家。你的任务是验证应用功能：
1. 运行完整的测试套件
2. 检查所有关键路径
3. 验证边界情况
4. 确保用户体验"感觉对劲"
5. 如果发现问题，提供详细的修复步骤
## 验证步骤
1. **功能测试**
- 核心功能是否正常
- 用户流程是否顺畅
2. **边界测试**
- 异常输入处理
- 边界条件处理
3. **性能测试**
- 响应时间
- 资源占用
4. **用户体验**
- 界面响应
- 错误提示
## 输出格式
```markdown
## 验证报告
### ✅ 通过项目
- [项目1]
- [项目2]
### ❌ 失败项目
- [项目]: [原因]
- 修复建议: [建议]
### ⚠️ 需要关注
- [项目]: [说明]
注意事项
- 如实报告，不要隐瞒问题
- 提供具体的复现步骤
- 给出可行的解决方案
### 使用方式
```bash
# 在 Claude Code 中
使用 code-simplifier agent 优化刚才写的代码
使用 verify-app agent 验证应用是否正常工作
五、自定义 Subagent 模板
模板结构
.claude/agents/
├── code-reviewer.md
├── test-writer.md
├── doc-generator.md
└── custom-agent.md
完整模板示例
# .claude/agents/[agent-name].md
你是一个[角色描述]。你的任务是[主要任务]。
## 核心职责
1. [职责1]
2. [职责2]
3. [职责3]
## 工作流程
1. [步骤1]
2. [步骤2]
3. [步骤3]
## 约束条件
- [约束1]
- [约束2]
## 输出格式
```markdown
## [任务]结果
### [部分1]
[内容]
### [部分2]
[内容]
注意事项
- [注意事项1]
- [注意事项2]
## 六、Subagent 最佳实践
### 1. 职责分离
```json
{
"agents": {
"frontend-dev": {
"description": "前端开发子代理",
"instructions": "专注于 React、Vue 等前端开发",
"tools": ["read", "write", "bash"]
},
"backend-dev": {
"description": "后端开发子代理",
"instructions": "专注于 Node.js、Python 等后端开发",
"tools": ["read", "write", "bash"]
},
"devops": {
"description": "DevOps 子代理",
"instructions": "专注于部署、运维、CI/CD",
"tools": ["read", "bash", "git"]
}
}
}
2. 权限控制
{
"agents": {
"readonly-reviewer": {
"description": "只读代码审查",
"instructions": "只读代码，不进行修改",
"permissions": {
"allowWrite": false,
"allowBash": false
}
}
}
}
3. 工具限制
{
"agents": {
"safe-tester": {
"description": "安全测试子代理",
"instructions": "只使用安全的测试工具",
"tools": ["read", "bash"],
"allowedCommands": [
"npm test",
"npm run test:*"
],
"deniedCommands": [
"rm *",
"format *"
]
}
}
}
七、常见问题
问题 1：Subagent 不执行
可能原因：
- 配置错误
- 工具权限不足
- 模型不可用
解决方案：
# 检查配置
cat ~/.claude/agents.json
# 验证工具权限
claude /agents <agent-name>
# 查看错误日志
claude /agents logs
问题 2：结果不完整
可能原因：
- 上下文窗口不足
- 任务过于复杂
- 指令不清晰
解决方案：
# 简化任务
将复杂任务拆分成多个简单任务
# 明确指令
在 instructions 中添加更详细的指导
# 增加上下文
提供更多背景信息
问题 3：并行任务冲突
可能原因：
- 多个 Subagent 操作同一文件
- 资源竞争
- 依赖顺序问题
解决方案：
# 串行执行冲突任务
使用顺序调用而非并行
# 分离职责
确保 Subagent 操作不同的文件
# 协调执行
使用主代理协调 Subagent 执行顺序
八、进阶技巧
1. 动态 Subagent
# 根据任务动态选择 Subagent
根据代码语言选择合适的 Subagent:
- JavaScript/TypeScript -> frontend-dev
- Python/Java -> backend-dev
- Go/Rust -> system-dev
2. 链式 Subagent
# 一个 Subagent 的输出作为另一个的输入
1. code-analyzer 分析代码
2. code-simplifier 简化代码
3. test-writer 编写测试
4. verify-app 验证结果
3. 条件 Subagent
{
"agents": {
"smart-router": {
"description": "智能路由子代理",
"instructions": "根据任务类型路由到合适的子代理",
"tools": ["read", "bash"]
}
}
}