Claude Code Subagents 进化指南：从牛马到老板

我是 Quentin，OpenClaw 拼车的维护者。这篇是我整理的 Claude Code 子代理（Subagents） 完全指南。

子代理是 Claude Code 1.0.60 引入的功能，直接把 AI 编程从「单兵工具」升级成「专业团队」。一夜之间你不再是写代码的牛马，而是一个有专业 AI 团队的小老板：审查代码的、调试 bug 的、写文档的、跑测试的，分别由不同子代理负责，各自独立思考，互不打扰。

读完这篇你会知道：什么是子代理、为什么它是质变而不是量变、怎么在 5 分钟内创建一个、官方推荐的最佳实践、以及几个我自己在用的实战模板。

拼车前置：子代理会显著放大 token 消耗（每个子代理都是独立上下文）。OpenClaw 拼车一行接通 Max 20× 配额：
curl -fsSL https://cp.bizq.net/setup.sh | bash -s -- claude-max-20x

一、什么是子代理？

想象你正在管理一个开发团队，每个成员都有自己的专长：有人擅长代码审查，有人精通调试，有人专注数据分析。Claude Code 的子代理功能正是基于这种思路——让 AI 助手也能像团队一样针对不同任务调用专门的「AI 专家」。

按官方文档，子代理是预配置的 AI 助手，它们：

拥有特定的专业领域和任务类型
使用独立的上下文窗口，与主对话完全隔离
可以配置特定的工具访问权限
通过自定义系统提示词来引导其行为

当 Claude Code 遇到适合某个子代理处理的任务时，它会智能地把任务委派给相应的专家，就像一个优秀的项目经理分配任务一样。

二、四大核心优势

1. 上下文保护（Context Preservation）

每个子代理都在独立的上下文中运行。处理复杂任务时不会污染主对话。主线程保持专注于高层目标，具体的实现细节由子代理在各自的「工作空间」中完成。

这是子代理最被低估的好处——它让长会话的可持续性大大提升。一个主上下文跑大半天还能保持清醒。

2. 专业化能力（Specialized Expertise）

通过为特定领域定制详细的指令，子代理在其专长领域能达到更高成功率。比如一个专门的「代码审查」子代理，可以包含详细的代码规范、检查清单、安全 checklist——比通用 prompt 更精准。

3. 可重用性（Reusability）

一旦创建，子代理可以跨项目复用，甚至可以与团队成员共享。意味着团队可以逐步积累一套强大的 AI 工具库，把工作流程标准化。

4. 灵活的权限管理（Flexible Permissions）

每个子代理可以配置不同的工具访问级别。例如：

「数据分析」子代理：访问文件系统和数据处理工具
「代码格式化」子代理：只能读取和编辑代码，不能跑 shell
「文档生成」子代理：只能写 docs/ 目录，禁动业务代码

这给了一种最小权限的安全姿态。

三、配置子代理：5 分钟实操

第 0 步：打开子代理界面

在 Claude Code 内输入：

/agents

进入子代理管理界面。第一次打开是空的。

第 1 步：选择「Create New Agent」

进入后选择「Create New Agent」。子代理有自己的上下文、自己的系统提示词、自己的工具配置。

第 2 步：选择存储位置

类型	存储路径	适合场景
项目级	`.claude/agents/`	团队共享，提交进 git
用户级	`~/.claude/agents/`	个人通用，跨项目复用

我的习惯：通用工具型子代理（debugger、code-reviewer、test-writer）放用户级；项目专属业务流程子代理（migration-runner、release-bot）放项目级。

第 3 步：选择创建方式

两种方式：

让 Claude 根据描述自动生成：推荐新手，输入一段需求描述，Claude 直接产出第一版子代理配置
完全自定义：自己写 name、description、tools、prompt 全套

新手强烈建议先用「Claude 自动生成」，再二次修改细节。

第 4 步：选择工具权限

按回车选中 / 取消选中。空格表示未选中。

通用建议：

调试类子代理：Read, Edit, Bash, Grep, Glob
审查类子代理：Read, Grep, Glob（不要给 Edit，它的工作就是给意见）
文档类子代理：Read, Edit, Grep（可以编辑，但不能跑 shell）

第 5 步：选择背景颜色

设计很贴心——执行时可以通过颜色判断哪个子代理在工作。颜色不同表示当前在子代理上下文里跑，不会和主对话混淆。

