Claude Code通关手册（五）：组建你的AI专家团队，子代理系统

这是Claude Code通关手册的第五篇，这一篇将把"万能助手"变成一支专业队伍，各司其职、并行作战，这才是 Claude Code 的正确打开方式

先来看一个熟悉的场景

你面对一个复杂的任务，突然萌生了这样的想法：

"要是能有个专门负责探索代码库的助手，再有个专门审查代码的专家，还有个专注写测试的工程师，大家各司其职、同时开工，那该多爽？"

------这不是天方夜谭，这正是 Claude Code 子代理（Subagent）的核心价值。

什么是子代理？

简单说，子代理就是给 AI 指定一个专门的角色。不再说"帮我搞定所有事"，而是明确告诉它："你现在是测试员"、"你负责安全审查"、"你是重构专家"。

在技术层面上，每个子代理都是一个拥有独立上下文窗口的专用 AI 实例。当你在 Claude Code 主对话中下达任务时，Claude 可以判断该任务是否适合委派给某个子代理，由子代理独立完成后将结果摘要返回主对话。

为什么需要子代理？

Claude Code功能确认很强大，但是在实际使用的过程中就会发现当我们让Cladue Code执行一些复杂的任务时并没有得到很好的结果------随手丢给 Claude 一句话------"重构这段代码，找出 bug，写测试，优化性能，顺便解释一下"。

Claude 确实很努力，但结果一塌糊涂：可能在重构时动了业务逻辑，解释写了一半就没了下文，测试跟项目框架对不上，性能建议全是泛泛而谈的套话。

三大瓶颈，让"万能助手"力不从心。

瓶颈一：上下文窗口是有限的

Claude Code 的上下文窗口就像你的办公桌。桌子就这么大，能同时摊开的文件就这么多。

让 Claude 同时看 20 个文件、记住你的编码规范、理解项目架构、还要分析性能问题------桌子上堆满了纸，它开始翻不过来了。分析质量肉眼可见地下降，重要的信息被挤到角落，Claude 开始"遗忘"你十分钟前强调过的规范。

瓶颈二：不同任务需要不同的"专业视角"

代码审查要关注的点和安全审计要关注的点完全不同。

让一个 Agent 同时扮演审查专家和安全专家，就像让一个医生同时做心脏手术和脑科手术------不是做不到，是做不好。一个模型在同一个系统提示词里既要说"关注代码可读性"，又要说"检查 SQL 注入风险"，最后的结果往往是两头都不够深入。

专注比全能更可靠。

瓶颈三：串行处理，效率有上限

主 Agent 处理任务是排队的------先做 A、再做 B、再做 C。你让它"分析代码、写测试、审查安全、生成文档"，它只能一件一件来。

但很多任务其实可以并行------分析代码结构、审查最近的改动、为某个模块写单元测试，这三件事完全可以同时进行。串行处理就像只有一个人在生产线上干活，其他人都在等。

子代理就是针对这三个瓶颈的设计答案：

• 保留上下文 - 将探索和实现保留在独立上下文中，不污染主对话
• 强制约束 - 限制 子代理 可使用的工具
• 复用配置 - 用户级 子代理 跨项目可用
• 专业化行为 - 使用专注的系统提示处理特定领域
• 控制成本 - 将任务路由到更快、更便宜的模型如 Haiku

一个简单的比方

你是一个团队的开发经理。你手头有三个任务：探索代码库的结构、审查最近的改动、为某个模块写单元测试。

你可以自己把这三件事一件一件做完------很累，而且容易被打断思路。

但如果你手下有三个专家：一个专门负责扫遍代码库，一个专门盯着代码质量，一个专门写测试用例------你把任务分派下去，让他们同时开工，然后等着收结果就行。

子代理就是这三个专家。 它们各有自己的"工位"（独立上下文），有自己的"工具箱"（受限的工具权限），有自己的"工作手册"（专门的系统提示词），只专注于自己擅长的事情。

内置子代理

在你动手创建之前，Claude Code 本身就自带了几位"员工"。你不用做任何配置，它们随时待命。

