Subagents 深入

主代理像一位项目经理：他什么都懂一点，但你不会让他一个人把前后端、测试、文档全干完。他会把大块工作拆给独立上下文的「外聘顾问」——这就是 Subagent（子代理）。子代理在一份干净的上下文里埋头干活，干完只把结论摘要交回来，主代理的笔记本依然整洁。

这一篇讲清楚为什么需要子代理、内置三代理怎么用、自定义子代理怎么写，以及怎么编排它们。

为什么需要子代理：上下文退化

主代理的上下文窗口是 200K token，但不是用满才出问题。经验上，上下文用到 45% 左右，模型对早期信息的注意力就开始衰退；越往后塞，早期的指令和发现越容易被「遗忘」或忽略。这就是上下文退化（context degradation）。

退化不是崩溃，而是悄悄变笨：忘了你三小时前定的命名规范、漏掉早期读过的某个文件、重复跑已经做过的探索。它像一个塞了太多便签的同事，翻得到处都是，却找不到最关键那一张。

子代理的解法很直接：给重活一份干净的上下文。子代理从零开始读它需要的东西，干完把摘要交还主代理。主代理的上下文只增加一段总结，而不是几千 token 的过程细节。

内置三代理：开箱即用

Claude Code 自带三个子代理，覆盖最常见的「探索—规划—执行」链条。

Explore（探索代理）

只读，专门用来摸清陌生代码库。它有三档力度：

档位	适用	行为
快速（fast）	找一个函数/变量在哪	直接 Grep + Glob，定位即返
中等（medium）	理解一个模块怎么工作	读相关文件，总结调用链
非常彻底（very thorough）	整体摸排陌生项目	多轮搜索 + 交叉验证，给出全局地图

Explore 永远不会改你的代码——它没有 Edit 权限。它只读、只看、只总结，把「这里有什么」讲清楚。

Plan（规划代理）

研究型代理，在 Plan 模式下收集信息、形成方案。它不急着写代码，而是先把问题拆解、列出选项、给出推荐路线。适合「我想重构这个模块，但还没想好怎么动」这类需要先想清楚的场景。

General-purpose（通用代理）

复杂多步骤任务的全能选手。能读能写能跑命令，适合「按这个方案把改动落地」这类需要实际动手的活。它有自己的上下文，可以放心跑一长串步骤而不污染主会话。

自定义子代理：写一个你自己的顾问

当内置三代理不够用时，你可以定义专属子代理。位置是 ~/.claude/agents/（用户级）或 .claude/agents/（项目级），每个代理一个 .md 文件。

---
name: security-reviewer
description: 安全审查子代理。当用户请求安全审查、检查依赖漏洞、或排查注入风险时调用。只读不改。
tools: Read, Grep, Glob
---

# 安全审查员

## 职责
逐文件检查以下风险：
- SQL 注入（拼接式查询）
- 命令注入（未转义的 shell 参数）
- 硬编码密钥与 token
- 不安全的反序列化

## 输出格式
对每个发现：
1. 文件路径 + 行号
2. 风险等级（高/中/低）
3. 一句话说明
4. 建议修法

只报告问题，不要修改代码。

frontmatter 字段

字段	作用
`name`	代理名，主代理用 `Task` 工具委托时引用
`description`	主代理靠它判断何时调用此子代理
`tools`	控制工具权限，逗号分隔

tools 字段：最小权限原则

tools 是子代理的安全带。给多少工具，它就只能做多少事：

# 只读审查员：只能看
tools: Read, Grep, Glob

# 需要改代码的执行代理：加上编辑和命令
tools: Read, Grep, Glob, Edit, Bash

# 只探索文档的代理：连 Edit 都不给
tools: Read, Glob

经验法则：能不给就不给。审查员不需要 Edit，探索者不需要 Bash。万一子代理跑偏，权限小意味着破坏也小。

委托-返回模式

子代理的核心工作模式是委托-返回：

主代理 ──委托任务──▶ 子代理（独立上下文）
                        │
                        │ 读文件、跑命令、思考
                        │
                   ◀──返回摘要──
