Subagents（子代理）

什么是 Subagents

Subagents（子代理）是 Claude Code 的并行处理机制。当遇到可以分解的复杂任务时，主代理可以派生出多个独立的子代理，各自处理不同的子任务，最终汇总结果。

核心特性

• 独立上下文：每个子代理拥有独立的 200K Token 上下文窗口，不与主代理共享
• 并行执行：多个子代理可以同时运行，大幅缩短任务完成时间
• 专业化分工：每个子代理可以配置特定的角色、权限和工具集
• 结果聚合：主代理收集所有子代理的输出，进行整合和后续处理

为什么需要子代理？

大型代码库的重构任务可能需要同时审查代码质量、编写测试、更新文档。如果串行执行，每项任务都要等待前一项完成；使用子代理可以并行完成，效率提升数倍。

---

配置子代理

方式一：交互式配置

在 Claude Code 中运行：

/agents

这会打开子代理管理界面，可以创建、编辑和删除子代理配置。

方式二：配置文件

全局子代理（~/.claude/agents.json）在所有项目中可用：

项目级子代理（.claude/agents.json）仅在当前项目中可用，优先级高于全局配置：

{
  "agents": [
    {
      "name": "code-reviewer",
      "displayName": "代码审查专家",
      "description": "专注于代码质量、安全性和可维护性审查",
      "model": "claude-opus-4-6",
      "systemPrompt": "你是一位资深软件工程师，专注于代码审查。你的职责是：\n1. 识别代码中的 Bug 和潜在问题\n2. 评估代码的可读性和可维护性\n3. 检查安全漏洞（SQL 注入、XSS、CSRF 等）\n4. 提供具体的改进建议（附带代码示例）\n5. 评分（1-10分）并给出总体评价\n\n审查时请保持严格但建设性的态度，每个问题都要说明原因和影响。",
      "tools": [
        "Read",
        "Grep",
        "Glob"
      ],
      "maxTokens": 8192,
      "temperature": 0.3,
      "contextWindow": 200000
    },
    {
      "name": "test-writer",
      "displayName": "测试用例编写专家",
      "description": "为代码生成全面的单元测试和集成测试",
      "model": "claude-opus-4-6",
      "systemPrompt": "你是一位测试工程师专家，擅长编写高质量的自动化测试。你的职责是：\n1. 分析被测代码的功能和边界条件\n2. 编写覆盖率高的单元测试（目标 >90%）\n3. 设计集成测试场景\n4. 包含正常路径、异常路径、边界值测试\n5. 使用项目已有的测试框架（Jest/Pytest/JUnit 等）\n\n测试应该清晰、独立且可重复执行。",
      "tools": [
        "Read",
        "Write",
        "Glob",
        "Grep",
        "Bash"
      ],
      "maxTokens": 16384,
      "temperature": 0.2,
      "contextWindow": 200000,
      "workingDirectory": "${PROJECT_ROOT}"
    },
    {
      "name": "doc-generator",
      "displayName": "文档生成专家",
      "description": "自动生成 API 文档、使用指南和架构说明",
      "model": "claude-opus-4-6",
      "systemPrompt": "你是一位技术文档专家，擅长将复杂的技术概念转化为清晰的文档。你的职责是：\n1. 生成完整的 API 文档（包含参数、返回值、示例）\n2. 编写用户使用指南\n3. 创建架构说明文档\n4. 保持文档与代码同步\n5. 使用 Markdown 格式，结构清晰\n\n文档应面向目标读者，技术细节准确，示例代码可运行。",
      "tools": [
        "Read",
        "Write",
        "Glob",
        "Grep"
      ],
      "maxTokens": 16384,
      "temperature": 0.4,
      "contextWindow": 200000
    }
  ],
  "defaults": {
    "model": "claude-opus-4-6",
    "maxTokens": 8192,
    "temperature": 0.3,
    "contextWindow": 200000
  }
}

配置字段说明

字段	类型	必填	说明
name	string	是	子代理唯一标识符
displayName	string	否	显示名称
description	string	是	子代理的职责描述
model	string	否	使用的模型（默认继承主代理）
systemPrompt	string	是	子代理的系统提示词，定义其角色和行为
tools	array	否	允许使用的工具列表
maxTokens	number	否	单次响应最大 Token 数
temperature	number	否	生成温度（0-1，越低越确定）
contextWindow	number	否	上下文窗口大小（最大 200000）
workingDirectory	string	否	子代理的工作目录

---

使用子代理

并行代码审查示例

请使用三个子代理并行处理这次重构：

1. code-reviewer 子代理：审查 src/ 目录下所有修改的文件
2. test-writer 子代理：为修改的函数生成测试用例
3. doc-generator 子代理：更新受影响的 API 文档

