EP01. "Subagents 完整教程：什么时候该委派，什么时候不该"

• Overview 系列 EP02 提过 subagent 能把一块独立工作丢出去跑、不会弄乱主对话上下文——官方这门 Introduction to Subagents 课（4 节课，45 分钟）把这件事讲透：怎么建一个自定义 subagent、怎么写出真正好用的 subagent、什么任务该委派、什么任务千万别委派
• 官方自己测试发现，有一种 subagent 用法在所有配置里「表现最差」——用错场景，subagent 不但没帮上忙，反而制造额外麻烦（细节见下面「什么时候不该用」）
• 前置知识：用过 Claude Code 基本操作，知道主对话的上下文窗口是什么

重点内容

Subagent 是什么，为什么需要它

Subagent 是专门的助手，Claude Code 能把任务委派给它——各自在独立的对话上下文窗口里运行，独立完成工作，只把摘要传回主线程。

为什么重要：主对话的上下文空间有限——「每一次工具调用、每一次读文件、每一条搜索结果」都会被存进主对话，占用有限的空间。

Subagent 收到两个输入：一份自定义的 system prompt（定义这个 subagent 的角色）+ 来自父 agent 的任务描述。做完之后，subagent 的对话记录直接丢弃，主上下文保持干净——代价是你看不到它决策过程的细节。

例子：在不熟悉的代码库里找「哪个 service 处理退款」，subagent 可以疯狂搜索、读一堆文件，主对话最后只收到一个聚焦的答案，不会被沿途翻过的文件塞满。

内建可用的 subagent：General purpose（多步骤任务）、Explore（快速搜索/代码导航）、Plan（先研究分析，再给建议）。

自定义 subagent：自己写 system prompt + 配置工具权限，做专门用途。

怎么建一个自定义 Subagent

用 /agents 指令：先选范围（project 级或 user 级），再选两种建法之一——让 Claude 根据描述自动生成配置，或自己手写（官方推荐用 AI 辅助生成）。

工具怎么配：按这个 subagent 的实际功能配，可选类别有 Read-only 工具、Edit 工具、执行类工具、MCP 工具、其他工具。📌 例如 code reviewer 大概率不需要 Edit 工具——它该读和分析代码，不该动手改。

模型和颜色怎么选：模型有 Haiku（快、轻量）、Sonnet（平衡）、Opus（复杂分析）、Inherit（跟主对话一致）四种；另外还能选一个 UI 颜色方便辨识。

配置文件：markdown + YAML frontmatter，通常放在 .claude/agents/你的agent名.md：

---
name: code-quality-reviewer
description: Use this agent when you need to review recently written or modified code for quality, security, and best practice compliance.
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch
model: sonnet
color: purple
---

You are an expert code reviewer specializing in quality assurance, security best practices, and adherence to project standards...

字段说明：

frontmatter 下面的 markdown 正文就是 system prompt，用来指导这个 subagent 的行为、分析重点、输出结构。

测试：改一段代码，请求跑一次 subagent review；如果自动委派没触发，把 description 写得更具体、补上范例，重新校准。

怎么设计出真正好用的 Subagent（四个关键特征）

config 里的 name/description 会被写进主 agent 的 system prompt 里，决定这个 subagent 什么时候会被启动——description 身兼两职：控制「什么时候触发」，也塑造「主 agent 会给它下达什么样的指令」。description 写得太笼统，主 agent 派下去的指令也会很笼统（比如只是「看看目前的改动」）；description 写得细，主 agent 会主动带上更具体的参数（比如列出具体要 review 哪些文件、要求附来源）。

① 定义输出格式——官方说这是「对 subagent 最重要的一项改进」，做到两件事：有明确的完成节点（所有区块都填完就算做完）、防止跑过头（subagent 能靠这个判断自己做完了没）。code review 的范例结构：Summary / Critical Issues / Major Issues / Minor Issues / Recommendations / Approval Status。

② 主动报告遇到的障碍——subagent 应该把过程中发现的 workaround、复杂情况写进输出，比如环境设置问题、需要特殊 flag 的指令、依赖问题、配置怪癖。输出模板里明确留一个「Obstacles Encountered」区块，主线程才不用重新摸索一遍已经解决过的问题。

③ 限制工具访问——不同类型的 subagent 配不同工具集：

这样能防止意外的副作用，也让每个 subagent 的角色更清楚。

