我把 Claude 的上下文炸过几次之后，才搞懂 Subagent 是干嘛的

事情大概是这样的。

让 Claude Code 改一个 bug，它兴致勃勃地开始读代码——src/auth 翻一遍、src/api 翻一遍、src/db 再翻一遍，连测试文件都不放过。等它准备动手的时候，上下文窗口已经塞满了。然后它开始"忘事"——前面读过的关键逻辑记不清了，改出来的代码前后逻辑都对不上。

后来这种事遇到几次，我才反应过来一件事：不是所有任务都该让主对话亲力亲为。

Subagent 就是干这个的。

它到底是什么

最简单的理解：Subagent 是被派出去执行具体任务的专员，跑在自己独立的上下文窗口里。

打个比方。你的主对话是项目经理，得管全局、做决策；Subagent 是被派去做具体活的工程师——独立工作，最后只把结论汇报回来。它读过的 50 个文件、跑过的几千行日志，全留在它自己脑子里，不污染你的主对话。

这个设计带来的好处是双向的。

一是主对话的上下文不会被噪音填满。Subagent 在自己那边把 50 个文件啃完，主对话只看到一句"这个模块用的是 JWT 认证，校验逻辑在 middleware/auth.ts 里"。

二是可以并行。同时派三个 Subagent 分别去研究认证、数据库、API，三件事齐头并进，互不打扰。

开箱就有三个

不需要你做任何事，Claude Code 自带这三个：

Explore——只读模式的搜索专家，默认跑在 Haiku 上（便宜、快）。你说"帮我看下这个项目里 X 是怎么实现的"，Claude 会自动把这种"读大量文件但不写"的任务委托给它。

Plan——在动手之前先做架构方案，只规划不动手。审过再执行。

General-purpose——没有专门定位、什么都能干的兜底款。

很多人没意识到：你跟 Claude 说"研究一下"或"理解一下"的时候，它经常已经在用 Explore 了，只是没明说。

写一个自己的 Subagent

Subagent 就是一个带 YAML 头部的 Markdown 文件，没有任何魔法。

最快的姿势：在 Claude Code 里敲 /agents，按引导走完就行。也可以手写文件，丢到 .claude/agents/（项目级）或 ~/.claude/agents/（全局）。

举个具体例子，一个代码审查 Subagent：

---
name: code-reviewer
description: 代码审查专家。写完或修改代码后立即主动使用。
tools: Read, Grep, Glob, Bash
model: inherit
---

你是一位资深代码审查员。被调用时：

1. 跑 git diff 看最近改动
2. 只聚焦修改过的文件
3. 按优先级反馈：严重问题 → 警告 → 建议

审查清单：
- 命名是否清晰
- 是否有重复
- 错误处理是否完善
- 是否暴露了密钥
- 测试是否够

几个字段值得多说两句。

description 是整个文件里最关键的一行。 Claude 靠这段话决定什么时候自动委托。如果你只写"一个代码助手"，它不知道什么时候该用；写成"写完或修改代码后立即主动使用"——触发条件 + "主动"两个字——Claude 才会真的主动调。这一行写得好不好，直接决定这个 Subagent 是不是摆设。

tools 是权限闸门。 只读任务就只给 Read, Grep, Glob，不给 Edit, Write。这不只是为了简洁，更是一道安全围栏，防止 Subagent 越权改东西。

model 可以分级用。 探索这种廉价任务用 Haiku，深度审查用 Sonnet 或 Opus，按需付费，不浪费贵模型。

怎么让它干活

三种调用方式，各有各的场景。

直接说人话：用 code-reviewer 看一下 auth 模块。自然，但不保险，Claude 可能选别的 Subagent。

@code-reviewer 看下最近的改动。@ 提到的，一定会用，不会跑偏。

claude --agent code-reviewer。整个会话绑死在这个 Subagent 上，适合你只想干一件事的场景。

三个最常用的场景

跑测试、处理日志这种"高产出"操作。 npm test 一跑几千行，塞进主对话直接窒息。交给 Subagent：「跑完整测试套件，只报告失败的测试和错误」——它处理掉所有噪音，只把信号发给你。

并行研究。 "用三个独立的 subagent 同时研究认证、数据库、API 模块"——比顺序调研明显快，而且三个模块的细节不会互相污染。

链式工作流。 "用 code-reviewer 找性能问题，然后用 optimizer 修复它们"。前一个的输出当作后一个的输入，整条链你不用手动搬运结论。

Subagent 和 Skill 别再搞混了

这俩概念是 Claude Code 里最容易混的。一张表说清楚：

	Skill	Subagent
本质	可复用的指令包	独立上下文的工作者
跑在哪	主对话上下文内	自己独立的上下文窗口
什么时候用	想在主对话里复用一套流程	想隔离上下文、并行、限权

记忆口诀：要隔离用 Subagent，要复用用 Skill。

两个最容易踩的坑

Subagent 不能再派 Subagent。 它没法递归。如果你的流程需要嵌套委托，要么把流程写成 Skill，要么从主对话里手动串多个 Subagent。

description 写得太抽象等于没写。 这是新手最常见的错误。"general purpose helper" 这种描述，Claude 永远不会主动调它——它根本不知道你想让它什么时候出场。越具体越好，像"PR 提交前自动审查代码，主动使用"这样直接给出触发场景。

一个进阶用法：给 Subagent 开记忆

YAML 头部加一行：

memory:
  scope: project

它会把每次发现的项目模式、踩过的 bug、架构约定记下来。下次调用时，它已经"认识"你的项目了。

再在正文里加一句：

完成任务后，把你学到的东西保存到记忆里。

跑一段时间，这个 Subagent 会变成项目里的"老员工"——审查质量越来越高，因为它知道哪些地方曾经出过事。

最后

回头看开头那个上下文炸了的故事——后来再遇到这种情况，"读代码"这一步直接丢给 Explore，主对话只接收一句结论："问题在 middleware/auth.ts，token 解析时没处理空 header。" 该改哪改哪。

Subagent 的核心价值就三件事：保护主对话的上下文、实现并行、限制权限。

别一上来就想得太复杂。从一个最简单的代码审查 Subagent 开始，让它在你每次提交前自动跑一次。用顺手了，你自然会冒出下一个念头——"这件事好像也可以扔给一个专员去做"。