D10 · Subagents

一句话版本:凡是「过程输出很吵、结论只要一段」的活,都该丢给 subagent 去做——它在独立上下文里消化搜索结果、测试日志、文件内容,主会话只为最终摘要付上下文成本。

为什么这天学这个

D2 讲过:上下文窗口是最稀缺的资源,塞满无关内容,模型质量就往下掉。Subagent 是 Claude Code 对此的内置解法——把「探索」和「实现」分开,探索的噪音留在分身的窗口里。本站观点其实你早用过它:D5 的 plan mode 里,Claude 做代码库调研时委派的就是内置 Plan subagent。

往后看,这课是并行工作流的地基:D11 的 worktree 给每个 subagent 一份隔离的代码副本,D12 的 agent teams 把「单会话内委派」升级成「多会话协同」。分不清「多开几个会话」和「一个会话派多个 subagent」,学完本课看对比 Tip:多会话 vs 多 agent 怎么选。

概念讲清楚

官方Subagent 是处理特定任务的专门 AI 助手:运行在自己的上下文窗口里,有自己的系统提示、工具集和权限。任务匹配某个 subagent 的 description 时,Claude 把活委派出去,subagent 独立完成后交回结果。它解决的核心问题:侧线任务会用搜索结果、日志、文件内容淹没主对话,而这些内容你之后根本不会再引用。

一个类比:借调的同事

本站观点把 subagent 想成借调来的同事:你写一段任务说明交给他(委派消息),他自己翻档案、跑实验、记满一本草稿(他的上下文),最后只交回一页备忘录。你的笔记本只多了这一页,他的草稿本你从头到尾不用见。多借几个人,各自埋头干活,互相看不见彼此的草稿,汇总是你(主会话)的事。

内置 subagent

官方Claude Code 自带几个内置 subagent,Claude 会在合适时机自动委派:

官方两个特殊点:Explore 和 Plan 为了快和省,不加载 CLAUDE.md 和父会话的 git 状态;其余内置与自定义 subagent 都加载。某条规则(如「忽略 vendor/ 目录」)必须传达给它们时,写进委派 prompt 里。另有几个自动触发的辅助 agent(claude、statusline-setup、claude-code-guide),一般不用直接管。

