Subagents 是 Claude Code 中可以并行处理任务的独立 AI 代理，每个子代理拥有独立的 200K 上下文窗口，可以分配不同任务以提高效率。

一、什么是 Subagents？

核心概念

Subagents 是可以并行处理任务的独立 AI 代理，具有以下特点：

• 独立性：每个子代理独立运行
• 并行性：多个子代理同时工作
• 专用性：每个子代理专注于特定领域
• 大上下文：每个子代理拥有 200K token 上下文窗口

核心理念

把常用工作流看作自动化运行的"子智能体"，就像圣诞老人分派任务给精灵一样，每个子智能体专注于特定领域。

Subagent 架构

┌─────────────────────────────────────────────────────────────────┐│                    主代理 Claude Code                            ││                                                                 ││  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐      ││  │子代理1    │  │子代理2    │  │子代理3    │  │子代理4    │     ││  │代码审查   │  │测试编写  │  │文档生成  │  │性能优化   │     ││  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘      ││       │              │              │              │           ││       └──────────────┴──────────────┴──────────────┘           ││                              ↓                                  ││                     ┌─────────────────┐                         ││                     │    结果汇总      │                         ││                     └─────────────────┘                         │└─────────────────────────────────────────────────────────────────┘

二、Subagent 配置

方式一：通过 /agents 命令

# 查看和管理 Subagentsclaude /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 会自动：

1. 创建三个独立的子代理
2. 分配各自的上下文（200K × 3）
3. 并行执行任务
4. 汇总结果返回

执行流程

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 不执行

可能原因：

1. 配置错误
2. 工具权限不足
3. 模型不可用

解决方案：

# 检查配置cat ~/.claude/agents.json# 验证工具权限claude /agents # 查看错误日志claude /agents logs

问题 2：结果不完整

可能原因：

1. 上下文窗口不足
2. 任务过于复杂
3. 指令不清晰

解决方案：

# 简化任务将复杂任务拆分成多个简单任务# 明确指令在 instructions 中添加更详细的指导# 增加上下文提供更多背景信息

问题 3：并行任务冲突

可能原因：

1. 多个 Subagent 操作同一文件
2. 资源竞争
3. 依赖顺序问题

解决方案：

# 串行执行冲突任务使用顺序调用而非并行# 分离职责确保 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"]    }  }}