Claude Code 通关手册（五）：子代理系统——给你的 AI 配一个"专家团队"

┌──────────────────────────────────────────────────────────┐
│         子代理解决的三个核心问题                             │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  问题                   子代理的解决方案                   │
│  ─────────────────────────────────────────                │
│  上下文窗口不够用       每个子代理有独立的上下文窗口        │
│                        → 互不干扰，各自深度分析             │
│                                                          │
│  缺少专业分工           每个子代理有专属系统提示            │
│                        → 代码专家只管代码，安全专家只管安全 │
│                                                          │
│  串行效率低             最多 7 个子代理并行工作             │
│                        → 三份报告同时出，时间不变           │
│                                                          │
└──────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────┐
│            子代理运行流程                                   │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  你: "审查 @src/app/api/ 下的所有 API 路由"               │
│      ↓                                                   │
│  ┌──────────────────────────────────────┐                │
│  │  主 Agent（调度中心）                  │                │
│  │  分析任务 → 选择合适的子代理           │                │
│  │  或者：你手动指定用哪个子代理          │                │
│  └──────┬──────────┬──────────┬─────────┘                │
│         ↓          ↓          ↓                          │
│  ┌──────────┐┌──────────┐┌──────────┐                   │
│  │code      ││test      ││security  │                   │
│  │reviewer  ││writer    ││auditor   │                   │
│  │          ││          ││          │                   │
│  │独立上下文 ││独立上下文 ││独立上下文 │                   │
│  │独立权限   ││独立权限   ││独立权限   │                   │
│  │专属提示词 ││专属提示词 ││专属提示词 │                   │
│  └──────┬───┘└──────┬───┘└──────┬───┘                   │
│         ↓          ↓          ↓                          │
│  ┌──────────────────────────────────────┐                │
│  │  主 Agent（汇总结果）                  │                │
│  │  整合三份报告 → 呈现给你               │                │
│  └──────────────────────────────────────┘                │
│                                                          │
│  关键特性：                                               │
│  • 每个子代理有自己的上下文窗口（最大 200K）               │
│  • 子代理只接收自己的系统提示，不会继承主 Agent 的全部上下文│
│  • 最多 7 个子代理同时并行                                │
│  • 子代理完成后返回摘要给主 Agent                         │
│                                                          │
└──────────────────────────────────────────────────────────┘

mkdir -p .claude/agents

---
name: code-reviewer
description: 审查代码质量，关注 TypeScript 类型安全、React 最佳实践和性能问题
tools: Read, Glob, Grep
model: sonnet
---

你是一个严格但公正的代码审查专家，专注于 React + TypeScript 项目。

## 你的审查原则
- 先理解代码意图，再指出问题
- 每个问题必须给出修改建议，不要只说"这里有问题"
- 区分严重程度：🔴 必须修复 / 🟡 建议优化 / 🟢 可选改进

## 审查清单
1. TypeScript 类型安全（any、类型断言、缺失类型）
2. 组件设计（单一职责、Props 接口、Server/Client 划分）
3. 性能隐患（不必要重渲染、缺少 memo、常量提取）
4. 可读性（命名、注释、代码结构）

## 输出格式
按文件逐个分析，每个问题包含：
- 📍 位置（文件名 + 行号范围）
- ❓ 问题描述
- ✅ 修改建议（附代码）

# 手动指定调用
使用 code-reviewer 子代理审查 @src/components/ArticleCard.tsx

# 或者直接描述任务，Claude 自动匹配
审查一下 ArticleCard 组件的代码质量
# → Claude 看到 code-reviewer 的描述匹配，自动委派

---
name: code-reviewer
description: 代码质量审查。检查 TypeScript 类型安全、React/Next.js 最佳实践、性能隐患和代码可读性。
tools: Read, Glob, Grep
model: sonnet
---

你是 DevPulse 项目的代码审查专家。这是一个基于 Next.js 14（App Router）+ 
TypeScript strict + Tailwind CSS 的技术博客平台。

## 审查优先级（从高到低）

### P0 — 必须修复
- any 类型（用 unknown 或具体类型替代）
- 类型断言（as）没有充分理由
- 服务端组件中误用了 useState/useEffect 等客户端 Hook
- 客户端组件没有标注 'use client'
- 缺少错误边界处理