主代理整合摘要，继续推进

关键在摘要二字：子代理不会把自己读过的几千 token 原样扔回来。它消化、提炼，只把结论交给主代理。主代理的上下文因此只增长几百 token，而不是几千。

这也是为什么子代理不能生成子代理——一旦允许嵌套，就可能无限递归，每个子代理又开子代理，上下文和成本都会失控。Claude Code 限制：子代理无法再调用 Task 工具委托下一层。

链式调用：主代理当指挥家

多个子代理可以串行编排，主代理充当指挥家：

主代理
  │
  ├─① 委托 Explore：摸清这个模块的结构
  │     └─ 返回：模块地图 + 关键文件清单
  │
  ├─② 委托 Plan：基于地图给出重构方案
  │     └─ 返回：三步方案 + 风险点
  │
  ├─③ 委托 General-purpose：按方案落地
  │     └─ 返回：改了哪些文件、测试结果
  │
  └─④ 委托 security-reviewer：审查改动
        └─ 返回：无安全风险 / 发现 2 处问题

每一步只把摘要传给下一步，主代理的上下文始终清爽。这就是 9 步循环里「探索→规划→执行→审查」的落地方式。

并行编排：代码审查流水线

链式是串行，但有些子代理可以并行。经典场景是代码审查流水线——风格、安全、测试三类检查互不依赖，同时开三个子代理：

              主代理（分发改动列表）
              ┌──────┼──────┐
              ▼      ▼      ▼
           风格审查  安全审查  测试审查
          (Read)   (Read)  (Read+Bash)
              │      │      │
              └──────┼──────┘
                     ▼
              主代理汇总三份摘要

三个子代理各跑各的，最后主代理把三份摘要合并成一份完整审查报告。比串行快，且每份审查在独立上下文里更专注。

实用模式清单

场景	怎么用子代理
大型重构	Explore 摸结构 → Plan 出方案 → General-purpose 落地 → security-reviewer 把关
代码审查流水线	风格 / 安全 / 测试三子代理并行，主代理汇总
研究任务	Explore 彻底档摸排，把「全局地图」摘要交回
陌生代码接手	Explore 中等档先跑一遍，省得主代理自己读一堆文件
批量改造	General-purpose 在子上下文里跑完，避免污染主会话

通信模式：一张文字图

把主代理与子代理的往来画出来：

┌─────────────────────────────────────────────┐
│  主代理（持久上下文）                        │
│                                             │
│  用户：「帮我重构 auth 模块」               │
│       │                                     │
│       ▼ Task(delegates to Explore)         │
│  ┌─────────┐  摘要返回  ┌─────────────┐    │
│  │ Explore │ ─────────▶ │ 主代理记录   │    │
│  └─────────┘            └──────┬──────┘    │
│                                │           │
│                                ▼           │
│                       Task(delegates to     │
│                       General-purpose)      │
│  ┌────────────────┐  摘要返回  ┌────────┐  │
│  │ General-purpose│ ─────────▶ │ 整合    │  │
│  └────────────────┘            └────────┘  │
│                                             │
│  主代理向用户汇报最终结果                   │
└─────────────────────────────────────────────┘

要点：箭头流过去的永远是摘要，不是原始上下文。子代理的内部上下文（它读了什么、想了什么）不回传，主代理只拿到结论。

最佳实践速记

摘要优先：子代理的返回值要是结论，不是过程堆砌。在 description 里明确「输出格式」。
最小权限：tools 给得越少越安全，只读代理就别给 Edit。
别让主代理亲自探索：摸代码这种「读一堆、留很少」的活，交给 Explore 最划算。
审查并行、执行串行：检查类可并行加速，改造类串行保证顺序依赖。
子代理不能再生子代理：编排权留给主代理，避免无限嵌套。

子代理的本质是用独立上下文换主会话的清爽。下一篇看 Hooks 深入与实战，了解怎么在工具调用的生命周期里插进「硬规则」。🚀