Subagent 与并行工作流
一句话定位：Subagent 是从主对话分出去的「独立上下文临时工」——高噪声活它干，摘要回主线；本文讲哪些活值得派、怎么定义、输出怎么设计才带证据。前置：Hooks：事件驱动的确定性控制——先熟悉工具与权限这套骨架；Claude Code 全景与日常使用——先认识这套产品本身。
先从测试日志刷屏说起
你让 Claude Code 修一个失败测试。它跑了测试，几百行日志滚过，找到那一条失败的，修好，再跑一遍全量确认。任务完成得不错，但你的上下文被两轮完整日志吃掉一大块——聊不了多久，又要压缩了。
让活有人干、脏东西别溅进主对话，是每个重度用户的共同愿望——把测试整个交给一个「分身」去跑，只让它回来一句话。
可分身真的可靠吗？它看不到主对话里聊过的约定，会不会误判？派出去的活，怎么保证干完干对、还带得回能采信的结果？
这就是 Subagent 要回答的问题。官方机制一句话：子代理从全新的空白上下文启动，带一份你写好的系统提示与任务简报，干完后只把摘要送回主对话——过程噪声全部留在它的上下文里。先看一次委派的解剖：
图：一次委派的解剖——①主对话 ②独立上下文（其 CLAUDE.md 即项目约定文件）③受限执行 ④摘要回传 ⑤并行与嵌套；隔离是手段，摘要才是交付
渐进拆解：外包给可信赖的分包工头
类比：开篇说的「临时工」，正式一点叫分包工头——主对话是总包，Subagent 是分包。总包把一栋楼的「电路检测」整包签出去：签合同（系统提示，写明范围与验收标准）、交底（任务简报）；分包工头自己带队伍干，噪声留在他的工地上；验收时他交回来的不是施工全程录像，而是一页检测报告。多个分包可以同时开工（并行），分包还能再雇自己的分包（嵌套），但总包桌上只出现各包的报告。
定义一个子代理：一份 markdown 的事
放在项目的 .claude/agents/ 下（随 git 全组共享）或用户级 ~/.claude/agents/（你的所有项目），文件就是「frontmatter + 正文」：
| 字段 | 用途 |
|---|---|
name | 身份 |
description | 委派依据 |
| 正文 | 系统提示——写清角色、范围、输出格式 |
tools | 白名单，只给指定工具（只读审计就只给 Read/Grep/Glob） |
disallowedTools | 黑名单，在继承基础上扣掉危险项（如 Write/Edit） |
model | 选档 |
maxTurns | 限步数 |
memory | 给分身配独立笔记 |
initialPrompt | 在它作为会话主代理时充当首条指令 |
每一条都是「给分身划边界」。同名按作用域优先级解析（管理策略 > CLI 参数 > 项目 > 用户 > 插件），/doctor 会报告重名文件。
委派的三种触发
- 自动委派：Claude 按任务描述与子代理的
description匹配，描述里写「use proactively」类措辞可鼓励主动派活。 - 显式委派：自然语言点名（「让 security-review 审一下 auth 模块」，是否派由 Claude 判断），或 @ 引用（补全列表里选，保证一定用它）。
- 会话级固定：用
--agent参数或配置，让整场会话都在某个子代理的系统提示、工具限制与模型下工作。
此外，除官方内置分身外，所有自定义子代理的描述合计超过 15000 token 会在启动时警告——清单也要瘦身。
前台与后台
前台子代理阻塞主对话直到干完，权限弹窗原样透传；后台子代理并行跑，权限请求会浮到主会话由你裁决，结果以完成通知的形式在后面的轮次送达（Ctrl+B 可把在跑的任务转后台）。并发默认上限 20 个在跑，子代理嵌套默认最深三层（主对话之下），到层的分身收不到再派工具、只能亲自干完。
安全网：输出扫描与证据设计
子代理可能读过你没审过的网页与文件，其文本可能夹带指向主对话的注入指令——官方对每份最终报告做扫描，两类改动：
- 模仿系统标签（如
<system-reminder>）的文本会被插入反斜杠、降级为普通文本。 - 形似指令或提及权限设置的内容会被打上标记行，提示主对话留意。
原文不删除、不改写。但扫描不是豁免——真正的防线在你自己：系统提示里规定输出格式，要求每条结论带文件路径、行号与可复查引用，让分身「带证据回来」而不是「带结论回来」。
流水线编排：分身串成一条线
分身除了并行，还能串行：让上一个分身的结论作为下一个分身的输入——「用代码评审分身找出性能问题，再派优化分身逐条修复」，Claude 会先等评审报告，再把相关上下文转给优化分身。并行管「互不依赖的同时干」，链式管「有依赖的先后干」，两样合起来就是多任务编排的全部形状。
再往上一步：Agent Teams（多代理协作）
主从委派之外，官方还提供「队友制」：多个 teammate 各自是完整的 Agent 会话——可以在同一进程内跟随你的会话，也可以在独立分窗里作为单独进程运行；它们共享任务清单（建任务、认领、更新状态）、互相通信，适合装不进一个上下文窗口、需要多路线长期并行推进的工作。选型口径：一次性的分身用 Subagent，需要「长期共事、共享进度」的多会话协作才上 Teams。
大白话：Subagent 就是雇个临时工——活给他、工具按需给、干完只要报告。报告要带证据，是因为你没法旁观他干活的全过程。
技术定义：子代理是拥有独立上下文窗口的 Agent 实例，由主对话经委派消息启动；初始上下文含自定义系统提示、任务简报、各级 CLAUDE.md 与 git 状态快照，但不含主对话历史。fork 是特例——它继承父对话的完整上下文与工具池，适合「把当前任务整个转交」而不是「从零外包」。
定义文件另支持 permissionMode/skills/isolation 等字段；并发在跑数默认上限 20、嵌套默认最深三层（分别由环境变量 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 与 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 调节）。结束的分身可以 resume 续聊——上下文还在，不用从头交底。
动手：一个只读的安全审计分身
建 .claude/agents/security-review.md（--- 之间是 frontmatter）：
---
name: security-review
description: 只读安全审计。Use proactively after auth or input handling changes.
tools: Read, Grep, Glob
---
你是安全审计员，只读不写。逐项检查指定文件：
1. 输入未校验直接拼接（注入风险）
2. 密钥或凭证硬编码
3. 权限校验缺失的端点
输出格式：每条发现 = 严重度 + 文件路径:行号 + 问题
一句话 + 建议修法；没有发现的方面也要逐项说明「已查，未见」。用三选一的方式派活：对话里说「让 security-review 审一下 auth 模块」；@ 引用选它；或整个会话用 --agent 固定身份。审计分身没有 Edit/Write——它物理上改不了代码，报告里每条发现都带路径行号，你复查一眼即可采信。输出格式那一行是关键：不带证据的报告，复核成本比自己做还高。
值得派与不值得派，一张表对齐（判据来自官方选型指引）：
| 派给子代理 | 留在主对话 |
|---|---|
| 高噪声输出：测试、日志、文档抓取 | 需要频繁来回打磨的迭代任务 |
| 自包含、可用一段摘要交付 | 多阶段共享上下文（设计到实现到验证） |
| 并行的独立调研（认证/数据库/API 各派一个） | 快速小改动、延迟敏感的操作 |
| 需要工具隔离的只读审计 | 对话里已有的问题追问（用 /btw——看得见上下文、无工具、不进历史的旁路提问） |
边界与取舍：分包不是万能的
协调成本是真实的税
每个分身从零攒上下文（读文件、理解约定都要重来），简单任务的开销可能超过收益；并行派的分身若各自交回详尽报告，主对话照样被撑大——官方文档明确提醒「多分身、详报告」的合并代价。经验法则：任务能一句话说清边界、结果能一段话交回，才值得派。
图：派活决策树——第一问「是」留主对话（快速小改同理）；第一问「否」进第二问，第二问「是」才派分身
「看不见该看的」是设计问题，不是机制缺陷
分身误判的根因通常是委派消息没带齐关键约定——修法是把验收标准前置进系统提示与输出格式：查什么、按什么标准、每条发现带什么证据。仍不放心就上验证链：审计分身报一条，再派一个验证分身逐条复核——嵌套机制就是为这种「复核再复核」准备的。
别把多代理当架构炫技
官方给主对话的保留场景（频繁交互、共享上下文、小改动）其实就是日常的大多数；从「一个能干的对话」开始，遇到高噪声、可并行、需隔离这三类信号再派分身——A2A 篇的判断框架在这里同样成立：管得着的用编排，真正的跨信任域协作才需要协议。
自测
合上文章先自己答，再展开对照：
哪类任务值得拆给 subagent，哪类反而增加协调成本？
值得派的三类：高噪声输出（跑测试、分析日志——噪声留在分身边，只回摘要）；自包含、能一段话交付的活；需要工具隔离的任务（只读审计，物理上改不了代码）。另外相互独立的并行调研也适合各派一个。不值得派（留主对话）的：需要频繁来回打磨的迭代、多阶段共享上下文的连续工作、快速小改动、延迟敏感的操作——分身从零攒上下文的时间可能超过收益，并行分身各自交回详尽报告还会撑大主对话。判据一句话：边界一句话说得清、结果一段话交得回，才派。
子代理「看不见该看的」导致误判——怎么设计输出格式让它带证据回来？
分身看不到主对话历史，误判的根因多是委派没带齐约定，所以要两头设计。入口端：把角色、范围、验收标准写进子代理的系统提示（正文），委派消息里把任务边界说清。出口端：系统提示里硬性规定输出格式——每条发现必须带严重度、文件路径:行号、可复查的引用与建议修法，没有发现的方面也要逐项说「已查，未见」；再配只读工具白名单保证它改不了代码，报告可放心采信。机制上官方还会扫描每份报告，把模仿系统标签的注入文本降级打标——但扫描不是豁免，证据格式才是你的复核抓手。
参考与延伸
- Claude Code 官方文档《Sub-agents》：作用域与优先级、frontmatter 字段、前后台行为、输出扫描与嵌套深度的原始出处 — code.claude.com/docs/en/sub-agents
下一站：Plugins 与开放生态——技能、代理、钩子打包分发：把个人手艺变成团队资产。