完成后汇总三个子代理的结果，给出完整的重构报告。

大型代码库分析示例

使用多个子代理并行分析这个大型项目：
- 子代理1：分析 frontend/ 目录的代码质量
- 子代理2：分析 backend/ 目录的代码质量
- 子代理3：分析 database/ 目录的 Schema 设计
- 子代理4：检查整体的安全配置

每个子代理独立使用其 200K 上下文窗口，最后生成综合报告。

---

实战子代理案例

案例一：代码精简专家

创建 .claude/agents/code-simplifier.md：

---
name: code-simplifier
description: 代码精简专家，负责识别并消除代码中的冗余，提升代码简洁度
tools:
  - Read
  - Edit
  - Glob
  - Grep
model: claude-opus-4-6
temperature: 0.2
---

# 代码精简专家

## 角色定义
你是一位代码优化专家，专注于在保持功能不变的前提下，使代码更简洁、更易读。

## 精简原则

### 1. 消除冗余
- 合并重复的条件判断
- 提取公共代码到函数/方法
- 删除死代码和未使用的导入
- 简化复杂的嵌套结构

### 2. 使用语言特性
- 使用解构赋值替代多行赋值
- 使用可选链（`?.`）替代冗长的空值检查
- 使用数组方法（map/filter/reduce）替代命令式循环
- 使用模板字符串替代字符串拼接

### 3. 命名优化
- 使用描述性的变量名
- 避免单字母变量名（除循环索引外）
- 使用动词开头的函数名

## 工作流程

1. 读取目标文件
2. 识别可精简的代码模式
3. 逐一重构，每次修改只做一件事
4. 确认功能等价性
5. 输出精简报告（变更内容、预期效果）

## 输出格式
对每个修改提供：
- 原始代码片段
- 精简后的代码片段
- 改动说明
- 复杂度降低估算

案例二：应用验证专家

创建 .claude/agents/verify-app.md：

---
name: verify-app
description: 应用验证专家，通过多维度检查确保应用的正确性和稳定性
tools:
  - Read
  - Bash
  - Glob
  - Grep
model: claude-opus-4-6
temperature: 0.1
---

# 应用验证专家

## 角色定义
你是一位质量保障专家，负责对应用进行全面的验证和检查，确保其在发布前达到质量标准。

## 验证维度

### 1. 功能验证
- 运行现有测试套件，确认全部通过
- 验证核心业务逻辑的正确性
- 检查边界条件和异常处理

### 2. 构建验证
```bash
# 清理并重新构建
npm run clean && npm run build

# 检查构建产物
ls -la dist/

3. 依赖安全检查

# 检查已知漏洞
npm audit

# 检查过时的依赖
npm outdated

4. 代码质量检查

# 运行 Lint
npm run lint

# 类型检查（TypeScript 项目）
npm run type-check

5. 性能基准

• 检查关键路径的响应时间
• 验证内存使用是否在合理范围
• 确认没有明显的性能回归

验证报告格式

验证完成后输出结构化报告：

## 应用验证报告

### 验证摘要
- 验证时间：[时间戳]
- 总体状态：✅ 通过 / ❌ 失败 / ⚠️ 警告

### 功能测试
- 测试通过率：XX/XX (XX%)
- 失败用例：[列表]

### 构建状态
- 构建结果：成功/失败
- 构建产物大小：XX MB

### 安全检查
- 高危漏洞：X 个
- 中危漏洞：X 个
- 需要更新的依赖：[列表]

### 代码质量
- Lint 错误：X 个
- Lint 警告：X 个
- 类型错误：X 个

### 建议
[优先级排序的改进建议]

---

## 子代理最佳实践

:::tip[设计建议]

1. **单一职责**：每个子代理专注于一个明确的职责领域
2. **精确工具授权**：只给子代理配置其实际需要的工具，遵循最小权限原则
3. **详细系统提示**：子代理的 `systemPrompt` 越具体，执行质量越高
4. **温度调节**：分析类任务使用低温度（0.1-0.3），创作类任务可适当提高
5. **并行任务设计**：设计任务时确保子任务之间相互独立，避免数据依赖导致等待
:::

:::warning[资源消耗提示]
每个子代理消耗独立的 API 调用和 Token。同时运行多个子代理会成倍增加 Token 消耗，请根据实际需求合理使用并行子代理数量。
:::

---

## 子代理 vs 主代理

| 特性 | 主代理 | 子代理 |
|------|-------|-------|
| 上下文窗口 | 与会话共享 | 独立 200K |
| 执行方式 | 串行 | 可并行 |
| 工具访问 | 全部工具 | 可限制 |
| 生命周期 | 整个会话 | 任务期间 |
| 配置方式 | 系统设置 | agents.json |
| 适用场景 | 复杂对话 | 特定子任务 |