第 19 章 Subagents:并行探索与上下文隔离

当主对话被十几个文件 dump、三份日志、两轮搜索结果塞满时,你就该把活儿分给 subagent 了。这一章讲透独立上下文、配置字段、并行执行、嵌套 Fork,以及——更重要的——什么时候不要用 subagent。

19.1 结论:Subagents 是并行探索与隔离上下文的利器

Subagents 是拥有独立上下文窗口的专用 AI 助手。主代理把一个子任务连同简短指令委托给 subagent,subagent 在自己的上下文里完成探索、搜索、读写,完成后只向主对话返回摘要,不回吐中间的文件 dump 和搜索噪声。

一句话定位:

独立上下文 + 只返回摘要,让大规模任务不撑爆主窗口。

这带来三类收益,正好对应主对话最容易被压垮的三种场景:

场景	主对话的痛点	Subagent 的解法
并行探索	顺序读 5 个模块,上下文被文件内容塞满	5 个 Explore subagent 并发,各读各的,只回结论
独立子任务	一次性诊断脚本写完就丢,但写它的过程很吵	general-purpose subagent 写完只回"脚本已生成 + 用法"
低耦合批量修改	10 个文件改同一类 pattern,主代理要 hold 全部上下文	多个 subagent 各改一片,主代理只 merge 摘要

但 subagent 也有它做不好的事——需要精确代码引用、需要跨文件一致性保证、需要让主对话看到完整 diff 的任务,不该委托。19.7 节专门讲这条边界。

本章版本基线:Claude Code v2.1.202+,核对日期 2026-07-08。涉及 research preview 的功能(Fork、Agent Teams)会显式标注。

19.2 子代理机制:独立上下文、只返回摘要

理解 subagent 的关键,是看清它和主对话之间的信息流边界。

text

┌──────────────────────── 主对话上下文(约 200K tokens)────────────────────────┐
│                                                                              │
│  用户:并行审查 auth/payment/notification 三个模块                              │
│       │                                                                      │
│       ├─── Agent(Explore, "审查 auth 模块")      ──┐                          │
│       ├─── Agent(Explore, "审查 payment 模块")    ──┤  并发派发                │
│       ├─── Agent(Explore, "审查 notification 模块")──┤                          │
│       │                                             │                          │
│       │   ┌─── subagent 独立上下文 ───────────────┐ │                          │
│       │   │ 读 12 个文件 / grep 30 次 / 自己推理   │ │                          │
│       │   │ ...这些细节不进主对话...                │ │                          │
│       │   └────────────────────────────────────────┘ │                          │
│       │                                             │                          │
│       ◄─── 摘要 1:auth 模块 3 个 HIGH,文件:行号     │                          │
│       ◄─── 摘要 2:payment 模块 1 个 CRITICAL        │                          │
│       ◄─── 摘要 3:notification 模块 0 问题          │                          │
│       │                                                                      │
│  主代理 merge 三份摘要 → 输出整合报告给用户                                    │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

三个要点:

独立上下文:subagent 启动时,只拿到主代理派发时给的 prompt + 自身的 system prompt + 基本环境信息(工作目录)。主对话此前的历史、CLAUDE.md(对自定义 subagent 而言)、git status,按规则加载——但主对话当前轮次的中间产物不会泄漏进去。
只返回摘要:subagent 完成后,只有它的最终消息回到主对话。它读过哪些文件、grep 了什么、中间推理了什么,全部留在它自己的上下文里,主对话看不到。
委托是单向的:主代理决定何时委托;subagent 不能反向调用主代理。subagent 可以再委托嵌套 subagent(19.6 节),但每一层都是向下的。

与第 06 章的「可执行闭环」对照,subagent 把闭环步骤 2(建立事实模型)和步骤 4(运行验证)的部分负载挪到了独立上下文里——主对话只保留架构决策和最终审查。这就是为什么它叫"上下文隔离的利器"。