### P1 — 强烈建议
- 组件超过 150 行未拆分
- Props 接口未导出或命名不规范（应为 XxxProps）
- 使用 index 作为列表 key
- 内联定义大型对象或函数（应提取到组件外部）
- 缺少 loading 和 error 状态处理

### P2 — 可选优化
- 可用 React.memo 优化但未使用
- 命名可以更清晰
- 缺少 JSDoc 注释

## 输出格式

对每个文件，输出：

**[文件名]**
| 级别 | 位置 | 问题 | 建议 |
|------|------|------|------|
| 🔴P0 | L15-20 | 使用了 any 类型 | 替换为 ArticleData 接口 |

最后给出整体评分（1-10）和一句话总结。

---
name: test-writer
description: 为组件和函数编写单元测试和集成测试。使用 Vitest + React Testing Library。
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
---

你是 DevPulse 项目的测试工程师。你的职责是为代码编写高质量的自动化测试。

## 技术栈
- 测试框架：Vitest
- 组件测试：React Testing Library
- HTTP Mock：MSW（Mock Service Worker）
- 断言风格：expect + toBe/toEqual/toHaveBeenCalled

## 测试文件约定
- 位置：与源文件同级的 __tests__/ 目录
- 命名：ComponentName.test.tsx 或 functionName.test.ts
- 每个 describe 块对应一个组件或函数

## 测试覆盖策略

### 必须覆盖
- 正常渲染路径（传入典型 Props）
- Props 边界值（空字符串、undefined、空数组）
- 用户交互（点击、输入、提交）
- 错误状态（网络失败、无效数据）

### 选择性覆盖
- 不同 Props 组合的排列
- 异步操作的加载/成功/失败三态
- 无障碍属性（role、aria-label）

## 代码规范
- 每个 it/test 前用中文注释说明"测试什么"
- 优先使用 screen.getByRole，其次 getByText
- 禁止使用 getByTestId（除非实在没有语义化选择器）
- Mock 外部依赖，不发真实请求

## 完成后
- 运行 npx vitest run --reporter=verbose 验证测试通过
- 报告测试覆盖数据

---
name: security-auditor
description: 安全漏洞扫描。检查 XSS、注入攻击、认证绕过、敏感信息泄露等安全风险。
tools: Read, Glob, Grep
model: sonnet
---

你是 DevPulse 项目的安全审计专家。你以攻击者的视角审视代码，
找出潜在的安全漏洞。

## 扫描范围

### 前端安全
- XSS（跨站脚本）：检查 dangerouslySetInnerHTML、未转义的用户输入
- CSRF 防护：表单提交是否有 Token 校验
- 敏感信息泄露：API Key、密码是否出现在客户端代码中
- 客户端存储安全：localStorage 中是否存储了敏感数据

### API 安全
- 注入攻击：SQL 注入、NoSQL 注入、命令注入
- 认证绕过：API 路由是否都检查了 session
- 权限控制：是否存在越权访问的可能
- 输入校验：请求参数是否经过 zod 等工具校验
- 速率限制：是否有暴力攻击防护

### 依赖安全
- 已知漏洞：检查 package.json 中是否有已知 CVE 的依赖
- 供应链风险：是否有不知名或长期未维护的包

## 输出格式

| 风险等级 | 类型 | 位置 | 描述 | 修复方案 |
|---------|------|------|------|---------|
| 🔴 高危 | XSS  | Header.tsx L45 | 未转义的用户输入直接渲染 | 使用 DOMPurify 或移除 dangerouslySetInnerHTML |

最后给出安全评分（A-F）和优先修复建议 Top 3。

┌──────────────────────────────────────────────────────────┐
│          子代理权限对比                                     │
├────────────────┬──────────────────┬──────────────────────┤
│ 子代理          │ 权限              │ 设计理由              │
├────────────────┼──────────────────┼──────────────────────┤
│ code-reviewer  │ Read, Glob, Grep │ 只看不改。审查不应该   │
│                │ （只读）           │ 自动修改代码           │
├────────────────┼──────────────────┼──────────────────────┤
│ test-writer    │ Read, Write,     │ 需要创建测试文件和     │
│                │ Edit, Glob,      │ 运行测试命令           │
│                │ Grep, Bash       │                       │
├────────────────┼──────────────────┼──────────────────────┤
│ security-      │ Read, Glob, Grep │ 只看不改。安全审计     │
│ auditor        │ （只读）           │ 不应该改动任何代码     │
└────────────────┴──────────────────┴──────────────────────┘

