Claude Code 通关手册（五）：子代理系统——给你的 AI 配一个"专家团队"
这是「Claude Code 通关手册」系列的第 5 篇，共 10 篇。从这篇开始进入 Level 3（扩展篇），也是整个系列最有"差异化竞争力"的部分。
想象一个场景。
你是一个 Tech Lead，手下有三个专家——一个代码质量专家、一个测试工程师、一个安全顾问。你把一个 PR 链接丢到群里说"审一下"，三个人各自打开代码，从各自的专业角度分析，半小时后各出一份报告汇总到你桌上。
你只做一件事：看报告，做决定。
现在把"三个专家"换成"三个 AI 子代理"。你说一句"审查一下这个模块"，三个子代理同时开工——一个查代码质量、一个生成测试、一个扫描安全漏洞——各自在独立的上下文窗口里工作，互不干扰，最后把结果汇总给主 Agent。
这不是概念演示，这是 Claude Code 子代理系统现在就能跑的东西。
今天我把它讲透——从原理到实操，从创建你的第一个子代理到为 DevPulse 搭建一个三人"专家团队"。
为什么需要子代理？——"全科医生"的天花板
前面四篇，你一直在跟 Claude Code 的"主 Agent"一对一对话。它确实很强，但你用久了就会发现三个瓶颈：
瓶颈一：上下文窗口是有限的。
打个比方：你的桌子就这么大（上下文窗口就这么多 Token）。你让 Claude 同时看 20 个文件、记住你的编码规范、理解项目架构、还要分析性能问题——桌子上堆满了纸，它开始翻不过来了。分析质量肉眼可见地下降。
瓶颈二：不同任务需要不同的"专业视角"。
代码审查要关注的点和安全审计要关注的点完全不同。让一个 Agent 同时扮演审查专家和安全专家，就像让一个医生同时做心脏手术和脑科手术——不是做不到，是做不好。
瓶颈三：串行处理，效率有上限。
主 Agent 处理任务是排队的——先做 A、再做 B、再做 C。但很多任务其实可以并行——审查代码和写测试完全可以同时进行。
子代理系统解决了这三个问题：
code┌──────────────────────────────────────────────────────────┐
│ 子代理解决的三个核心问题 │
├──────────────────────────────────────────────────────────┤
│ │
│ 问题 子代理的解决方案 │
│ ───────────────────────────────────────── │
│ 上下文窗口不够用 每个子代理有独立的上下文窗口 │
│ → 互不干扰，各自深度分析 │
│ │
│ 缺少专业分工 每个子代理有专属系统提示 │
│ → 代码专家只管代码，安全专家只管安全 │
│ │
│ 串行效率低 最多 7 个子代理并行工作 │
│ → 三份报告同时出，时间不变 │
│ │
└──────────────────────────────────────────────────────────┘用更直观的比方来说：
主 Agent 是你公司的"全科医生"——什么都能看，但看不深。子代理是你配的"专科医生团队"——心内科、骨科、神经科各管各的，每个人在自己的诊室（独立上下文）里看病，最后把诊断结果汇总给你这个主治医生。
子代理的运行机制
在动手之前，先花一分钟理解子代理是怎么运行的：
code┌──────────────────────────────────────────────────────────┐
│ 子代理运行流程 │
├──────────────────────────────────────────────────────────┤
│ │
│ 你: "审查 @src/app/api/ 下的所有 API 路由" │
│ ↓ │
│ ┌──────────────────────────────────────┐ │
│ │ 主 Agent（调度中心） │ │
│ │ 分析任务 → 选择合适的子代理 │ │
│ │ 或者：你手动指定用哪个子代理 │ │
│ └──────┬──────────┬──────────┬─────────┘ │
│ ↓ ↓ ↓ │
│ ┌──────────┐┌──────────┐┌──────────┐ │
│ │code ││test ││security │ │
│ │reviewer ││writer ││auditor │ │
│ │ ││ ││ │ │
│ │独立上下文 ││独立上下文 ││独立上下文 │ │
│ │独立权限 ││独立权限 ││独立权限 │ │
│ │专属提示词 ││专属提示词 ││专属提示词 │ │
│ └──────┬───┘└──────┬───┘└──────┬───┘ │
│ ↓ ↓ ↓ │
│ ┌──────────────────────────────────────┐ │
│ │ 主 Agent（汇总结果） │ │
│ │ 整合三份报告 → 呈现给你 │ │
│ └──────────────────────────────────────┘ │
│ │
│ 关键特性： │
│ • 每个子代理有自己的上下文窗口（最大 200K） │
│ • 子代理只接收自己的系统提示，不会继承主 Agent 的全部上下文│
│ • 最多 7 个子代理同时并行 │
│ • 子代理完成后返回摘要给主 Agent │
│ │
└──────────────────────────────────────────────────────────┘关键点：子代理的上下文是隔离的。 它不会继承你跟主 Agent 之间的长对话历史，只接收自己的系统提示和被委派的具体任务。这正是它的优势——干净的上下文 = 聚焦的分析。
创建你的第一个子代理
子代理的定义文件跟 Slash 命令一样简单——一个 Markdown 文件搞定。
文件位置：
.claude/agents/——项目级（提交到 Git，团队共享）~/.claude/agents/——全局个人级（所有项目可用）
最小示例：
bashmkdir -p .claude/agents创建 .claude/agents/code-reviewer.md：
markdown---
name: code-reviewer
description: 审查代码质量，关注 TypeScript 类型安全、React 最佳实践和性能问题
tools: Read, Glob, Grep
model: sonnet
---
你是一个严格但公正的代码审查专家，专注于 React + TypeScript 项目。
## 你的审查原则
- 先理解代码意图，再指出问题
- 每个问题必须给出修改建议，不要只说"这里有问题"
- 区分严重程度：🔴 必须修复 / 🟡 建议优化 / 🟢 可选改进
## 审查清单
1. TypeScript 类型安全（any、类型断言、缺失类型）
2. 组件设计（单一职责、Props 接口、Server/Client 划分）
3. 性能隐患（不必要重渲染、缺少 memo、常量提取）
4. 可读性（命名、注释、代码结构）
## 输出格式
按文件逐个分析，每个问题包含：
- 📍 位置（文件名 + 行号范围）
- ❓ 问题描述
- ✅ 修改建议（附代码）就这样，一个子代理就创建好了。
加载方式：子代理在会话启动时自动加载。如果你在会话中新建了文件，用 /agents 命令可以立即加载，不用重启。
调用方式：
bash# 手动指定调用
使用 code-reviewer 子代理审查 @src/components/ArticleCard.tsx
# 或者直接描述任务，Claude 自动匹配
审查一下 ArticleCard 组件的代码质量
# → Claude 看到 code-reviewer 的描述匹配，自动委派实操：为 DevPulse 搭建三人专家团队
现在给 DevPulse 项目创建三个各司其职的子代理。
子代理一：code-reviewer（代码审查专家）
.claude/agents/code-reviewer.md：
markdown---
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）和一句话总结。注意这里的 tools: Read, Glob, Grep——只给了只读权限。审查专家只需要看代码，不需要改代码。这就是最小权限原则。
子代理二：test-writer（测试工程师）
.claude/agents/test-writer.md：
markdown---
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 验证测试通过
- 报告测试覆盖数据这个子代理需要 Write 和 Edit 权限来创建测试文件，以及 Bash 权限来运行测试命令。
子代理三：security-auditor（安全审计专家）
.claude/agents/security-auditor.md：
markdown---
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┌──────────────────────────────────────────────────────────┐
│ 子代理权限对比 │
├────────────────┬──────────────────┬──────────────────────┤
│ 子代理 │ 权限 │ 设计理由 │
├────────────────┼──────────────────┼──────────────────────┤
│ code-reviewer │ Read, Glob, Grep │ 只看不改。审查不应该 │
│ │ （只读） │ 自动修改代码 │
├────────────────┼──────────────────┼──────────────────────┤
│ test-writer │ Read, Write, │ 需要创建测试文件和 │
│ │ Edit, Glob, │ 运行测试命令 │
│ │ Grep, Bash │ │
├────────────────┼──────────────────┼──────────────────────┤
│ security- │ Read, Glob, Grep │ 只看不改。安全审计 │
│ auditor │ （只读） │ 不应该改动任何代码 │
└────────────────┴──────────────────┴──────────────────────┘
原则：最小权限。
每个子代理只给它完成任务所必须的权限，多一个都不给。为什么这么较真？因为子代理是独立运行的——你不会实时看到它的每一步操作。如果给安全审计子代理写权限，万一它"好心"帮你修改了代码但改错了呢？只读权限 = 零副作用 = 绝对安全。
使用演示：三种调用方式
方式一：手动指定子代理
最明确的方式，适合你知道该用谁的时候：
code使用 code-reviewer 子代理审查 @src/app/api/posts/route.tscode用 security-auditor 扫描 @src/app/api/ 目录下所有 API 路由的安全漏洞code让 test-writer 为 @src/components/ArticleCard.tsx 编写单元测试方式二：自然语言描述，Claude 自动委派
你不需要记住子代理的名字——只要任务描述足够清晰，Claude 会根据每个子代理的 description 字段自动匹配最合适的那个：
code帮我检查这个 API 有没有 SQL 注入风险
→ Claude 自动选择 security-auditorcode给 ArticleCard 组件写一套完整的测试
→ Claude 自动选择 test-writer自动委派的准确度取决于你子代理的 description 写得多清晰。如果描述太模糊，Claude 可能选错人。所以 description 字段要写得具体——不是"通用助手"，而是"检查 XSS、注入攻击和认证绕过的安全审计专家"。
方式三：组合调用，多代理协作
这是最强大的用法——一句话触发多个子代理：
code对 @src/app/api/posts/route.ts 做一次完整审查：
1. 代码质量审查
2. 安全漏洞扫描
3. 补充缺失的测试Claude 会理解你需要三个维度的分析，分别委派给对应的子代理，然后汇总结果。
你还可以更显式地要求协作：
code先让 code-reviewer 审查 @src/components/ArticleCard.tsx，
然后基于审查结果，让 test-writer 补充测试覆盖这样 test-writer 就能参考审查报告来决定哪些地方需要重点测试。
查看和管理子代理
几个实用的管理命令：
bash# 查看当前可用的所有子代理
/agents
# 创建新子代理（交互式引导）
/agents create/agents 命令会列出所有已加载的子代理，包括内置的和你自定义的。
Claude Code 自带三个内置子代理，即使你不创建任何自定义子代理也可以使用：
code┌──────────────────────────────────────────────────────────┐ │ 内置子代理 │ ├────────────┬─────────────────────────────────────────────┤ │ 名称 │ 用途 │ ├────────────┼─────────────────────────────────────────────┤ │ Explore │ 文件探索——搜索、阅读、发现代码库中的内容 │ │ Plan │ 方案规划——研究代码库后制定执行方案 │ │ general- │ 通用子代理——处理复杂多步骤任务 │ │ purpose │ │ └────────────┴─────────────────────────────────────────────┘
你自定义的子代理跟它们是叠加关系——你有专门的就用专门的，没有的时候 Claude 用内置的。
进阶：子代理的记忆（Memory）
子代理有一个非常有价值的进阶功能——持久化记忆。
正常情况下，子代理每次被调用都是"全新的"，不记得上一次做了什么。但你可以通过 memory 字段让它拥有持久化的笔记本：
markdown---
name: code-reviewer
description: 代码质量审查
tools: Read, Glob, Grep
model: sonnet
memory: user
---
你是代码审查专家。
## 重要
- 每次审查前，先读一下你的记忆文件，看看之前发现过什么模式
- 审查完成后，把新发现的项目模式和常见问题记录到记忆中
- 随着时间积累，你的审查会越来越懂这个项目memory 字段的可选值：
code┌──────────────────────────────────────────────────────────┐
│ memory 作用域 │
├──────────┬───────────────────────────────────────────────┤
│ 值 │ 效果 │
├──────────┼───────────────────────────────────────────────┤
│ user │ 记忆跟用户绑定，跨项目共享（推荐默认） │
│ project │ 记忆跟项目绑定，只在当前项目生效 │
│ local │ 记忆跟本地环境绑定 │
│ 不设置 │ 无记忆，每次调用都是全新的 │
└──────────┴───────────────────────────────────────────────┘有了记忆之后，你的 code-reviewer 审查得越多，就越了解你的项目——它会记住"这个项目经常出现忘记标注 'use client' 的问题"、"API 路由经常缺少输入校验"这些模式。随着时间推移，审查质量会持续提升。
常见陷阱 & 最佳实践
❌ 陷阱一：一上来就创建一堆子代理
你不需要一开始就配置 10 个子代理。从 1-2 个最高频的开始，用熟了再加。上面的三个（审查、测试、安全）是经过验证的黄金组合，覆盖了代码质量的三个核心维度。
❌ 陷阱二：给子代理过宽的权限
test-writer 需要 Bash 权限来运行测试，但 code-reviewer 和 security-auditor 不需要。审查类的子代理永远只给只读权限。
❌ 陷阱三：系统提示太笼统
"你是一个代码审查专家"——太空了。Claude 本来就会审查代码，你不需要告诉它这个。你需要告诉它的是：这个项目的具体审查标准是什么、什么级别的问题需要什么级别的处理、输出格式长什么样。 越具体，结果越好。
✅ 最佳实践一：定义清晰的输出格式
每个子代理都应该有明确的输出格式定义。表格、分级、评分——让输出结构化，方便你快速扫描和做决定。
✅ 最佳实践二：先手动调用建立信任
初期阶段手动指定子代理（"使用 code-reviewer 审查..."），观察它的输出质量。满意了再逐步转向自然语言描述让 Claude 自动委派。信任是需要积累的。
✅ 最佳实践三：把子代理配置提交到 Git
.claude/agents/ 目录应该提交到版本控制。这样团队里的每个人都能使用相同的子代理配置，保证审查标准的一致性。
一张图总结子代理体系
code┌──────────────────────────────────────────────────────────┐
│ 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 → 项目专属 │
│ └── 不设置 → 无记忆（每次全新） │
│ │
└──────────────────────────────────────────────────────────┘本篇小结
三个核心收获：
第一，子代理解决了主 Agent 的三个天花板——上下文有限、缺少专业分工、串行效率低。每个子代理有独立的上下文窗口、专属的系统提示、独立的权限，最多 7 个并行工作。
第二，一个 Markdown 文件就能定义一个子代理。name + description 是必填的，tools 控制权限，model 选择模型，memory 开启记忆。创建成本极低，收益极高。
第三，审查（code-reviewer）+ 测试（test-writer）+ 安全（security-auditor）是经过验证的黄金三角组合。审查和安全只给只读权限，测试给读写+执行权限。先从这三个开始，熟练后再根据需要扩展。
通关检查清单
- 理解子代理的运行机制（独立上下文、委派执行、返回摘要）
- 创建了 code-reviewer 子代理并成功调用
- 创建了 test-writer 子代理并成功运行测试
- 创建了 security-auditor 子代理并完成安全扫描
- 理解最小权限原则（只读 vs 读写 vs 执行）
- 知道 /agents 命令查看所有可用子代理
- 尝试过多代理组合调用
全部打勾？Level 3 第一关通过。
下篇预告
第 6 篇：Claude Code 通关手册（六）—— MCP 协议：让你的 AI 连接 GitHub、数据库和整个开发生态
子代理让你有了一个"AI 团队"，但这个团队目前只能看代码。如果它能直接连上 GitHub 查 Issue、连上数据库查数据、连上浏览器做端到端测试呢？
这就是 MCP（Model Context Protocol）要做的事——给 Claude Code 装上"外接设备"。下一篇，我带你配置 GitHub MCP、Playwright MCP，让 Claude 从"只能看本地代码"进化到"连接整个开发生态"。
今日话题
如果你能配置 3 个 AI 专家团队成员，你会选哪 3 个角色？代码审查、测试、安全——还是有其他你更想要的？比如性能分析师、文档工程师、DevOps 专家？评论区分享你的理想配置。
如果这篇文章让你对"AI 团队"有了新的想象，欢迎点赞、在看、转发三连——这可能是全网把 Claude Code 子代理讲得最通俗的文章了。
关注「前端达人」，我们下篇见。
如果这篇对你有帮助，欢迎关注公众号「前端达人」，每周更新实用前端干货。
