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

> Subagent 是 Claude Code 里被严重低估的能力——独立上下文、可并行、能限权。聊聊它和 Skill 的区别、3 个开箱内置款,以及怎么写一个属于自己的代码审查 Subagent。

- 原文链接: https://laojin.blog/blog/20260520_claude_subagent_intro
- 作者: 老金
- 发布日期: 2026-05-20
- 标签: Claude Code, Subagent, AI 编程, 工程实践

---

![我把 Claude 的上下文炸过几次之后，才搞懂 Subagent 是干嘛的](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260520/00_cover.png)

事情大概是这样的。

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

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

Subagent 就是干这个的。

## 它到底是什么

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

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

![主对话派任务，Subagent 在自己的上下文里干活，只汇报结论](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260520/01_main_vs_subagent.png)

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

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

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

## 开箱就有三个

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

![Claude Code 内置三个 Subagent：Explore / Plan / General-purpose](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260520/02_three_builtin.png)

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

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

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

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

## 写一个自己的 Subagent

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

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

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

````markdown
---
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 上，适合你只想干一件事的场景。

## 三个最常用的场景

![Subagent 最擅长的三种模式：隔离噪音、并行、链式工作流](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260520/03_three_patterns.png)

**跑测试、处理日志这种"高产出"操作。** `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 头部加一行：

```yaml
memory:
  scope: project
```

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

再在正文里加一句：

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

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

## 最后

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

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

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