最后：预览与保存

系统会展示完整信息：名称、位置、工具、系统提示词。回车保存。退出后会显示已创建的子代理列表。

命名规则

注意：不支持中文，不能有空格。只能用英文、数字、横线。例：code-reviewer、bug-debugger、api-doc-writer。

四、子代理文件结构

每个子代理都是一个 Markdown 文件，存在 ~/.claude/agents/ 或 .claude/agents/。格式：

---
name: code-reviewer
description: 专门进行代码质量审查，检查代码规范、潜在 bug 和性能问题。使用时请主动调用。
tools: Read, Grep, Glob
---
 
# 代码审查专家
 
你是一个经验丰富的代码审查专家，专注于：
 
1. **代码质量检查**
   - 遵循项目编码规范
   - 识别潜在的 bug 和安全问题
   - 提出性能优化建议
 
2. **最佳实践**
   - 确保代码可读性和可维护性
   - 检查错误处理是否完善
   - 验证测试覆盖率
 
3. **审查流程**
   - 首先理解代码的整体结构
   - 逐个检查每个函数和模块
   - 提供具体的改进建议

tools 字段省略 = 继承主线程所有工具权限（不推荐，违反最小权限原则）。

五、如何使用子代理

最简单：直接在 prompt 里指定。

用 code-reviewer 帮我排查这个项目可能存在的问题

Claude 会切到 code-reviewer 子代理，在新的上下文里跑，跑完后把结论合并回主对话。颜色不同就是在告诉你「这是子代理在说话」。

隐式调用

更强大的用法：让 Claude 自动选择合适的子代理。

只要在子代理的 description 字段里写：

description: 专门处理错误、测试失败和异常行为的调试专家。**遇到任何 bug 时主动使用。**

或者带上关键词：

PROACTIVELY
MUST BE USED

Claude 看到任务符合 description 就会自动委派。不用你手动指定。

六、实战模板

下面三个是我自己日常用得最多的子代理。直接复制保存到 ~/.claude/agents/<name>.md 就能用。

模板 1：debugger（调试大师）

---
name: debugger
description: 专门处理错误、测试失败和异常行为的调试专家。遇到任何问题时主动使用。
tools: Read, Edit, Bash, Grep, Glob
---
 
# 调试专家
 
你是一个专精于根因分析的调试专家。被调用时的工作流程：
 
1. 捕获错误信息和堆栈跟踪
2. 识别复现步骤
3. 定位故障位置
4. 实施最小化修复
5. 验证解决方案有效性
 
调试过程：
- 分析错误信息和日志
- 检查最近的代码变更（git log / git diff）
- 形成并测试假设
- 添加策略性调试日志
- 检查变量状态
 
对每个问题，需要提供：
- 根本原因解释
- 支持诊断的证据
- 具体的代码修复方案
- 测试方法
- 预防建议
 
专注于修复根本问题，而非表面症状。

模板 2：data-scientist（数据分析师）

---
name: data-scientist
description: 数据分析专家，专精于 SQL 查询、BigQuery 操作和数据洞察。处理数据分析任务时主动使用。
tools: Bash, Read, Write
---
 
# 数据科学家
 
你是一个专精于 SQL 和 BigQuery 分析的数据科学家。被调用时的工作流程：
 
1. 理解数据分析需求
2. 编写高效的 SQL 查询
3. 适时使用 BigQuery 命令行工具（bq）
4. 分析并总结结果
5. 清晰地呈现发现
 
关键实践：
- 编写带有适当过滤条件的优化 SQL 查询
- 使用合适的聚合和连接操作
- 为复杂逻辑添加注释说明
- 格式化结果以提高可读性
- 提供数据驱动的建议
 
对每项分析：
- 解释查询方法
- 记录所有假设
- 突出关键发现
- 基于数据提出后续步骤建议
 
始终确保查询高效且成本可控。

模板 3：code-reviewer（代码审查官）

---
name: code-reviewer
description: 代码审查专家，关注 bug、安全漏洞、性能问题。提交前 PROACTIVELY 使用。
tools: Read, Grep, Glob
---
 
# 代码审查官
 
你只做审查，不做修改。每次被调用：
 
1. 读取最近改动的文件（git diff）
2. 找出**真实**的问题，不是风格点评：
   - 逻辑 bug
   - 边界条件未覆盖
   - 资源泄漏（未关闭的文件、连接、订阅）
   - 安全漏洞（SQL 注入、XSS、命令注入、权限校验）
   - 性能死角（N+1 查询、不必要的循环、阻塞调用）