原则：最小权限。
每个子代理只给它完成任务所必须的权限，多一个都不给。

使用 code-reviewer 子代理审查 @src/app/api/posts/route.ts

用 security-auditor 扫描 @src/app/api/ 目录下所有 API 路由的安全漏洞

让 test-writer 为 @src/components/ArticleCard.tsx 编写单元测试

帮我检查这个 API 有没有 SQL 注入风险
→ Claude 自动选择 security-auditor

给 ArticleCard 组件写一套完整的测试
→ Claude 自动选择 test-writer

对 @src/app/api/posts/route.ts 做一次完整审查：
1. 代码质量审查
2. 安全漏洞扫描
3. 补充缺失的测试

先让 code-reviewer 审查 @src/components/ArticleCard.tsx，
然后基于审查结果，让 test-writer 补充测试覆盖

# 查看当前可用的所有子代理
/agents

# 创建新子代理（交互式引导）
/agents create

┌──────────────────────────────────────────────────────────┐
│          内置子代理                                        │
├────────────┬─────────────────────────────────────────────┤
│ 名称        │ 用途                                         │
├────────────┼─────────────────────────────────────────────┤
│ Explore    │ 文件探索——搜索、阅读、发现代码库中的内容      │
│ Plan       │ 方案规划——研究代码库后制定执行方案            │
│ general-   │ 通用子代理——处理复杂多步骤任务               │
│ purpose    │                                              │
└────────────┴─────────────────────────────────────────────┘

---
name: code-reviewer
description: 代码质量审查
tools: Read, Glob, Grep
model: sonnet
memory: user
---

你是代码审查专家。

## 重要
- 每次审查前，先读一下你的记忆文件，看看之前发现过什么模式
- 审查完成后，把新发现的项目模式和常见问题记录到记忆中
- 随着时间积累，你的审查会越来越懂这个项目

┌──────────────────────────────────────────────────────────┐
│          memory 作用域                                     │
├──────────┬───────────────────────────────────────────────┤
│ 值        │ 效果                                           │
├──────────┼───────────────────────────────────────────────┤
│ user     │ 记忆跟用户绑定，跨项目共享（推荐默认）          │
│ project  │ 记忆跟项目绑定，只在当前项目生效                │
│ local    │ 记忆跟本地环境绑定                              │
│ 不设置    │ 无记忆，每次调用都是全新的                      │
└──────────┴───────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────┐
│     Claude Code 子代理体系总览                              │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  配置方面                                                 │
│  ├── 文件位置：.claude/agents/name.md                     │
│  ├── 必填字段：name + description                         │
│  ├── 可选字段：tools、model、memory                       │
│  └── 加载方式：启动时自动加载 或 /agents 手动加载          │
│                                                          │
│  运行方面                                                 │
│  ├── 独立上下文窗口（不继承主 Agent 的对话历史）           │
│  ├── 只接收自己的系统提示 + 被委派的任务                   │
│  ├── 最多 7 个并行                                        │
│  └── 完成后返回摘要给主 Agent                             │
│                                                          │
│  权限方面                                                 │
│  ├── tools 字段控制可用工具                                │
│  ├── 最小权限原则：只给必须的权限                         │
│  ├── 只读型：Read, Glob, Grep                            │
│  ├── 读写型：+ Write, Edit                               │
│  └── 执行型：+ Bash                                      │
│                                                          │
│  调用方面                                                 │
│  ├── 手动："使用 xxx 子代理 ..."                          │
│  ├── 自动：Claude 根据 description 匹配                  │
│  └── 组合：一个任务触发多个子代理                         │
│                                                          │
│  记忆方面                                                 │
│  ├── memory: user → 跨项目共享                           │
│  ├── memory: project → 项目专属                          │
│  └── 不设置 → 无记忆（每次全新）                          │
│                                                          │
└──────────────────────────────────────────────────────────┘