④ 描述具体、指向明确——四个特征合起来，subagent 才能变成一个「专注、可预期的工作者」，稳定完成任务。

什么时候该用 Subagent，什么时候不该

判断的核心问题只有一个：「中间过程对主线程重要吗？」 如果探索步骤跟主线程的执行路径无关，委派效果好；如果每一步都依赖前一步发现的东西，就该留在主线程里做。

该委派的三种场景：

• Research 类任务——经典应用。比如查一个不熟悉代码库里的身份验证逻辑，主线程只需要知道 JWT 验证发生在哪一处，不需要知道搜索过程翻了哪些文件；subagent 可以读几十个文件、追函数调用链、探索不同代码路径，最后给主线程一份干净的摘要
• Code Review——分开做效果更好。Claude 审查自己刚写的代码很难保持客观；独立的 reviewer subagent 单独跑 git diff、检查改动文件、套用审查标准，不带着「这段代码是我刚写的」这层包袱，还能透过专门的 system prompt 让「整个团队的审查标准保持一致」
• 需要专门 system prompt 的任务——Claude 默认的回答风格偏简洁、偏技术，不是每个任务都合适。例子：Copywriting subagent（专门讲语气和受众的指令，取代默认的技术向假设）、Styling subagent（自动加载设计系统文件，生成 CSS 前先把颜色变量、组件模式准备好）

不该委派的三种反模式：

• 「专家人设」没有实际价值——像「你是一个 Python 专家」这种 prompt，Claude 本来就有这些知识，不会因为这句话变强，没有真正的能力提升
• 有依赖关系的多步骤 pipeline——每一步都依赖前一步发现的信息时，「信息会在 agent 之间的交接过程中遗失」，在需要持续累积线索的 debug 流程里问题尤其明显
• Test Runner 类 subagent——会把诊断信息藏起来。测试失败时只拿到一份笼统摘要，逼着你另外写「debug 脚本」去拿本来直接输出就有的细节；官方测试里，这种用法在所有配置里表现最差

决策框架：

学完你会

• ✅ 讲得清 subagent 为什么能保护主对话的上下文空间，以及它「独立跑、只回传摘要」的代价是什么
• ✅ 会用 /agents 建一个自定义 subagent，配对工具权限、模型、description
• ✅ 知道好用的 subagent 要具备哪四个特征：具体的 description、固定输出格式、主动报告障碍、限制工具访问
• ✅ 拿到一个新任务，能用「中间过程重不重要」这一个问题，快速判断该不该委派给 subagent
• ✅ 认得出三种不该用 subagent 的反模式，尤其是官方测试里表现最差的 test runner 用法

常见错误

• ❌ 什么任务都想着丢给 subagent 处理——先问自己「中间过程对主线程重要吗」，每一步都依赖上一步发现的信息时，委派反而会在交接过程中把关键线索弄丢
• ❌ 给 subagent 一个「你是 XX 专家」式的 system prompt 就期待它变强——Claude 本来就有这些知识，这种描述不会带来真正的能力提升，纯粹浪费一次委派的开销
• ❌ 把跑测试这件事丢给 subagent——测试失败只会拿到一份笼统摘要，逼着自己另外写 debug 脚本去挖细节，官方测试里这是表现最差的用法
• ❌ 自定义 subagent 不写清楚输出格式——没有固定的输出模板，subagent 很难判断自己「做完了没」，容易跑过头或漏项
• ❌ 只该读代码的 code reviewer 类 subagent 配了 Edit/Write 权限——权限和角色对不上，容易产生不该有的副作用
• 💡 想让 Claude 自动派工作给你的 subagent，在 description 里加「proactively」这个词，再补几个具体的对话范例，比单纯写清楚「这个 subagent 是做什么的」更有效

Sources

官方文档：

1. Introduction to Subagents（课程总览）— https://academy.claude.com/courses/introduction-to-subagents
2. What are subagents? — https://academy.claude.com/courses/introduction-to-subagents/what-are-subagents
3. Creating a subagent — https://academy.claude.com/courses/introduction-to-subagents/creating-a-subagent
4. Designing effective subagents — https://academy.claude.com/courses/introduction-to-subagents/designing-effective-subagents
5. Using subagents effectively — https://academy.claude.com/courses/introduction-to-subagents/using-subagents-effectively