3. 检查测试覆盖：每个新分支都有对应测试吗？
 
**输出格式**：
- 严重程度：🔴 必须修 / 🟡 建议修 / 🟢 优化建议
- 文件:行号
- 一句话说明
- 建议方案
 
**不要**：
- 评价命名风格（除非命名直接产生歧义）
- 重复代码评论里已经说过的内容
- 写超过 3 行的解释

七、高级技巧

1. 子代理链式调用

可以通过复杂工作流串联多个子代理：

首先让 code-reviewer 检查代码，
然后让 performance-optimizer 优化性能，
最后让 doc-writer 更新相关文档

Claude 会按顺序调用，每个子代理跑完再传给下一个。

2. 动态子代理选择

Claude Code 会根据上下文智能选择子代理。在 description 字段里加：

PROACTIVELY ← 增加自动调用概率
MUST BE USED for X ← 几乎强制
Use when Y ← 触发条件描述

3. 显式调用

直接指名：

用 debugger 子代理来分析这个错误

不需要担心 Claude「忘了」用——你说了它就一定用。

八、最佳实践

从 Claude 生成开始

官方强烈推荐先让 Claude 根据需求生成初始子代理，然后逐步迭代。从零写 system prompt 容易遗漏关键约束，让 Claude 给你一版骨架更高效。

保持专注性

每个子代理应该有单一、明确的职责。避免创建「全能型」子代理——那会退化回普通 Claude，子代理的价值就消失了。

详细的系统提示

system prompt 里包含：

具体的角色定义
输入 / 输出格式
步骤化工作流
关键约束（不要做什么）
1~2 个示例

合理授权工具

只授予必要的工具权限：

安全（不会跑出格命令）
帮助子代理专注于相关操作（少了 Bash 它就不会想去开 shell 节省时间）

版本控制集成

将项目级子代理纳入版本控制（提交 .claude/agents/），方便团队协作和持续改进。新人 clone 项目就自动得到团队的 AI 工作伙伴。

九、性能考量

子代理虽好，但也有代价：

上下文效率：子代理保护主上下文，让整体会话能持续更长时间 ✅
延迟考虑：每次调用子代理都从零开始，需要时间收集上下文 ⚠️
token 消耗：每个子代理是独立上下文，token 消耗叠加 ⚠️

何时用 / 不用：

任务类型	用子代理？
简单单步修改	❌ 不用，直接主对话
调试复杂 bug	✅ debugger 子代理
多文件代码审查	✅ code-reviewer 子代理
跑一次单元测试	❌ 主对话直接跑
完整功能开发链路	✅ 链式调用多个子代理
一次格式化	❌ 直接 prettier

简单任务不需要子代理——子代理是给复杂的多方面查询用的，简单任务它反而是 overhead。

十、未来展望

子代理标志着 AI 编程助手向「智能、专业团队」方向发展。它不再是简单的代码生成工具，而是一个能够理解任务、智能分工、高效协作的 AI 团队。

通过子代理，开发者可以：

构建专属的 AI 开发团队
标准化团队工作流程
积累和分享专业知识
大幅提升开发效率

随着越来越多开发者创建和分享自己的子代理，一个丰富的 AI 工具生态正在形成。未来，我们可能只需要简单地描述需求，Claude Code 就能自动调配合适的子代理组合，像一个经验丰富的技术负责人一样高效地完成复杂任务。

十一、立即开始

子代理是 Claude Code 当前最值得花一小时配置的功能——配置一次，受益数月。

curl -fsSL https://cp.bizq.net/setup.sh | bash -s -- claude-max-20x
claude

进入 Claude Code 后：

/agents

挑一个你最想自动化的角色（debugger / code-reviewer / test-writer），让 Claude 帮你生成第一版，跑两个真实任务调一调，就有自己的专属 AI 团队了。

更多文档见 https://cp.bizq.net。

Claude Code 高阶玩家指南 — 子代理之外的所有高阶用法
Claude Code MCP 服务器入门 — 给子代理装上专业工具
CLAUDE.md 约束提示词指南 — 子代理的 system prompt 怎么写

Claude Code：拉开新时代差距的真正变量 Claude Code Vibe Coding 工作流：从规范到落地