子代理（Subagent）：拆活、并行、隔离上下文的核心手段

你有没有碰到过这种情况：一个复杂需求，先让 Claude Code 帮你调研，再让它写代码，再让它写测试，再让它排查一个无关的 bug——对话越来越长，上下文越堆越满，到后来它开始"忘事"，或者把前面说过的某个路径搞混，或者直接把 token 烧光了。

这不是 Claude Code 不够聪明，是你没拆活。

子代理（Subagent）就是拆活的核心机制。主 Agent 把一块相对独立的工作派给一个全新的子 Agent，子 Agent 在自己干净的上下文里做完，只把结论回传。主会话不会看到中间过程，不会被几百行文件、几轮搜索记录、几段调试输出撑爆。

这篇把子代理讲清楚：它到底是什么、为什么省上下文、怎么实际用、什么活适合派、以及你可能踩的坑。

---

子代理是什么

一句话：主 Agent 生成一条"派活指令"，由工具框架启动一个全新的 Agent 实例，这个新实例（子代理）拿到任务描述，在自己独立的上下文里从头开始工作，完成后只返回结论给主 Agent。

几个关键点：

上下文隔离：子代理启动时上下文是干净的，它不知道主会话里发生过什么（除非主 Agent 在派活时明确带进去）。这是隔离，也是代价——要传的信息得在派活时写清楚。

结论回传，不是过程回传：子代理把中间翻阅的文件、尝试的路径、排查的过程，全部留在自己的上下文里消化掉。主 Agent 只收到一条结论性的回复，比如"这个函数的 bug 根因是 xxx，影响文件是 a.js 和 b.js"。

可以是同一个模型，也可以是不同模型：在 Claude Code 的 Agent 工具框架里，子代理同样是 Claude 模型，但它可以被指定用更小/更快/更便宜的变体来做特定任务（比如 Haiku 做文件搜索，Sonnet 做代码生成）。

不等于"多轮对话"：多轮对话是在同一个上下文里来回，越来越长。子代理是另开一个，做完销毁，主上下文只增加一条结论性的摘要。

---

为什么子代理是省上下文的核心手段

先理解问题在哪：大语言模型的上下文窗口是有上限的（目前主流 100K-200K token）。一次对话里，你问的每个问题、它读的每个文件、它给的每个回复，都会堆在这个窗口里。窗口越满：

• 模型对早期内容的注意力会下降（attention dilution），容易"忘掉"前面说过的约束
• token 消耗线性增长，成本随之膨胀
• 达到上限后对话强制中断，只能新开会话，之前的中间状态全丢

子代理用两个机制解决这个问题：

机制一：隔离

调研类任务是最典型的上下文杀手。让主 Agent 去搜索"竞品 API 文档"，它要开好几个网页、读几千字内容、做比较——这些中间状态全堆在主上下文里，但你其实只想要"竞品 A 的 rate limit 是 X，竞品 B 是 Y"这一条结论。

子代理的做法：主 Agent 派出一个调研子代理，告诉它"去查竞品 A 和 B 的 rate limit"；子代理读文档、比对、整理，最后回传一条两行的结论；主上下文增加两行，不是两千行。

这就是隔离的价值：把"过程"困在子代理里，主会话只保留"结论"。

机制二：并行

某些任务彼此独立，没有先后依赖。比如：

• 同时让三个子代理分别搜索三个不同方向的文档
• 同时让两个子代理分别在两个模块里找同类型的 bug
• 同时让一个子代理写测试、另一个子代理写文档，两边都只依赖同一份已经确定的接口定义

并行意味着总耗时取决于最慢的那个子代理，而不是所有子代理耗时之和。对于 I/O 密集型任务（大量读文件、多次网络请求），并行能带来显著提速。

上下文角度：并行的多个子代理各自有独立上下文，互不干扰，主会话等它们各自完成后收集结论。主会话的上下文增量还是只有几条结论性回复。

---

在 Claude Code 里怎么用子代理

Claude Code 里，子代理通过 Agent 工具派出。你不需要自己写调度代码——当你告诉 Claude Code"帮我做 X"，它内部会判断是否值得开一个子代理；但更精确的做法是你主动说清楚你想要什么。

最直接的方式：直接要求并行执行

在 Claude Code 交互模式里：

> 同时帮我做两件事：1）搜索项目里所有用了 fetch() 的地方，整理成列表；
  2）检查 package.json 里的依赖有没有过期版本，给出报告。这两个可以并行。

Claude Code 收到这条指令，会启动两个子代理分别执行，主会话等待，然后收到两份结论性汇报。

调研类任务——最适合子代理的场景

> 帮我调研一下：项目里目前有没有任何地方用了 eval() 或 new Function()，
  以及 setTimeout 里有没有传字符串参数（这是安全风险）。
  把所有命中的文件和行号列出来就行，中间过程不用给我看。

子代理会翻遍整个代码仓库，完成后返回一张命中清单。主会话没有被几百次文件读取记录撑爆，只多了一份清单。

带上下文派活——主 Agent 需要明确传递背景

子代理上下文干净，不知道主会话里发生了什么。如果任务需要背景，要在派活时显式带进去：

> 我们正在用 Hono 框架，后端入口是 src/index.ts，路由在 src/routes/。
  帮我在这个基础上做一件独立的事：检查 routes/ 下所有路由处理函数，
  看哪些没有做错误边界（没有 try/catch 也没有 .catch()），列出来。

注意这里主动把框架、目录结构说清楚了——子代理需要这些才能定向查找，而不是漫无目的地翻整个项目。

在 CLAUDE.md 里配置子代理行为（进阶）

