06.4 Subagents 子代理编排

把大任务拆给拥有独立上下文的下级 Agent，是控制复杂度和成本的关键杠杆。

读完你能做什么：设计出一套主代理调度、子代理执行的分工，并用它同时降低上下文污染和成本。

一、子代理解决什么问题

1.1 核心价值：上下文隔离

主会话的上下文是宝贵且会被污染的。有些工作会产生大量"噪音"：

text

"在 500 个文件里找出所有调用了废弃 API 的地方"
→ 需要读大量文件
→ 这些文件内容如果全进主上下文，会把主线任务挤没

子代理让这类工作在独立的上下文里进行，只把最终结论回传主会话。

text

主会话上下文              子代理上下文（独立）
┌──────────────┐         ┌──────────────────┐
│ 主线任务      │  派发→   │ 读 500 个文件      │
│              │         │ 分析、筛选         │
│              │  ←结论   │ （噪音留在这里）    │
│ 收到:15处调用 │         └──────────────────┘
└──────────────┘              用完即弃

1.2 三大用途

用途	例子
隔离噪音	大规模搜索、读取，只要结论
并行加速	同时调查多个独立的问题
降本	用便宜模型（Haiku）做跑腿，主会话用 Opus 决策

二、定义一个子代理

子代理是 .claude/agents/<name>.md 文件，用 YAML frontmatter 配置。

2.1 最小示例

markdown

---
name: file-scanner
description: 在大型代码库中快速定位与关键词相关的文件。用于需要广泛搜索但不需要深度分析的场景。
tools: Glob, Grep, Read
model: haiku
---

你负责快速定位文件。

规则：
- 只返回文件路径 + 匹配到的关键行 + 一句话说明
- 不要分析代码细节，不要给建议
- 如果匹配太多（>30 个文件），只返回最相关的 30 个，并说明总数

2.2 全部 frontmatter 字段

字段	必填	作用
`name`	✅	唯一标识（小写+连字符，不能含 `:`）
`description`	✅	何时该委派给它（Claude 据此决定调用）
`tools`		可用工具；省略则继承全部子代理工具
`disallowedTools`		从继承/指定列表中移除的工具
`model`		`sonnet`/`opus`/`haiku`/`fable`/完整 ID/`inherit`（默认 inherit）
`permissionMode`		权限模式
`maxTurns`		最大轮数上限
`skills`		启动时预加载进上下文的技能（注入全文，非仅描述）
`mcpServers`		该子代理可用的 MCP server
`hooks`		该子代理专属的生命周期 hook
`memory`		持久记忆范围 `user`/`project`/`local`
`background`		`true` 则总在后台跑
`effort`		该子代理的推理级别
`isolation`		`worktree` 则在隔离的 git worktree 里跑
`color`		任务列表中的显示颜色
`initialPrompt`		作为主会话 agent 时自动提交的首轮 prompt

2.3 动态定义（不建文件）

bash

claude --agents '{
  "reviewer": {
    "description": "Reviews code for bugs",
    "prompt": "You are a meticulous code reviewer. Report only real bugs.",
    "tools": ["Read", "Grep", "Glob"],
    "model": "opus"
  }
}'

三、混合模型：最大的成本杠杆

回顾成本比例 Haiku : Sonnet : Opus ≈ 1 : 5 : 25（见 03.5）。

策略：让昂贵的模型只做决策，便宜的模型做跑腿。

markdown

---
name: explorer
description: 探索代码库回答结构性问题。用于"X 在哪""有多少地方用了 Y"这类广度搜索。
tools: Glob, Grep, Read
model: haiku
---

你是探索者。快速搜索并返回精炼结论，不做深度分析。

主会话（Opus）遇到需要搜索时委派给 explorer（Haiku）：

text

> 我要重构认证逻辑。先派 explorer 找出所有直接调用 verifyToken() 的地方，
  我基于它的报告决定重构策略。

Explorer 读了 50 个文件（成本按 Haiku 算），只回传"15 处调用及位置"，主会话的 Opus 上下文保持干净且便宜。

四、并行编排

4.1 后台执行（默认行为）

从 v2.1.198 起，Claude 默认在后台运行子代理。这意味着多个子代理可以并行。

text

> 同时调查三个独立的性能问题（它们互不相关，可以并行）：
  1. 派一个子代理分析数据库慢查询（看 slow query log）
  2. 派一个子代理分析 API 响应时间分布
  3. 派一个子代理检查前端 bundle 大小
  三个都完成后，汇总成一份报告。

4.2 查看并行任务

text

> /tasks

bash

claude agents               # 打开 agent view 监控
claude agents --json        # 脚本化查询活跃会话

4.3 什么时候该并行 vs 串行

text

✅ 并行：任务互不依赖（三个独立的调查）
❌ 并行：后一个依赖前一个的结果（先找 bug 再修）

五、验证型子代理：对抗确认偏误

一个高价值模式：用子代理做独立验证，因为它有隔离的上下文，不会被主会话的推理锚定。

markdown

---
name: verifier
description: 独立核查一个技术断言是否成立。用于对主会话的重要结论做交叉验证。
tools: Read, Grep, Glob, Bash, WebSearch
model: opus
---