子代理	使用模型	专长
Plan	继承主对话	Plan mode 下的代码库研究和上下文收集（只读）
Explore	Haiku（快速）	搜索和分析代码库（只读）
General-purpose	继承主对话	复杂多步任务（全工具权限）

也就是说，当你需要 Claude 在 Plan Mode 下做研究时，它会自动调用 Plan 子代理；当需要快速扫遍整个代码库搜索某个模式时，Explore 子代理会出马；当遇到一个需要独立调查的复杂任务时，General-purpose 子代理会被激活。

你甚至不需要知道它们的存在------它们就在后台默默地工作，然后把结果返给你。

创建你的第一个子代理

手动创建

和自定义命令一样，子代理可以通过一个markdown文件搞定

文件位置：

• .claude/agents/------项目级（提交到 Git，团队共享）
• ~/.claude/agents/------全局个人级（所有项目可用）
• 插件的 agents/ 目录 ------启用该插件的项目

一个简单的子代理示例：

---
name: code-reviewer
description: 审查代码质量和最佳实践
tools: Read, Glob, Grep
model: sonnet
---

你是代码审查员。被调用时，分析代码并提供
关于质量、安全性和最佳实践的具体、可操作的反馈。

使用 /agents 命令

可以在交互式界面使用/agents命令创建子代理

选择 Create new agent ，然后选择 User-level （用户级，跨项目可用）或 Project-level （项目级）。

选择 Generate with Claude，描述你想要的 Subagent：

一个代码改进代理，扫描文件并建议可读性、性能和最佳实践的改进。
它应该解释每个问题，展示当前代码，并提供改进版本。

Claude 会生成系统提示和配置。

选择工具和模型

• 工具 ：选择 Subagent 可用的工具。只读审查器只需 Read-only tools
• 模型 ：选择 Sonnet （平衡能力和速度）、Opus （最强）、Haiku （最快）或 inherit（继承主对话）
• 背景色：为 Subagent 选择背景颜色，帮助在 UI 中识别正在运行的是哪个 Subagent。

元数据字段说明

• name：唯一标识符
• description：描述何时应委托给此子代理
• tools：可用工具列表，省略则继承所有工具
• disallowedTools：禁用的工具
• model：sonnet、opus、haiku 或 inherit，默认 sonnet
• permissionMode：权限模式
• skills：要加载的 Skills 列表
• hooks：生命周期钩子

实战演练：创建你的AI专家团队

调试分析专家

---
name: debugger
description: 错误、测试失败和意外行为的调试专家。遇到任何问题时主动使用。
tools: Read, Edit, Bash, Grep, Glob
---

你是专注于根因分析的调试专家。

被调用时：
1. 捕获错误信息和堆栈跟踪
2. 识别复现步骤
3. 定位失败位置
4. 实现最小修复
5. 验证解决方案有效

调试过程：
- 分析错误信息和日志
- 检查最近代码更改
- 形成并测试假设
- 添加策略性调试日志
- 检查变量状态

对于每个问题，提供：
- 根因解释
- 支持诊断的证据
- 具体代码修复
- 测试方法
- 预防建议

专注于修复根本问题，而非症状。

代码审查专家

---
name: code-reviewer
description: 专业代码审查员。代码修改后主动审查质量、安全性和可维护性。
tools: Read, Grep, Glob, Bash
model: inherit
---

你是确保高标准代码质量和安全性的资深代码审查员。

被调用时：
1. 运行 git diff 查看最近更改
2. 关注修改的文件
3. 立即开始审查

审查清单：
- 代码清晰可读
- 函数和变量命名良好
- 没有重复代码
- 错误处理得当
- 没有暴露的密钥或 API 密钥
- 实现了输入验证
- 测试覆盖良好
- 考虑了性能

按优先级组织反馈：
- 严重问题（必须修复）
- 警告（应该修复）
- 建议（考虑改进）

包含如何修复问题的具体示例。

测试专家

