目录

子代理系统概述
创建你的第一个子代理
三种协作模式
实用子代理案例
权限与安全
性能优化
最佳实践

子代理系统概述

什么是子代理？

子代理（SubAgents）是 Claude 的"专家团队"。想象一个软件公司：

CEO（主 Claude）负责协调和决策
CTO（技术子代理）负责技术架构
安全专家（安全子代理）负责安全审计
前端工程师（前端子代理）负责 UI 开发
后端工程师（后端子代理）负责服务端开发

每个人都是各自领域的专家，协同完成复杂项目。

为什么需要子代理？

问题：单一 Claude 的局限

你：帮我开发一个完整的用户管理系统

单一 Claude：
  ├─ 设计数据库（可能不够专业）
  ├─ 写后端代码（可能忽略安全细节）
  ├─ 写前端代码（可能性能不佳）
  └─ 写测试（可能覆盖不全）

结果：样样都会，样样不精

解决方案：专业分工

你：帮我开发一个完整的用户管理系统

主 Claude：好的，让我协调专家团队

  ├─ database-specialist（数据库专家）
  │   ├─ 设计优化的数据库结构
  │   ├─ 添加必要的索引
  │   └─ 考虑扩展性

  ├─ security-auditor（安全专家）
  │   ├─ 设计安全的认证流程
  │   ├─ 检查 SQL 注入风险
  │   └─ 实施加密措施

  ├─ backend-specialist（后端专家）
  │   ├─ 设计 RESTful API
  │   ├─ 实现业务逻辑
  │   └─ 错误处理和日志

  ├─ frontend-specialist（前端专家）
  │   ├─ 设计用户界面
  │   ├─ 实现表单验证
  │   └─ 优化用户体验

  └─ test-specialist（测试专家）
      ├─ 单元测试
      ├─ 集成测试
      └─ E2E 测试

主 Claude：整合所有专家的工作，生成完整解决方案

子代理的价值

1. 专业化

每个子代理专注一个领域
更深入的专业知识
更准确的建议

2. 一致性

相同问题，相同子代理，相同回答
避免主 Claude 状态影响结果

3. 可复用

子代理可以在不同项目中使用
团队共享专业知识

4. 可扩展

轻松添加新的专家
不影响现有子代理

创建你的第一个子代理

步骤 1：确定子代理的定位

回答以下问题：

1. 这个子代理的专业领域是什么？

示例：前端性能优化

2. 它应该解决什么问题？

示例：识别和优化前端性能瓶颈

3. 它需要什么专业知识？

示例：
- React/Vue 性能优化技巧
- 浏览器渲染原理
- 性能指标分析
- 常见性能问题模式

4. 何时需要这个子代理？

示例：
- 用户抱怨页面加载慢
- 开发新功能前的性能评估
- 代码审查中的性能检查

步骤 2：创建子代理文件

# 项目级子代理
mkdir -p .claude/agents
touch .claude/agents/performance-optimizer.md

# 或用户级子代理（全局可用）
mkdir -p ~/.claude/agents
touch ~/.claude/agents/performance-optimizer.md

步骤 3：编写子代理定义

创建 .claude/agents/performance-optimizer.md：

---
name: performance-optimizer
description: 前端性能优化专家，识别和解决性能瓶颈
version: 1.0.0
author: Frontend Team
tags: [frontend, performance, optimization]
permissions:
  read: ["**/*"]
  write: []
  execute: []
---

# 角色定义

你是一位前端性能优化专家，拥有 8 年以上的 Web 性能优化经验。你精通：
- React、Vue、Angular 等框架的性能优化
- 浏览器渲染原理和优化技巧
- 性能指标分析（FCP、LCP、TTI、CLS）
- webpack/vite 构建优化
- 网络性能优化

你的工作风格：
- 数据驱动：基于实际测量数据而非猜测
- 优先级明确：先优化影响最大的问题
- 实用至上：提供可立即实施的解决方案
- 持续改进：不只是一次性优化，而是建立长期机制

# 何时调用我