你是独立验证者。你只会收到一个"待核查的断言"，不会收到得出它的推理过程。

任务：
1. 用工具独立查证这个断言
2. 输出结论：`确认` / `否定` / `无法验证`
3. 附上你查到的证据（文件路径:行号，或 URL）
4. 不要试图重建原始推理，只看证据本身

如果断言含多个子命题，逐个核查。

用法：

text

> 你刚才说"这个内存泄漏是因为 event listener 没有解绑"。
  派 verifier 独立核查这个结论，把断言给它但不要给它你的推理过程。

上下文隔离是关键：如果 verifier 能看到原始推理，它会被带偏，验证退化成确认。子代理天然的上下文隔离正好提供了这个隔离。见 04.3 第五节。

六、子代理的持久记忆

子代理可以有自己的跨会话记忆（与主会话隔离）：

markdown

---
name: db-expert
description: 数据库相关问题的专家，积累本项目的数据库知识
memory: project
tools: Read, Grep, Bash
---

你是本项目的数据库专家。随着工作积累对 schema、索引、慢查询的认识。

memory 取值：

值	存储位置	用途
`user`	`~/.claude/agent-memory/<name>/`	跨所有项目
`project`	`.claude/agent-memory/<name>/`	本项目，可提交共享
`local`	`.claude/agent-memory-local/<name>/`	本项目，不提交

七、worktree 隔离的子代理

让子代理在独立的 git worktree 里工作，改动完全隔离：

markdown

---
name: experimenter
description: 尝试有风险的重构方案，在隔离环境中验证可行性
isolation: worktree
tools: Read, Edit, Write, Bash
---

你在一个隔离的 worktree 中工作。大胆尝试，如果方案不可行也没关系
——你的改动不会影响主工作区。最后报告：方案是否可行 + 关键发现。

worktree 在子代理无改动时会自动清理。

八、内置子代理

Claude Code 自带几个子代理：

名字	用途
`general-purpose`	通用多步任务
`Explore`	只读的广度搜索
`Plan`	设计实现方案

text

> 用 Explore 子代理搜一下这个项目里所有的认证相关代码

九、编排的四条原则

原则 1：子代理适合"广度"，主会话适合"深度"

派子代理去做"读很多、筛出关键"的活；深度推理和决策留在主会话。

原则 2：给子代理明确的返回契约

text

description 里说清它该返回什么格式。子代理只回传结论，
所以返回内容必须自包含——主会话看不到它的中间过程。

原则 3：限制子代理的工具和轮数

markdown

tools: Grep, Glob, Read     # 只给需要的
maxTurns: 10                # 防止失控

原则 4：并行前确认无依赖

误把有依赖的任务并行化，会导致后面的子代理基于过时假设工作。

十、一个完整的编排实战

"接手一个陌生的大项目"：

text

> 我刚接手这个项目，帮我快速建立认知。用子代理并行调查（互不依赖）：

1. 派 Explore 子代理：梳理目录结构和模块划分，输出一张模块地图
2. 派一个 haiku 子代理：统计各语言/框架占比，找出最大的几个文件
3. 派一个子代理：用 git log 分析最近 3 个月改动最频繁的 5 个模块
4. 派一个子代理：找出所有的配置文件和环境变量，列出这个项目依赖哪些外部服务

四个都回来后，你综合成一份"新人上手指南"，我来审阅。

主会话（Opus）只做最后的综合，四个调查并行且各自的噪音都隔离在子代理里。

06.4 Subagents 子代理编排 ​

一、子代理解决什么问题 ​

1.1 核心价值：上下文隔离 ​

1.2 三大用途 ​

二、定义一个子代理 ​

2.1 最小示例 ​

2.2 全部 frontmatter 字段 ​

2.3 动态定义（不建文件） ​

三、混合模型：最大的成本杠杆 ​

四、并行编排 ​

4.1 后台执行（默认行为） ​

4.2 查看并行任务 ​

4.3 什么时候该并行 vs 串行 ​

五、验证型子代理：对抗确认偏误 ​

六、子代理的持久记忆 ​

七、worktree 隔离的子代理 ​

八、内置子代理 ​

九、编排的四条原则 ​

原则 1：子代理适合"广度"，主会话适合"深度" ​

原则 2：给子代理明确的返回契约 ​

原则 3：限制子代理的工具和轮数 ​

原则 4：并行前确认无依赖 ​

十、一个完整的编排实战 ​

延伸阅读 ​

06.4 Subagents 子代理编排

一、子代理解决什么问题

1.1 核心价值：上下文隔离

1.2 三大用途

二、定义一个子代理

2.1 最小示例

2.2 全部 frontmatter 字段

2.3 动态定义（不建文件）

三、混合模型：最大的成本杠杆

四、并行编排

4.1 后台执行（默认行为）

4.2 查看并行任务

4.3 什么时候该并行 vs 串行

五、验证型子代理：对抗确认偏误

六、子代理的持久记忆

七、worktree 隔离的子代理

八、内置子代理

九、编排的四条原则

原则 1：子代理适合"广度"，主会话适合"深度"

原则 2：给子代理明确的返回契约

原则 3：限制子代理的工具和轮数

原则 4：并行前确认无依赖

十、一个完整的编排实战

延伸阅读