自定义:.claude/agents/*.md

官方自定义 subagent 就是一个带 YAML frontmatter 的 Markdown 文件:frontmatter 是配置,正文是它的系统提示。subagent 收到的只有这份系统提示加基本环境信息,不是完整的 Claude Code 系统提示。最小可用的例子:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

官方只有 name 和 description 是必填,description 决定 Claude 什么时候委派给它——写清楚,想让它被主动使用可以加「use proactively」。常用可选字段:

官方文件放哪决定谁能用,同名时高优先级生效,从高到低:管理策略(managed settings)> --agents CLI 参数(仅当次会话)> 项目 .claude/agents/(建议进版本库,团队共用)> 用户 ~/.claude/agents/(自己所有项目可用)> 插件的 agents/ 目录。自 v2.1.198 起 /agents 不再打开创建向导,直接让 Claude 写文件或自己编辑即可;改动几秒内自动生效,唯独「某个 scope 的第一个 agent 文件」需重启会话才被发现。

什么时候用,什么时候别用

官方用 subagent 的三个信号:任务会产生主上下文用不上的大量输出(跑测试、抓文档、扫日志);想强制收窄工具或权限(只读审查员);工作自成一体、一份摘要就能交差。反之留在主会话:需要频繁来回迭代;多阶段共享大量上下文;快速小改动;在意延迟——subagent 从零启动,要花时间重新收集上下文。

官方两个最常用的模式:隔离高噪音操作(「用 subagent 跑测试,只汇报失败用例」)和并行探索(互不依赖的调研方向各派一个,同时跑,Claude 汇总)。官方同时提醒:很多个 subagent 各自交回冗长报告,同样会吃掉可观的主会话上下文——需要持续大规模并行时,该考虑 D12 的 agent teams。

边界:不共享上下文,只回一份报告

官方每个 subagent 都从全新的隔离上下文启动:看不到你的对话历史、已调用的 skill、Claude 已读过的文件。它拿到的是——自己的系统提示、Claude 写的委派消息、CLAUDE.md 全层级(Explore/Plan 除外)、父会话开始时的 git 状态快照、预载的 skill。干完活,回到主会话的只有一份最终报告,中间过程全留在它自己的 transcript 里。

官方由此推出几条边界:并行的 subagent 之间不共享上下文、不互相通信,B 想用 A 的发现,只能由主会话把 A 报告里的相关内容写进给 B 的委派消息;subagent 完成后可让 Claude 继续同一实例(保留全部历史「resume」),但 Explore 和 Plan 一次性、不能续;subagent 也能再派 subagent,默认主会话之下最多嵌套三层,单会话总量上限 200、同时运行上限 20(均可用环境变量调整)。反向特例是 fork(/subtask 命令):继承主会话完整对话历史再去干侧线任务,牺牲输入隔离换「不用重新交代背景」,输出仍只回一份结果。

后台运行

官方自 v2.1.198 起,subagent 默认在后台运行,你可以继续在主会话干别的;只有 Claude 立刻需要结果时才用前台(阻塞式)。后台 subagent 碰到需授权的操作,权限提示浮到主会话里、注明是哪个 subagent 在申请;批准放行,按 Esc 只拒绝这一次调用。你也能主动控制:让 Claude「在后台跑」,对运行中的任务按 Ctrl+B 转后台;/tasks 列出所有后台项,可查看、接管或停止。两个代价:后台 subagent 的内置工具集比前台小(MCP 工具全保留);结果以完成通知的形式在之后的轮次到达——提前问进度,Claude 只会说「还在跑」。

当天能做完的实操

整套约 30 分钟,在任意一个有测试或有一定规模代码的项目里做。

1. 体验隔离。先跑 /context 记下当前用量(D1 学过),再把下面的 prompt 交给 Claude Code。预期:出现一行 subagent 委派记录(agent 名 + 简短任务描述),完整测试输出不进主对话,回来的只有失败摘要;再跑 /context,增量远小于测试输出体量。

用一个 subagent 跑完整测试套件,只把失败的用例和对应错误信息汇报回来,
不要把完整测试输出带回主会话。

2. 创建自定义 subagent。用下面的 prompt 让 Claude 写文件。预期:.claude/agents/code-reviewer.md 出现,frontmatter 含 name、description、tools、model,正文是审查员系统提示。若这是本项目第一次建 .claude/agents/ 目录,重启会话让它被发现。

在 .claude/agents/ 里创建一个 code-reviewer subagent:只读(Read、Grep、Glob),
用 sonnet 模型,职责是审查最近的代码变更,按「必须修 / 建议修 / 可改进」三档
输出问题清单,每条附当前代码和改进写法。description 里写明改完代码后主动使用。

3. 显式调用。说「用 code-reviewer subagent 审查我最近的改动」,或输入 @ 从补全列表里选中它(@-mention 保证这次一定由它执行)。预期:出现 code-reviewer (…) 委派行,几分钟后收到三档问题清单。
4. 并行扇出。交给 Claude:「用三个并行的 subagent 分别调研本项目的认证、数据库、API 模块,各自总结职责与关键文件后汇总」。预期:三个 subagent 同时在后台跑,/tasks 里能看到各自状态,完成后 Claude 给出汇总——正是本课图里的扇出/汇聚。

验收标准

• 能不看笔记说清:subagent 启动时上下文里有什么(自己的系统提示、委派消息、CLAUDE.md、git 快照、预载 skill),结束时回来的是什么(一份报告)。
• 能说出 Explore / Plan / general-purpose 的分工,以及 Explore 和 Plan 的两个特殊点:只读;不加载 CLAUDE.md 与 git 状态。
• 项目里有一个自己写的 .claude/agents/*.md,且成功委派执行过一次。
• 自测题:三个 subagent 并行调研,B 能直接引用 A 的发现吗?怎样才能让 B 用上 A 的结论?(答案:不能,subagent 之间不共享上下文;A 的报告先回主会话,由 Claude 把相关内容写进给 B 的委派消息;需要 worker 间直接通信则是 D12 agent teams 的领域。)