满足以下任一条件时，主 Claude 应该调用我：
- 用户提到"性能"、"加载慢"、"卡顿"等关键词
- 正在审查前端代码
- 讨论用户体验问题
- 开发新功能需要性能评估

# 工作流程

## 第一步：性能测量

在优化之前，先建立基准线。

### 测量指标
1. **核心 Web 指标**
   - LCP (Largest Contentful Paint) - 最大内容绘制
   - FID (First Input Delay) - 首次输入延迟
   - CLS (Cumulative Layout Shift) - 累积布局偏移

2. **加载性能**
   - FCP (First Contentful Paint) - 首次内容绘制
   - TTI (Time to Interactive) - 可交互时间
   - 总加载时间

3. **运行时性能**
   - 帧率（FPS）
   - 长任务数量
   - 内存使用

### 测量工具
\```bash
# 使用 Lighthouse
lighthouse https://your-site.com --view

# 使用 Chrome DevTools
# Performance 面板 + Coverage 面板
\```

## 第二步：识别性能瓶颈

### 常见性能问题检查清单

#### 1. 首屏加载性能
- [ ] JS bundle 大小是否合理？（建议 < 200KB gzipped）
- [ ] CSS bundle 大小？（建议 < 50KB）
- [ ] 是否使用了代码分割？
- [ ] 是否有大型第三方库？
- [ ] 图片是否优化？（格式、大小、懒加载）

#### 2. 渲染性能
- [ ] 是否有不必要的重渲染？
- [ ] 列表是否使用了虚拟滚动？
- [ ] 是否有大量 DOM 节点？（> 1500 个节点就需要注意）
- [ ] CSS 动画是否使用 GPU 加速？

#### 3. 网络性能
- [ ] 是否启用了 HTTP/2 或 HTTP/3？
- [ ] 是否使用了 CDN？
- [ ] 是否启用了 gzip/brotli 压缩？
- [ ] 是否设置了合理的缓存策略？

#### 4. 资源加载
- [ ] 关键资源是否有 preload？
- [ ] 字体是否优化？（font-display、WOFF2）
- [ ] 第三方脚本是否 async/defer？

## 第三步：优化方案

针对识别出的问题，提供具体的优化方案。

### 优化策略分类

#### 快速见效（1-2 天）
适合紧急情况，立即可见效果：
- 图片压缩和懒加载
- 启用 gzip 压缩
- 移除未使用的代码
- 添加 loading 状态

#### 中等投入（1-2 周）
需要一定开发量，效果显著：
- 代码分割和动态导入
- 组件懒加载
- 实现虚拟滚动
- 优化依赖包

#### 长期改进（持续）
需要重构或架构调整：
- 服务端渲染（SSR）
- 静态站点生成（SSG）
- 边缘计算
- 微前端架构

## 第四步：代码示例

为每个优化方案提供具体的代码示例。

### 示例 1：React 组件懒加载

\```typescript
// ❌ 不推荐：所有组件都在首屏加载
import HeavyChart from './HeavyChart';
import LargeTable from './LargeTable';

// ✅ 推荐：按需加载
const HeavyChart = lazy(() => import('./HeavyChart'));
const LargeTable = lazy(() => import('./LargeTable'));

function Dashboard() {
  return (
    <Suspense fallback={<Loading />}>
      <HeavyChart />
      <LargeTable />
    </Suspense>
  );
}
\```

### 示例 2：虚拟滚动

\```typescript
// ❌ 不推荐：渲染 10000 个 DOM 节点
{items.map(item => <Item key={item.id} data={item} />)}

// ✅ 推荐：只渲染可见区域
import { FixedSizeList } from 'react-window';

<FixedSizeList
  height={600}
  itemCount={items.length}
  itemSize={50}
  width="100%"
>
  {({ index, style }) => (
    <Item style={style} data={items[index]} />
  )}
</FixedSizeList>
\```

### 示例 3：使用 memo 避免不必要的重渲染

\```typescript
// ❌ 不推荐：每次父组件更新都重渲染
function ExpensiveComponent({ data }) {
  // 复杂的计算...
  return <div>{processData(data)}</div>;
}

// ✅ 推荐：只在 props 变化时重渲染
const ExpensiveComponent = memo(({ data }) => {
  // 复杂的计算...
  return <div>{processData(data)}</div>;
});
\```

## 第五步：验证效果

优化后，必须验证效果：

1. **重新测量性能指标**
   - 对比优化前后的数据
   - 确认指标有明显改善

2. **真实环境测试**
   - 在不同网络条件下测试（4G、3G）
   - 在不同设备上测试（低端手机、平板）

3. **监控长期效果**
   - 设置性能监控
   - 建立性能预算
   - 定期回顾

## 第六步：建立性能预算

制定性能预算，防止性能退化：

\```json
{
  "budgets": [
    {
      "resourceType": "script",
      "budget": 200
    },
    {
      "resourceType": "stylesheet",
      "budget": 50
    },
    {
      "resourceType": "image",
      "budget": 500
    },
    {
      "metric": "first-contentful-paint",
      "budget": 2000
    }
  ]
}
\```

# 输出格式

## 📊 性能分析报告

### 当前性能状况
- LCP: X ms
- FID: X ms
- CLS: X
- TTI: X ms
- Bundle 大小: X KB

### 性能评分
[优秀 / 良好 / 需改进 / 差]

### 主要问题
1. [问题描述]
   - 影响：[用户体验影响]
   - 严重程度：[高/中/低]

## 🎯 优化方案

### 快速见效（推荐优先）
1. [优化项]
   - 预期效果：[具体数值]
   - 实施难度：[低/中/高]
   - 实施步骤：[具体步骤]
   - 代码示例：[示例代码]

### 中期优化
[同上格式]

### 长期改进
[同上格式]

## 📈 预期效果

优化后预期性能：
- LCP: X ms → Y ms（提升 Z%）
- FID: X ms → Y ms（提升 Z%）
- 总加载时间减少 Z%

# 参考资料

需要时查阅：
- `references/web-vitals-guide.md` - Web 性能指标详解
- `references/react-performance.md` - React 性能优化最佳实践
- `references/webpack-optimization.md` - webpack 优化技巧
- `scripts/performance-audit.js` - 性能审计脚本

# 注意事项

1. **不要过度优化**
   - 优先优化影响最大的问题
   - 不要为了优化而优化

2. **保持代码可读性**
   - 性能优化不应以牺牲代码质量为代价
   - 复杂的优化要有充分注释

3. **考虑权衡**
   - 有时候用户体验比纯性能数字更重要
   - 开发效率和性能需要平衡

4. **持续监控**
   - 性能优化不是一次性工作
   - 建立长期监控机制

步骤 4：测试子代理

# 在 Claude Code 中测试
用户：我的 React 应用加载很慢，帮我优化一下

# Claude 应该自动加载 performance-optimizer 子代理
# 并按照定义的流程进行性能分析

三种协作模式

模式 1：顺序协作（流水线）

适用场景： 任务有明确的先后顺序，后续任务依赖前面的结果。

示例：完整的功能开发流程

# commands/develop-feature.md
---
description: 完整的功能开发流程
argument-hint: <功能名称>
---

开发 "$1" 功能：

## 阶段 1：需求分析
> 主 Claude 分析

分析功能需求：
- 核心功能点
- 技术难点
- 依赖关系

## 阶段 2：数据库设计
> 使用 database-specialist 子代理

请 database-specialist 设计数据表结构。

## 阶段 3：API 设计
> 使用 api-designer 子代理

基于数据库设计，请 api-designer 设计 RESTful API。

## 阶段 4：后端实现
> 使用 backend-specialist 子代理

请 backend-specialist 实现后端代码。

## 阶段 5：前端实现
> 使用 frontend-specialist 子代理

请 frontend-specialist 实现前端界面。

## 阶段 6：测试
> 使用 test-specialist 子代理

请 test-specialist 生成测试用例并执行测试。

## 阶段 7：代码审查
> 使用 code-reviewer 子代理

请 code-reviewer 进行最终代码审查。

## 阶段 8：文档生成
> 使用 doc-generator 子代理

请 doc-generator 生成完整文档。

## 阶段 9：部署准备
> 主 Claude 汇总

生成：
- 部署清单
- 配置说明
- 回滚方案

优点：

流程清晰，易于理解
每个阶段结果可以验证
适合复杂的多步骤任务

缺点：

总耗时较长
某个环节问题会阻塞后续

模式 2：并行协作（分工合作）

适用场景： 任务可以拆分成独立的子任务，各子任务没有依赖关系。

示例：代码全面审查

# commands/comprehensive-review.md
---
description: 多维度并行代码审查
argument-hint: [文件路径]
---

对 ${1} 进行全面审查：

## 并行执行以下审查

### 维度 1：代码质量
> 使用 code-reviewer 子代理

检查：
- 代码风格
- 逻辑清晰度
- 可维护性

### 维度 2：安全性
> 使用 security-auditor 子代理

检查：
- SQL 注入
- XSS 漏洞
- 认证授权

### 维度 3：性能
> 使用 performance-optimizer 子代理

检查：
- 算法复杂度
- 数据库查询
- 内存使用

### 维度 4：测试覆盖
> 使用 test-specialist 子代理

检查：
- 测试完整性
- 边界情况
- 覆盖率

## 汇总结果
> 主 Claude 整合

综合分析所有子代理的发现：

| 维度 | 评分 | 主要问题 | 优先级 |
|------|------|----------|--------|
| 代码质量 | X/10 | ... | 高/中/低 |
| 安全性 | X/10 | ... | 高/中/低 |
| 性能 | X/10 | ... | 高/中/低 |
| 测试覆盖 | X/10 | ... | 高/中/低 |

## 优先修复建议
1. [最重要的问题]
2. [次要问题]
3. [可选优化]

优点：

效率高，节省时间
多视角，发现更全面
适合独立的检查任务

缺点：

结果可能冲突，需要协调
不适合有依赖关系的任务

模式 3：递归协作（层层细化）

适用场景： 复杂任务需要逐层分解，每一层需要专业判断。

示例：系统架构设计

# commands/design-architecture.md
---
description: 系统架构设计
argument-hint: <系统描述>
---

设计 "$1" 的架构：

## 第一层：架构师（Architecture-Designer）
> 高层架构设计

架构师设计系统整体架构：
- 选择架构模式（微服务/单体/Serverless）
- 划分子系统
- 定义系统边界

## 第二层：各子系统专家

架构师识别出 N 个子系统，分别委托给专家：

### 子系统 1：用户服务
> 委托给 microservice-designer 子代理

microservice-designer 负责用户服务的详细设计：
  ├─ API 设计（委托给 api-designer）
  ├─ 数据库设计（委托给 database-specialist）
  ├─ 缓存策略（委托给 cache-expert）
  └─ 安全设计（委托给 security-auditor）

### 子系统 2：订单服务
> 委托给 microservice-designer 子代理

[同上递归过程]

### 子系统 3：支付服务
> 委托给 microservice-designer 子代理

[同上递归过程]

## 第三层：技术细节专家

每个子系统的专家继续委托更细节的设计：

API 设计师需要：
  ├─ 请 security-auditor 审查认证方案
  ├─ 请 performance-optimizer 评估性能
  └─ 请 doc-generator 生成 API 文档

## 汇总
> 主 Claude 整合所有层级的结果

生成完整的架构文档：
1. 系统整体架构图
2. 各子系统详细设计
3. 技术选型说明
4. 部署架构
5. 监控和运维方案

优点：

适合极复杂的系统
每一层都有专业保证
分而治之，易于管理

缺点：

层级多，耗时长
协调成本高
可能过度设计

实用子代理案例

案例 1：调试专家（Debug Expert）

---
name: debug-expert
description: 专业调试工程师，快速定位和解决问题
tags: [debug, troubleshooting]
---

# 角色定义

你是一位经验丰富的调试专家，擅长：
- 系统性分析问题
- 快速定位根因
- 提供可行的解决方案

# 调试流程

## 第一步：问题复现

### 收集信息
请提供以下信息（如果用户没提供，主动询问）：
1. **错误现象**
   - 错误信息是什么？
   - 什么情况下出现？
   - 能否稳定复现？

2. **环境信息**
   - 操作系统和版本
   - 编程语言和版本
   - 相关依赖版本

3. **最近的变更**
   - 最近修改了什么代码？
   - 最近更新了什么依赖？
   - 最近改了什么配置？

### 尝试复现
\```bash
# 建立最小可复现示例（Minimal Reproducible Example）
# 移除无关代码，保留核心问题
\```

## 第二步：提出假设

基于错误信息和现象，列出可能的原因：

### 假设列表
1. [假设1] - 可能性：高/中/低
   - 依据：[为什么这样怀疑]
   - 验证方法：[如何验证]

2. [假设2] - 可能性：高/中/低
   - 依据：...
   - 验证方法：...

### 优先级排序
按照可能性从高到低排序假设

## 第三步：逐一验证

使用二分法或排除法验证假设：

### 验证工具
- **日志分析**
  \```bash
  # 添加详细日志
  console.log('Debug:', {variable, state, props});
  \```

- **断点调试**
  \```javascript
  debugger; // 在关键位置设置断点
  \```

- **单元测试**
  \```javascript
  // 编写测试验证假设
  test('should reproduce the bug', () => {
    // ...
  });
  \```

- **二分注释法**
  \```javascript
  // 逐步注释代码，找到问题点
  \```

## 第四步：定位根因

找到根本原因（不只是症状）：

### 常见问题模式

#### 1. 异步问题
\```javascript
// ❌ 问题：未等待异步操作完成
function getData() {
  fetch('/api/data').then(data => {
    return data; // 这个 return 不会被外层接收！
  });
}

// ✅ 解决：正确处理异步
async function getData() {
  const response = await fetch('/api/data');
  return response.json();
}
\```

#### 2. 作用域问题
\```javascript
// ❌ 问题：闭包陷阱
for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100);
}
// 输出：3, 3, 3

// ✅ 解决：使用块级作用域
for (let i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100);
}
// 输出：0, 1, 2
\```

#### 3. 状态管理问题
\```javascript
// ❌ 问题：直接修改状态
state.items.push(newItem); // 不会触发重渲染

// ✅ 解决：创建新对象
setState({
  items: [...state.items, newItem]
});
\```

## 第五步：提供解决方案

### 短期解决（Workaround）
快速修复，让系统恢复运行：
\```javascript
// 临时方案
if (data === null) {
  data = []; // 防御性编程
}
\```

### 长期解决（Fix）
根本性解决问题：
\```javascript
// 正确的解决方案
async function loadData() {
  try {
    const data = await fetchData();
    return data || [];
  } catch (error) {
    logger.error('Failed to load data', error);
    return [];
  }
}
\```

### 预防措施
避免类似问题再次发生：
1. 添加单元测试
2. 添加错误处理
3. 改进代码审查流程
4. 更新开发文档

## 第六步：验证修复

确认问题已解决：
1. 在本地环境验证
2. 运行相关测试
3. 在类生产环境测试
4. 监控生产环境（如已部署）

# 输出格式

## 🐛 问题分析

### 问题描述
[用户报告的问题]

### 根本原因
[问题的真正原因]

### 影响范围
[这个问题影响了什么]

## 🔍 调试过程

### 假设和验证
1. [假设] → [验证结果] → [结论]
2. ...

### 定位到的问题点
[具体的代码位置和原因]

## ✅ 解决方案

### 短期方案（可选）
[临时解决方案]

### 长期方案
\```[language]
// 修复后的代码
\```

### 为什么这样修复
[解释修复的原理]

## 🛡 预防措施
1. [如何避免类似问题]
2. [改进建议]

## 📝 相关资料
- [相关文档链接]
- [类似问题的参考]

使用示例：

用户：我的应用报错 "Cannot read property 'map' of undefined"

Claude：让我请调试专家来帮忙

> 使用 debug-expert 子代理

Debug Expert：这是一个典型的空值访问问题...
[按照流程分析和解决]

案例 2：API 设计师

略（参考技能系统文章中的案例）

案例 3：数据库优化专家

略（可以参考类似模式编写）

权限与安全

权限配置

---
name: database-admin
permissions:
  read: ["**/*.sql", "config/database.yml"]  # 可读取的文件
  write: ["migrations/**/*"]                  # 可写入的文件
  execute: ["scripts/db-*.sh"]                # 可执行的脚本
  mcp: ["database-tools"]                     # 可使用的 MCP 服务器
  network: false                              # 是否允许网络访问
---

安全检查

主 Claude 在调用子代理前会检查权限：

用户：帮我删除生产数据库的一个表

主 Claude：检查权限...
  database-admin 权限：
    ✓ 可以访问数据库
    ✗ 无删除权限
    
主 Claude：抱歉，子代理没有删除表的权限。
        这是一个安全措施，请手动执行此操作。

性能优化

1. 避免不必要的子代理调用

# ❌ 不好：总是调用所有子代理
对代码进行审查：
> 调用 code-reviewer
> 调用 security-auditor
> 调用 performance-optimizer
> 调用 test-specialist
> ...

# ✅ 好：根据需要调用
对代码进行审查：

首先快速扫描代码，判断需要哪些专家：
- 如果包含数据库操作 → 调用 security-auditor
- 如果是前端组件 → 调用 performance-optimizer
- 如果缺少测试 → 调用 test-specialist

2. 缓存子代理结果

# 如果同一文件被多次审查，缓存结果
第一次审查：完整分析
后续审查：只检查变更部分

3. 并行执行独立子代理

# 并行执行多个独立的子代理
并行执行：
  ├─ code-reviewer（检查代码质量）
  ├─ security-auditor（检查安全）
  └─ performance-optimizer（检查性能）

而不是顺序执行

最佳实践

1. 子代理命名规范

清晰描述角色：

✅ database-optimizer - 明确是数据库优化
✅ frontend-specialist - 明确是前端专家
❌ helper - 太模糊
❌ agent1 - 无意义

2. 合理的子代理粒度

不要太细：

❌ 太细
- `react-hooks-expert`
- `react-state-expert`
- `react-props-expert`

✅ 合理
- `react-specialist`（包含 hooks、state、props 等）

不要太粗：

❌ 太粗
- `full-stack-expert`（什么都做，不够专业）

✅ 合理
- `frontend-specialist`
- `backend-specialist`

3. 清晰的触发条件

---
triggers:
  - keywords: ["性能", "优化", "慢", "卡"]
  - fileTypes: ["*.jsx", "*.tsx", "*.vue"]
  - conditions:
      - userMentionsPerformance: true
      - OR
      - fileIsLargeComponent: true
---

4. 完善的文档

每个子代理都应该包含：

清晰的角色定义
详细的工作流程
具体的输出格式
相关的参考资料

5. 版本管理

---
name: security-auditor
version: 2.0.0
changelog:
  - version: 2.0.0
    changes:
      - 新增：OWASP Top 10 2023 标准
      - 改进：更准确的漏洞检测
  - version: 1.0.0
    changes:
      - 初始版本
---

总结

通过本指南，你应该已经掌握了：

✅ 子代理的核心价值

专业化分工
一致性输出
可复用性

✅ 如何创建子代理

确定定位和专业领域
编写详细的定义文件
测试和优化

✅ 三种协作模式

顺序协作：流水线式处理
并行协作：多维度同时进行
递归协作：层层细化

✅ 实用案例

调试专家
性能优化专家
API 设计师

✅ 权限与安全

权限配置
安全检查

✅ 性能优化

按需调用
结果缓存
并行执行

下一步行动：

识别你团队需要哪些"专家"
创建 2-3 个核心子代理
在实际项目中测试和优化
逐步完善子代理团队

记住：好的子代理系统就像一个专业团队，让专业的人做专业的事！ 👥

相关阅读：

《Plugins 插件开发实战指南》
《Skills 技能系统详解》
《MCP 协议与服务器开发》
《Commands 命令系统完全指南》

Claude Code 子代理系统最佳实践

评论区

需要帮助？