---
name: test-expert
description: 专业的单元测试编写专家。当需要为 Java/Spring Boot 类编写单元测试时使用。
tools: Read, Write, Edit, Glob, Grep
model: sonnet
---
你是资深单元测试工程师，专注为 Java/Spring Boot 项目编写高质量单元测试。
## 技术栈
- JUnit 5 (Jupiter)
- Mockito (mock 依赖)
- AssertJ 或 JUnit 断言
## 工作流程
1. 读取目标类的源代码
2. 识别所有 public 方法及其参数、返回值、异常
3. 分析每个方法的分支逻辑（正常路径、异常路径、边界条件）
4. 生成测试类，覆盖：
   - 正常场景（happy path）
   - 边界值（null、空集合、极限值）
   - 异常场景（预期抛出的 BusinessException）
5. 测试类命名：`原类名 + Test`
6. 测试方法命名：`方法名_场景描述_预期结果`
## 强制规范
- 使用 `@ExtendWith(MockitoExtension.class)`
- 被测试类使用 `@InjectMocks`，依赖使用 `@Mock`
- 每个测试方法必须独立，不依赖其他测试
- 禁止使用 `Thread.sleep()` 或真实数据库连接
- 测试代码也要可读：given-when-then 结构
## 输出
- 直接写入 `src/test/java/` 对应包路径下
- 如果测试类已存在，只补充缺失的测试方法，不覆盖已有内容

使用演示：三种调用方式

最明确的方式，适合你知道该用谁的时候：

方式一：手动指定子代理

使用 code-reviewer 子代理 找出性能问题

方式二：自然语言描述，Claude 自动委派

你不需要记住子代理的名字------只要任务描述足够清晰，Claude 会根据每个子代理的 description 字段自动匹配最合适的那个：

帮我为当前打开的文件生成单元测试

方式三：组合调用，多代理协作

使用 code-reviewer 子代理 找出问题，然后使用 debugger 子代理 修复它们

进阶知识：子代理的记忆功能

子代理有一个非常有价值的进阶功能------持久化记忆。

正常情况下，子代理每次被调用都是"全新的"，不记得上一次做了什么。但你可以通过 memory 字段让它拥有持久化的笔记本：

---  
name: code-reviewer  
description: 代码质量审查  
tools: Read, Glob, Grep  
model: sonnet  
memory: user  
---  
  
你是代码审查专家。  
  
## 重要  
- 每次审查前，先读一下你的记忆文件，看看之前发现过什么模式  
- 审查完成后，把新发现的项目模式和常见问题记录到记忆中  
- 随着时间积累，你的审查会越来越懂这个项目

有了记忆之后，你的 code-reviewer 审查得越多，就越了解你的项目------它会记住这个项目经常出现的问题。随着时间推移，审查质量会持续提升。

子代理的记忆功能可以设置作用域：

• user：用户绑定，跨项目共享（推荐默认）
• project：记忆跟项目绑定，只在当前项目生效
• local：记忆跟本地环境绑定
• 不设置：每次调用都是全新的

常见陷阱

一开始就创建一堆子代理❌

不需要一开始就配置 10 个子代理。从 1-2 个最高频的开始，用熟了再加。上面的审查、测试是经过验证的开发人员的黄金组合

给子代理过宽的权限❌

test-writer 需要 Bash 权限来运行测试，但 code-reviewer 和 security-auditor 不需要。审查类的子代理永远只给只读权限。

系统提示太笼统❌

"你是一个代码审查专家"------太空了。Claude 本来就会审查代码，你不需要告诉它这个。你需要告诉它的是：这个项目的具体审查标准是什么、什么级别的问题需要什么级别的处理、输出格式长什么样。 越具体，结果越好。

总结

Claude Code 的子代理功能不仅是一个新特性，它代表了 AI 辅助开发模式的根本性转变：从单一的"全能助手"转向专业化的"AI 团队协作"。

• 内置子代理：Explore、Plan、General-purpose------开箱即用
• 创建方式 ：/agents 交互命令（推荐）、Markdown 文件、CLI 参数
• 调用方式：自动委派（语义匹配）或显式调用
• 核心价值：上下文隔离、专业化分工、并行处理、权限可控

下一篇预告 ：我们来聊聊 MCP（模型上下文协议）------让 Claude Code 连接你的数据库、Jira、GitHub......真正做到"懂你的整个工作流"。