19.3 配置:.claude/agents/*.md 与 frontmatter 字段详解

Subagent 的定义是一个 Markdown 文件:YAML frontmatter 做配置,正文做 system prompt。存放位置决定作用域。

19.3.1 存放位置与优先级

位置	作用域	优先级	创建方式
Managed settings 目录	全组织	1(最高)	管理员部署
`--agents` CLI 参数	当前会话	2	启动时传 JSON
`.claude/agents/`	当前项目	3	让 Claude 写,或手写文件
`~/.claude/agents/`	你的所有项目	4	让 Claude 写,或手写文件
插件的 `agents/` 目录	插件启用处	5(最低)	随插件安装

同名冲突时,高优先级覆盖低优先级。项目级 .claude/agents/ 从当前工作目录向上扫描,每一层 .claude/agents/ 都会被发现;v2.1.178 起,同名时取离工作目录最近的那一个。

推荐策略:团队共享的 subagent(如 code-reviewer、security-auditor)放项目级 .claude/agents/ 并纳入版本控制;个人偏好(如自己的 explorer 风格)放 ~/.claude/agents/。

19.3.2 frontmatter 字段详解

只有 name 和 description 必填,其余可选。字段较多,按用途分组记忆:

身份与触发

字段	必填	作用
`name`	是	全小写加连字符的唯一标识;Hooks 收到的 `agent_type`
`description`	是	告诉主代理何时该委托给这个 subagent;写不清楚就不会被触发

能力约束

字段	作用
`tools`	工具白名单;省略则继承主对话全部工具
`disallowedTools`	工具黑名单;先于 `tools` 应用。支持 `mcp__<server>` / `mcp__<server>__` 模式,`mcp__` 移除全部 MCP 工具
`mcpServers`	该 subagent 独占的 MCP 服务器(内联定义或按名引用);插件 subagent 此字段被忽略
`skills`	启动时预载入的 Skill 全文;区别于在 `tools` 里列 `Skill`(那只表示能用)

模型与推理

字段	作用
`model`	`sonnet` / `opus` / `haiku` / `fable` / 完整 model ID / `inherit`(默认)
`effort`	推理档:`low` / `medium` / `high` / `xhigh` / `max`,覆盖会话档位

权限与隔离

字段	作用
`permissionMode`	`default` / `acceptEdits` / `auto` / `dontAsk` / `bypassPermissions` / `plan`;父级是 `bypassPermissions`/`acceptEdits`/`auto` 时不可覆盖
`isolation`	设为 `worktree` 则在临时 git worktree 中运行,默认从默认分支拉出
`maxTurns`	最大 agentic 轮次,防失控

记忆与生命周期

字段	作用
`memory`	持久记忆作用域:`user` / `project` / `local`,跨会话积累知识
`hooks`	仅作用于该 subagent 的生命周期 Hook;插件 subagent 此字段被忽略
`background`	`true` 则始终后台运行;省略时由 Claude 决定,v2.1.198 起默认后台

展示与入口

字段	作用
`color`	任务列表里的展示颜色
`initialPrompt`	作为主会话 agent(经 `--agent` 或 `agent` 设置)运行时自动作为首轮提交

两个易错点:

tools 与 disallowedTools 同时存在:disallowedTools 先生效,然后 tools 在剩余池里做白名单。同时列在两边的工具会被移除。
skills 不是 tools:预载入 Skill 用 skills 字段,不要把 Skill 写进 tools 来"预载入"——后者只表示"允许调用 Skill 工具"。

19.3.3 一个完整自定义 subagent 范例:security-auditor

下面是一个项目级 security-auditor subagent,适合在每次涉及鉴权/加密/输入处理的改动后调用。参考 web-studio/agents/qa-reviewer.md 的风格,但聚焦安全。

markdown

---
name: security-auditor
description: 对刚改动的代码做安全审查——鉴权绕过、注入、密钥泄漏、SSRF、不安全反序列化。任何涉及 auth/crypto/输入处理/网络请求的改动后主动调用。
tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit
model: sonnet
effort: high
permissionMode: default
maxTurns: 30
---

你是安全审查员,默认怀疑,不给「差不多就行」。

## 工作流程
1. 用 `git diff origin/main...HEAD --name-only` 列出本次改动文件。
2. 对每个文件,按下面的 checklist 逐项核查,证据引用 `文件:行号`。
3. 跑 `npm audit --omit=dev` 或 `pip-audit`(看 lockfile 类型),记录已知漏洞。
4. grep 高风险模式:`eval(`、`dangerouslySetInnerHTML`、`child_process.exec`、`SQL.*\+`、`https?://` 硬编码。

## Checklist
- 鉴权:每个写操作经 `requireAdmin()` 或等价 middleware;无 IDOR。
- 注入:SQL 参数化;无未消毒模板拼接;命令行参数走数组形式。
- 密钥:`.env` 不在版本控制;无硬编码 token;CI secret 不进日志。
- SSRF:外部 URL 输入经白名单或协议/域校验。
- 反序列化:不信任输入不进 `pickle`/`yaml.load`/`unserialize`。

## 产出格式

最后给一句结论:「阻塞 N 项,可合并 N 项」。阻塞项不为零,不许 `/commit`。

放在 .claude/agents/security-auditor.md,纳入版本控制。Claude Code 会监视该目录,几秒内热加载,下次委托即生效。

命令(让主代理委托给它):

text

刚改完 src/auth 的 refresh token 逻辑,用 security-auditor 审一遍

预期输出(主对话收到的是 subagent 的摘要,不是它读过的文件):

text

security-auditor 审查了 4 个改动文件,发现 2 项阻塞:
- CRITICAL src/auth/session.ts:88  refresh token 未轮换,可重放
- HIGH     src/api/upload.ts:42    未校验 MIME 类型
另有 1 项建议合并。结论:阻塞 2 项,不许 commit。

验证:

text

/agents

在列表里看到 security-auditor 已加载。如果新建了 agents 目录后看不到,重启一次 Claude Code(目录监听只覆盖会话启动时已存在的目录)。

失败边界:

description 写得太泛(如"做安全审查"),主代理可能在不相关任务上也委托,造成噪音;写得越精确(列出触发关键词),越准。
tools 漏掉 Bash 就跑不了 git diff / npm audit,审查会停在第一步。
这个 subagent 是只读的(disallowedTools: Write, Edit),它不能自己改代码;如果你希望它顺手修复,去掉 disallowedTools 并把 permissionMode 改成 acceptEdits。

19.4 内置 subagent:Explore / Plan / general-purpose

Claude Code 自带三个核心内置 subagent,主代理会根据任务自动委托。理解它们的分工,就是理解主代理什么时候会"自动把活儿交出去"。

内置 subagent	模型	工具	用途
Explore	继承主对话(v2.1.198 起)	只读;禁 Write/Edit	文件发现、代码搜索、代码库探索
Plan	继承主对话	只读;禁 Write/Edit	Plan Mode 下的代码库研究
general-purpose	继承主对话	全工具	复杂多步任务,既探索又行动

Explore 是日常最常被自动委托的。当主代理需要"找一下 X 在哪儿定义""谁调用了 Y",它会派一个 Explore subagent,指定力度:quick(精准查找)、medium(平衡)、very thorough(全面)。

v2.1.198 之前 Explore 固定跑 Haiku,便宜但能力有限;v2.1.198 起继承主对话模型(在 Claude API 上封顶 Opus)。如果你怀念旧的低成本行为,可以定义一个用户级同名 subagent:

yaml

---
name: Explore
description: Override built-in Explore to always use Haiku for cheap exploration.
model: haiku
tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit
---
快速只读探索,读完只回结论。

同名用户级覆盖项目级覆盖内置,model: haiku 会被保留。

Plan 是 Plan Mode 的内部分身。第 07 章讲过,Plan Mode 下主对话保持只读;当它需要理解代码库时,委托给 Plan subagent 做研究,研究细节留在 subagent 上下文里,主对话只收到用来组装 plan 的结论。这就是为什么 Plan Mode 能在不撑爆主窗口的前提下完成大范围探索。

general-purpose 是兜底的全能选手。当任务既需要探索又需要修改、需要多步推理、或者中间结果需要解读后再行动,主代理委托给它。它有全部工具,可以真正改代码。

关闭内置 subagent:

只关 Explore/Plan:CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1(v2.1.198+),主代理自己读文件。
关全部内置:在 permissions.deny 里加 Agent 工具,或非交互/SDK 下设 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1。
关特定类型:permissions.deny 里加 Agent(<name>)。

另有 statusline-setup、claude-code-guide 等辅助 subagent,由 /statusline 或问 Claude Code 问题时自动触发,一般不用手动调。

19.5 并行执行:v2.1.198 默认后台 + 实战

v2.1.198 起,subagent 默认在后台运行。主代理可以在一条消息里并发派发多个 subagent,它们各跑各的,完成后再把摘要回注主对话。这是大规模任务的主力武器。

19.5.1 并行委托的写法

主代理在一条消息里发多个 Agent 工具调用,就会并发执行(参考第 06 章「单轮工具并发」)。用户侧的指令可以这样写:

text

并行审查这三个模块,每个模块一个 Explore subagent,只回严重问题摘要:
- src/auth:鉴权绕过、session 固定
- src/payment:金额篡改、重放
- src/notification:SSRF、模板注入

主代理会同时派发三个 Explore,各自读各自的目录,完成后回三份摘要。

19.5.2 实战:并行审查三个模块

命令(在交互会话里):

text

用三个 Explore subagent 并行审查 src/auth、src/payment、src/notification 三个模块,
每个返回 CRITICAL/HIGH 问题清单,带 文件:行号 证据,不超过 10 条。

预期输出(主对话最终收到的是 merge 后的摘要,不是 subagent 中间读过的几百个文件):

text

== src/auth (Explore #1) ==
- HIGH src/auth/session.ts:88  refresh token 未轮换,可重放
- HIGH src/auth/middleware.ts:24 requireAdmin 漏覆盖 /api/admin/users/bulk

== src/payment (Explore #2) ==
- CRITICAL src/payment/amount.ts:12 金额从 body 直接取,未校验范围
- HIGH     src/payment/replay.ts:45  idempotency key 未强制唯一

== src/notification (Explore #3) ==
- HIGH src/notification/webhook.ts:30  webhook URL 未做协议/域白名单,SSRF
- MED  src/notification/template.ts:18 用户输入直接拼进模板

合并结论:1 CRITICAL + 5 HIGH + 1 MED。建议优先修 payment 的金额校验。

验证:

text

/agents

切到 Running 标签(或 v2.1.198+ 的后台任务列表),能看到三个 Explore subagent 并发运行。完成后它们从 Running 消失,摘要出现在主对话。

如果你怀疑某个 subagent 实际上没干活,可以查它的最终消息——但注意,中间的文件 dump 你看不到,这是设计如此(隔离上下文)。

失败边界(重要):

并行 subagent 改同一文件会冲突:Explore 是只读的,所以审查任务没问题。但如果让三个可写 subagent 同时改 package.json、src/index.ts 这类共享文件,后写的会覆盖先写的,且主代理不会自动 merge。这是并行委托最常见的灾难。
- 解法一:把改动按文件/目录正交切分,每个 subagent 只碰自己那片。
- 解法二:用 isolation: worktree(19.8 节),每个 subagent 在独立 worktree 改,最后人工 merge。
subagent 之间不能通信:三个 Explore 互相看不到对方的发现。如果审查需要交叉印证(比如 auth 的 session 轮换问题要结合 payment 的重放问题一起看),这种交叉判断必须回到主对话做。
后台默认意味着延迟:v2.1.198 起默认后台,主代理可以继续干别的,但如果你需要结果才能往下走,显式说"我等结果",或设 background: false 在 subagent 定义里。

19.6 嵌套与 Fork:最深 5 层、/fork 继承上下文、Agent Teams

Subagent 自己也可以再派 subagent,形成嵌套结构。另有两种衍生模式:Fork 和 Agent Teams。

19.6.1 嵌套 subagent(最深 5 层)

在 subagent 的 tools 里列 Agent,它就能派发自己的子 subagent。最大嵌套深度为 5 层(research preview 特性,版本敏感,核对日期 2026-07-08)。

典型用途是「协调者-工人」结构:一个 coordinator subagent 接到大任务,拆成几片,派给多个 worker subagent 并发执行,自己只做拆分和汇总。

yaml

---
name: coordinator
description: 拆分大重构任务,派给 worker subagent 并发执行,汇总结果。
tools: Agent(worker, researcher), Read, Bash
---
你是协调者。接到任务后:
1. 用 Read/Grep 拆出正交的子任务(按目录或文件切分)。
2. 每片派给一个 worker subagent。
3. 收齐 worker 摘要后,汇总成单一报告。
不要自己改代码,改代码交给 worker。

注意 Agent(worker, researcher) 是白名单:coordinator 只能派这两种 subagent。这是 v2.1.63 起 Task 工具改名 Agent 后引入的语法;老的 Task(...) 写法仍作为别名工作。

失败边界:

嵌套过深会失控:5 层嵌套意味着主代理 → A → B → C → D → E。每一层都丢失上一层的一部分上下文,到第 5 层时,subagent 可能完全不知道原始目标是什么。实践中 2 层是甜点,3 层就要谨慎,4 层以上几乎一定出问题。
协调者上下文不足:coordinator 只看到 worker 的摘要,看不到 worker 读过的文件。如果汇总需要精确引用,让 worker 在摘要里带 文件:行号 证据。
成本:嵌套会放大调用量。5 层 × 每层 3 个并发 = 最多 3⁵ ≈ 243 次 LLM 调用。设 maxTurns 兜底。

19.6.2 Fork 模式:/fork 继承完整对话上下文

Fork 是一种特殊的 subagent(research preview,版本敏感)。普通 subagent 启动时只拿到派发时的 prompt;fork 启动时继承主对话此刻的完整上下文——包括此前的全部对话历史、已读文件、已做的推理。

适用场景:你和一个长对话已经建立了大量上下文(讨论了架构、看了五个文件、定了方案),现在想分一支出去做「如果换种实现会怎样」的探索,但又不想污染主对话。

text

/fork 探索一下用事件驱动代替现在的轮询实现,只回结论,别改主分支代码

Fork 带着完整上下文去探索,完成后只回摘要。主对话继续走原路线,fork 的探索结果作为参考。

失败边界:fork 继承的是派发时刻的上下文快照,之后主对话的新进展它看不到。如果探索需要主对话的最新状态,重新 fork 一次。

19.6.3 Agent Teams:多 peer 会话协作

Agent Teams(research preview)是另一种形态:多个 peer agent 会话互相通信协作,而不是单向委托。每个 teammate 是独立会话,可以发消息给其他 teammate,主代理作为协调者监控进度。

这和 subagent 的核心区别:

维度	Subagent	Agent Teams
拓扑	树状,单向委托	图状,peer 互发消息
上下文	完全隔离	各自独立,但可通过消息交换信息
适用	可拆分的独立子任务	需要协作/协商的复杂任务
状态	稳定	research preview

subagent 的定义可以被 teammate 复用:派发 teammate 时指定 subagent type,teammate 会用该 subagent 的 tools 和 model,定义正文作为附加指令注入其 system prompt。但并非所有 frontmatter 字段在 teammate 路径上都生效(如 hooks、mcpServers、permissionMode),细节查官方 agent-teams 文档。

Agent Teams 适合「前端 agent 和后端 agent 协商 API 契约」这类需要对话的场景;subagent 适合「三个模块各审各的」这类可独立完成的场景。不要用 Agent Teams 做能 subagent 做的事——peer 通信的协调成本远高于单向委托。

19.7 何时用何时不用 Subagent

这是本章最重要的一节。subagent 用错地方,比不用更糟——你会得到一份看起来合理但无法验证的摘要。

19.7.1 用 subagent

并行探索:同时审 N 个模块、同时调研 N 个方案、同时读 N 个目录。每个 subagent 只回结论,主对话不被文件 dump 淹没。
独立子任务:写一次性诊断脚本、生成报告、跑 lint 并解读输出——这些任务的过程很吵,结果只需要一句话。
低耦合批量修改:10 个文件改同一类 pattern,文件之间互不依赖(如统一 import 顺序、统一错误处理风格)。按文件切分给多个可写 subagent,各改各的。
上下文隔离的「支线」:想试一种实现思路,又不想污染主对话;用 fork 带着上下文去试,只回结论。

19.7.2 不用 subagent

需要精确代码引用:subagent 只返回摘要,它读过的文件、行号、中间推理不会进主对话。如果你后续要基于"那个函数第 42 行的 bug"继续工作,而那行号只在 subagent 上下文里,主对话就丢了证据。这种任务留在主对话做,或者让 subagent 在摘要里显式带 文件:行号 证据。
跨文件一致性保证:改 A 文件要同步改 B 文件的接口、改 schema 要同步改所有 caller——这类强耦合任务,用主上下文操作,让 Claude 同时看到所有相关文件。subagent 各改各的,merge 时一定对不齐。
需要主对话看到完整 diff:代码审查、最终交付,要在主对话用 git diff 看。委托给 subagent 改代码,主对话只收到"改好了"三个字,你失去了 diff 审查面——这违反第 06 章的「人类审查」支点。
超大型耦合重构:见第 06 章能力边界。这类任务连主对话都难,subagent 更难。
需要让 Claude 基于失败自我修正:闭环步骤 5-6(读失败、自我修正)需要主对话持有失败上下文。委托给 subagent 改、它自己跑自己改,失控风险高;除非用 worktree 隔离 + 严格 maxTurns。

判断口诀:

能拆成正交子任务的,用 subagent;需要一致性保证的,留主对话。

19.8 worktree 隔离:避免并行写冲突

19.5 节提到并行可写 subagent 改同一文件会冲突。根本解法是 isolation: worktree:subagent 在临时 git worktree 中运行,拥有仓库的独立副本,改完不影响主工作树。

yaml

---
name: batch-refactor
description: 批量重构,每个 subagent 在独立 worktree 改,最后人工 merge。
tools: Read, Edit, Write, Glob, Grep, Bash
model: sonnet
isolation: worktree
permissionMode: acceptEdits
maxTurns: 25
---
按指令在当前 worktree 改代码,改完跑 `npm run typecheck` 自证,只回 diff 摘要。

worktree 默认从你的默认分支拉出(不是当前 HEAD,这点要小心——如果你在 feature 分支上工作,worktree 不会带你的未提交改动)。subagent 完成后,如果 worktree 没有改动,自动清理;有改动则保留,你需要手动 merge 或 cherry-pick。

命令(派发多个 worktree 隔离的 subagent):

text

并行派 3 个 batch-refactor subagent,分别改 src/a/*、src/b/*、src/c/* 的错误处理风格,
各自在独立 worktree,完成后只回 diff 摘要和 worktree 路径。

预期输出:

text

batch-refactor #1 (worktree: .claude/worktrees/a-refactor)
  改了 4 个文件,统一了 try/catch 风格,typecheck 通过
  diff 摘要: ...

batch-refactor #2 (worktree: .claude/worktrees/b-refactor)
  改了 6 个文件,typecheck 通过
  diff 摘要: ...

batch-refactor #3 (worktree: .claude/worktrees/c-refactor)
  改了 3 个文件,typecheck 失败 2 处,已回退,未改动

验证:

bash

git worktree list
# 主仓库 + 三个 worktree
git -C .claude/worktrees/a-refactor diff --stat

逐个 review worktree 的 diff,满意的 cherry-pick 回主分支,不满意的直接删 worktree。

失败边界:

worktree 从默认分支拉,不带你的未提交改动;如果你的改动是 subagent 工作的前提,先 commit 到默认分支或换 worktree.baseRef 配置。
多个 worktree 改完后,merge 回主分支时仍可能冲突(比如都改了 package.json 的 dependencies)。人工 merge,别让 subagent 自动 merge。
worktree 不适合需要共享状态的修改(如数据库 migration)——每个 worktree 独立,看不到彼此的 schema 变更。

worktree 隔离是第 20 章 Workflows 的预告:Workflows 把"派发多个 subagent + 管理依赖 + 收集结果"做成了声明式编排,底层就是 worktree 隔离 + 并行 subagent。

19.9 失败边界汇总

把本章分散的失败边界集中一次,作为使用前的 checklist:

失败模式	症状	对策
子代理上下文不足	subagent 给出泛泛结论,没引用具体文件/行号	摘要契约里强制要求 `文件:行号` 证据;或改用主对话
并行写冲突	多个可写 subagent 改同一文件,后写覆盖先写	按文件正交切分;或用 `isolation: worktree`
嵌套过深失控	第 4-5 层 subagent 不知道原始目标	限 2 层,最多 3 层;设 `maxTurns` 兜底
依赖子代理做精确引用	主对话后续工作需要 subagent 看过的细节,但只剩摘要	这类任务别委托;或让 subagent 把证据写进摘要
description 写得太泛	subagent 被过度触发或不触发	description 写明触发关键词和场景,如"任何涉及 auth/crypto 改动后"
tools 漏关键工具	subagent 跑到一半卡住,如审查 subagent 没有 Bash 跑不了 `git diff`	上线前 dry-run 一次,确认工具链完整
fork 上下文过期	fork 派发后主对话继续走,fork 用的是旧状态	fork 适合一次性探索;需要新状态重新 fork
Agent Teams 滥用	简单并行任务用 peer 通信,协调成本爆炸	能 subagent 单向委托的,别用 Agent Teams

19.10 核心心法

Subagents 的价值不在"并行更快",而在"上下文隔离让主对话保持清醒"。一个被文件 dump 塞满的主对话,推理质量会下降;把吵闹的子任务挪到 subagent,主对话只保留架构决策和最终审查——这才是 subagent 的真正杠杆。

记住第 06 章的心法:你做架构决策和关键审查,Claude 做实现和探索。 Subagent 是 Claude 用来"做探索"的分身,不是用来替你做审查的替身。最终 diff 永远在主对话用 git diff 看,最终安全审查永远在主对话用 /security-review——这两件事,不能委托给 subagent。

下一章:Workflows:声明式编排

第 19 章 Subagents:并行探索与上下文隔离 ​

19.1 结论:Subagents 是并行探索与隔离上下文的利器 ​

19.2 子代理机制:独立上下文、只返回摘要 ​

19.3 配置:.claude/agents/*.md 与 frontmatter 字段详解 ​

19.3.1 存放位置与优先级 ​

19.3.2 frontmatter 字段详解 ​

19.3.3 一个完整自定义 subagent 范例:security-auditor ​

19.4 内置 subagent:Explore / Plan / general-purpose ​

19.5 并行执行:v2.1.198 默认后台 + 实战 ​

19.5.1 并行委托的写法 ​

19.5.2 实战:并行审查三个模块 ​

19.6 嵌套与 Fork:最深 5 层、/fork 继承上下文、Agent Teams ​

19.6.1 嵌套 subagent(最深 5 层) ​

19.6.2 Fork 模式:/fork 继承完整对话上下文 ​

19.6.3 Agent Teams:多 peer 会话协作 ​

19.7 何时用何时不用 Subagent ​

19.7.1 用 subagent ​

19.7.2 不用 subagent ​

19.8 worktree 隔离:避免并行写冲突 ​

19.9 失败边界汇总 ​

19.10 核心心法 ​

第 19 章 Subagents:并行探索与上下文隔离

19.1 结论:Subagents 是并行探索与隔离上下文的利器

19.2 子代理机制:独立上下文、只返回摘要

19.3 配置:.claude/agents/*.md 与 frontmatter 字段详解

19.3.1 存放位置与优先级

19.3.2 frontmatter 字段详解

19.3.3 一个完整自定义 subagent 范例:security-auditor

19.4 内置 subagent:Explore / Plan / general-purpose

19.5 并行执行:v2.1.198 默认后台 + 实战

19.5.1 并行委托的写法

19.5.2 实战:并行审查三个模块

19.6 嵌套与 Fork:最深 5 层、/fork 继承上下文、Agent Teams

19.6.1 嵌套 subagent(最深 5 层)

19.6.2 Fork 模式:/fork 继承完整对话上下文

19.6.3 Agent Teams:多 peer 会话协作

19.7 何时用何时不用 Subagent

19.7.1 用 subagent

19.7.2 不用 subagent

19.8 worktree 隔离:避免并行写冲突

19.9 失败边界汇总

19.10 核心心法