如果你经常需要特定类型的子代理任务，可以在项目根目录的 CLAUDE.md 里描述项目结构和惯例，子代理启动时会读取这个文件作为初始上下文，减少你每次手动带背景的负担。具体上下文工程方法见 3.1 上下文是一切。

---

什么活适合派子代理

不是所有任务都该开子代理。主要适合这三类：

1. 大量读文件的调研任务

在一个大型仓库里找某类模式（所有的 TODO、所有未处理的 Promise rejection、所有硬编码字符串）——子代理翻文件的过程会消耗大量 token，但结论只有几行，极适合隔离。

2. 彼此独立、没有先后依赖的并行子任务

写三个不同模块的单元测试、搜索三个不相关的文档资源、对三个独立子目录做同类型的代码检查——可以同时派出去，互不阻塞。判断标准：子任务 A 的输出不是子任务 B 的输入。

3. 需要"干净视角"的任务

Code review、安全审计、文档生成——这些任务最好从没有"先入为主"的视角来做。子代理没有主会话里的偏见和中间状态，给出的判断往往更客观。

不适合子代理的任务：

• 需要主会话里大量中间状态的迭代调试（来回改、来回验证，每一步依赖上一步的结果）
• 任务很短、复杂度很低（开子代理本身有启动成本，几行代码的小修改直接在主会话做就够了）
• 任务之间有强依赖链（A 的输出是 B 的输入，B 的输出是 C 的输入）

上下文管理的整体策略，以及什么时候该用 /clear 而不是子代理，见 4.3 上下文工程：管 token、防飘移。

---

故障排查表

症状	原因	解法
子代理回来的结论"答非所问"，没查到正确的地方	派活时没传必要的背景：目录结构、文件命名约定、框架版本	在派活指令里显式写清楚：入口文件是哪个、相关目录在哪、关键术语是什么
多个子代理"并行"了，但结果出来发现顺序不对、互相冲突	任务之间实际上有依赖，不适合并行	先画依赖图：A 的输出是不是 B 的输入？是的话必须串行
子代理任务很简单，但感觉成本比预期高很多	滥用子代理——小任务的启动成本（新上下文初始化、读 CLAUDE.md、模型启动）不比直接做省	规则：任务预计耗时 < 30 秒、文件读取 < 5 个，直接在主会话做，不要开子代理
子代理回来说"文件不存在"或"找不到对应函数"	项目根目录不对，或子代理没有 CLAUDE.md 可以读	确认项目有 CLAUDE.md 且描述了目录结构；派活时手动带上"根目录是 xxx，主要代码在 src/"
主会话等了很久，子代理一直没回	子代理遇到了需要用户确认的操作（比如写文件权限），但子代理模式下无法弹出交互	派活时明确说"只读不写，只查不改"；需要写操作的任务不要用纯子代理模式

---

判断：什么时候该用子代理

一个快速判断流程：

这个任务是否独立，不依赖主会话的中间状态？
  ├── 否 → 直接在主会话做
  └── 是 → 任务够重（读文件多 / 要搜索 / 要调研 / 要生成大量内容）？
              ├── 否（轻量，几行改动）→ 直接在主会话做
              └── 是 → 有没有多个这样的独立重任务？
                          ├── 是 → 并行子代理（性价比最高）
                          └── 否（只有一个）→ 单个子代理（隔离上下文用）

记住两条原则：隔离换来的是主会话的干净；并行换来的是时间上的节省。 如果一个任务又不重又不独立，硬开子代理只是增加成本。

Plan 模式 是配合子代理的好搭档：先用 Plan 模式把大任务拆成有依赖关系的子任务图，再识别出哪些是并行节点，然后派子代理去执行那些并行节点——这是系统性用好 AI 编程工具的标准流程。

---

常见问题

Q：子代理和主 Agent 用的是同一个模型吗？会多花钱吗？

默认是同一个模型。每个子代理启动时会有独立的 token 计费，主会话 + 子代理的总 token 消耗会高于只用主会话做全部工作（因为子代理有自己的上下文初始化开销）。但换来的是：主会话上下文不被撑爆，总体质量更可控，长任务不中断。是否划算取决于任务规模。具体计费以 Anthropic 官方说明 为准。

Q：子代理能不能写文件、执行命令，不只是"调研"？

可以。子代理的权限默认和主 Agent 相同，可以读写文件、执行命令。但要注意：子代理如果写了文件，主 Agent 需要在派活指令里明确"你完成后把改了哪些文件告诉我"，否则主会话不会自动知道。写操作的子代理更需要派活时把范围写清楚，防止乱改。

Q：我能控制子代理用 Haiku 而不是 Sonnet 来省钱吗？

在 Claude Code 的对话层面，你可以在派活描述里建议模型规格，但最终决策由 Claude Code 内部的路由逻辑决定。如果你是通过 API 直接构建多 Agent 系统，可以在 Agent 工具调用参数里指定模型。具体参数见 Anthropic API 文档。

Q：子代理和 MCP（Model Context Protocol）是什么关系？

MCP 是给 Agent 扩展"工具能力"的协议（比如接入浏览器、数据库、外部 API）；子代理是"把一块活派给另一个 Agent 实例"的调度机制。两者正交，不冲突——子代理本身也可以使用 MCP 工具。可以把 MCP 理解为"单个 Agent 的工具箱扩展"，子代理理解为"任务的横向拆分"。

Q：子代理失败了怎么办？主会话能感知到吗？

主 Agent 会收到子代理的返回，如果子代理遇到了阻塞（找不到文件、权限不够、任务描述歧义），返回内容会说明失败原因。主 Agent 可以根据返回决定：重新派活并补充更多背景信息，或者接管这块任务自己做。

---

👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。