Subagents
课程导读
这节课介绍 Claude Code 的 Subagents，也就是子代理。你可以把子代理理解成主代理派出去的小助手，用来处理某一类独立任务。
一、什么是 Subagent
我们平时在 Claude Code 里对话的这个 AI，可以理解成主代理。
主代理主要负责：
- 理解用户意图。
- 制定执行策略。
- 分配任务。
- 监督子代理进度。
- 汇总最终结果。
Subagent 中文可以叫子代理。
你可以把它理解成主代理派出去的小助手。这个小助手会按照提前设定好的职责或规则，完成某一部分任务。
比如一个项目里可能会拆出很多小任务：
| 任务类型 | 适合的子代理 |
|---|---|
| 查文档 | 文档调研子代理 |
| 跑测试 | 测试验证子代理 |
| 审核代码 | 代码审查子代理 |
| 设计界面 | UI 设计子代理 |
子代理完成任务后，会把结果返回给主代理，再由主代理统一整理给我们。
二、Subagent 的优势
1. 节省主对话上下文
子代理有自己独立的上下文。
它在执行任务时产生的过程信息，不会全部挤进主对话里。
主代理最后只接收子代理整理好的结果。
这可以减少主对话的上下文占用。
2. 结果更稳定
子代理可以提前设置固定职责和输出规则。
比如创建一个专门整理资料的子代理，并规定：
- 先提炼重点。
- 再整理操作步骤。
- 最后列出注意事项。
以后再让它整理资料时，它就会按照这套固定格式执行。
3. 可以并行处理
有些任务彼此之间没有依赖关系。
比如同时下载三个不同网站的文档，谁先完成都不影响其他任务。
这种任务就可以交给多个子代理同时执行，从而提升效率。
三、Subagent、MCP 和 Skills 的关系
Subagent 对 MCP 和 Skills 的继承方式不一样。
| 能力 | 子代理是否自动继承 | 说明 |
|---|---|---|
| MCP | 通常会继承 | MCP 更像工具权限，当前会话能用的工具，子代理通常也能用 |
| Skills | 不会自动继承 | Skill 不会自动继承主会话里已经加载的内容 |
如果希望某个子代理具备特定技能，需要在定义它时显式写清楚。
比如：
text
这个 subagent 可以使用 weekly-report 和 clean-csv。这样子代理启动时，相关 Skill 才会预先加载到它自己的上下文里。
四、使用 /agents 查看子代理
在 Claude Code 中输入：
text
/agents这个命令可以进入子代理管理界面。
常见界面包括：
| 界面 | 作用 |
|---|---|
| Running | 查看正在运行中的子代理 |
| Library | 查看可用的子代理列表 |
如果当前没有正在运行的子代理，Running 页面会是空的。
切换到 Library 后，可以看到两类子代理：
| 类型 | 说明 |
|---|---|
| 自己创建的子代理 | 项目级或用户级自定义子代理 |
| Claude Code 内置子代理 | 系统自带，会在合适场景下自动调用 |
内置子代理示例
| 子代理 | 适合场景 |
|---|---|
| Explore | 搜索、阅读、分析代码 |
| Plan | 制定计划、前期调研 |
| general-purpose | 通用任务 |
| claude-code-guide | Claude Code 自身功能问答 |
| statusline-setup | 配置状态栏 |
子代理后面如果显示 inherit，表示继承主会话的模型。
也就是说，主代理用什么模型，子代理就用什么模型。
五、示例：并行下载三个网站文档
这里用一个实际任务演示子代理的效果。
示例提示词：
text
我希望你帮我将这三个网站的文档下载到本地，分别存放在不同的文件夹下，优先下载中文版，没有的话下载英文版：
https://code.claude.com/docs/zh-CN/overview
https://docs.warp.dev
https://developers.openai.com/codexClaude Code 会先分析这些网站。
如果网站提供了 llms.txt，Claude Code 可能会优先读取它。
llms.txt 可以简单理解成专门给 AI 看的文档索引，里面通常会整理文档站点的重要页面和结构。
制定计划后，可以继续补充要求：
text
方案没有问题，你需要启用 3 个 subagent 同时下载文档。这时 Claude Code 会启动多个子代理，让它们分别处理不同网站。
主代理会进入等待状态，等子代理完成后再统一汇总结果。
六、管理正在运行的子代理
当多个子代理在后台运行时，状态栏下方会显示 agents 提示。
可以按键盘下箭头定位到这个提示，再按回车展开后台任务面板。
常见操作如下：
| 操作 | 作用 |
|---|---|
| 上下键 | 切换当前选中的子代理 |
| 回车 | 展开子代理详情 |
x | 停止当前选中的子代理 |
Esc | 退出详情或面板 |
在子代理详情里，可以看到：
- 已运行时间。
- Token 消耗。
- 调用过哪些工具。
- 当前执行到哪一步。
- 主代理派发给它的任务提示词。
如果想停止所有正在运行的子代理，可以使用界面提示的快捷键。
当前操作可以记成：
text
Ctrl + X，Ctrl + K，再重复一次 Ctrl + X，Ctrl + K也就是连续执行两遍停止全部子代理的组合键。
七、创建自定义子代理
内置子代理可以处理很多基础场景。
但如果你希望某类任务后续反复使用，建议创建一个固定子代理。
这里以创建 UI 设计子代理为例。
1. 安装 frontend-design Skill
如果希望 UI 设计子代理使用指定 Skill，需要先安装对应 Skill。
安装命令：
bash
npx skills add https://github.com/anthropics/skills --skill frontend-design提醒
Skill 不会自动继承主会话里已经加载的内容。
如果希望某个子代理使用 frontend-design，需要在创建或配置子代理时明确写进去。
2. 创建新子代理
在 Claude Code 中输入：
text
/agents进入子代理列表后，选择：
text
Create new agent创建范围通常有两种：
| 范围 | 适合场景 |
|---|---|
| Project Scope | 当前项目使用，可以和团队共享 |
| User Scope | 当前用户所有项目都可以使用 |
创建方式可以选择自动生成。
对大多数同学来说，直接让 Claude Code 自动帮你生成即可。
3. 示例描述
创建时，可以这样描述这个子代理：
text
帮我创建一个专门负责 UI 设计的 subagent。
它擅长页面结构设计、视觉层级、配色、排版、按钮和卡片样式优化。
优先保证界面简洁、美观、易读，并兼顾桌面端和移动端体验。
默认先输出设计方案和修改建议，再进行实现。
可以调用 frontend-design skill。4. 设置工具权限
创建过程中，Claude Code 会让你选择这个子代理可以调用哪些工具。
工具权限要根据任务决定。
比如：
| 子代理类型 | 建议权限 |
|---|---|
| 查询文档 | 网络查询、读取文件、写入文档 |
| 代码审查 | 读取文件、运行检查命令 |
| UI 设计 | 读取文件、编辑文件、运行预览或构建命令 |
如果不希望它直接修改文件，可以取消编辑相关权限。
5. 设置模型和颜色
接下来可以设置子代理默认模型和显示颜色。
| 配置 | 说明 |
|---|---|
| 模型 | 可以选择 Sonnet、Opus 或继承主会话模型 |
| 颜色 | 用来在运行时区分不同子代理 |
UI 设计这类任务，可以先选择 Sonnet。
6. 设置记忆范围
Memory 可以理解成子代理自己的长期记忆。
它不是当前对话里的临时上下文，而是会保存到固定目录中的经验。
常见记忆范围如下：
| 范围 | 说明 |
|---|---|
| Project Scope | 保存在当前项目目录中，适合团队共享 |
| User Scope | 保存在用户级目录中，对所有项目生效 |
| Local Scope | 保存在当前项目本地，适合个人使用，不共享给团队 |
| None | 不启用长期记忆 |
如果只是个人使用，而且不会上传到 GitHub，Project Scope 和 Local Scope 的差别不大。
如果团队成员会从同一个项目仓库获取代码，Project Scope 中的规则和记忆就可以跟着项目一起同步。
7. 查看子代理文件
如果创建的是项目级子代理，它通常会保存在：
text
.claude/agents/里面会有一个 Markdown 文件。
打开后可以看到它的基本结构和 Skill 有点像：
| 部分 | 说明 |
|---|---|
name | 子代理名称 |
description | 子代理说明，以及什么时候应该使用它 |
| 正文 | 子代理的系统提示词和行为规范 |
如果后续发现它不符合预期，可以继续让 Claude Code 帮你修改这个文件。
八、测试自定义子代理
创建完成后，建议重启 Claude Code，确保配置已经加载。
然后可以用下面的提示词测试：
text
请使用 ui-design-specialist 这个 agent，帮我设计三款不同风格的网站登录页面，并让多个子代理并行完成。运行时可以展开后台任务面板查看子代理详情。
如果配置了显示颜色，也可以更容易区分这个子代理。
九、使用建议
Subagents 很适合处理可以独立拆开的任务。
适合拆分的情况：
- 多个任务之间没有强依赖关系。
- 每个任务都能用清晰提示词单独说明。
- 子代理只需要返回结果，不需要和其他子代理反复协商。
不适合拆分的情况：
- 任务之间依赖很强。
- 每一步都需要共享完整背景。
- 子代理之间需要频繁协调。
- 主代理需要不断解释同一批上下文。
可以记住一句话：
text
只有当上下文可以被真正隔离时，拆分才是有效的。十、参考资源
可以参考下面这个子代理模板合集。
Awesome Claude Code Subagents