D12 · Agent teams 与 dynamic workflows

本课把多 agent 协作的两条高阶路线讲清楚:agent team 是什么、和 subagent 差在哪、怎么启动;dynamic workflow 怎么用脚本确定性编排大规模 subagent;以及最重要的——什么时候值得上编排,什么时候单会话反而最省。

为什么这天学这个

D10 的 subagents 解决了「在一个会话里派活」:worker 各有独立上下文,但只能把结果汇报给主 agent,互相之间不说话。D11 的 worktrees 解决了「手动开多个并行会话」:物理隔离,但要你自己当协调人。这留下两个空白:一是 worker 之间无法讨论、无法互相挑战对方的结论;二是「先干什么再干什么」的编排逻辑只存在于 Claude 当时的上下文里,换个会话就没了,不可复现。

本站观点D12 的两个机制正好补上这两个空白:agent teams 让多个完整会话共享任务列表、互发消息;workflows 把编排本身写成一段可读、可存、可重跑的脚本。学完本课,你手里就有了从「单会话」到「上百 agent」的完整工具谱系。D13(Headless 与 CI)会用到这里的结论:workflows 在 claude -p 和 Agent SDK 里同样能跑,是自动化流水线的地基;保存下来的 workflow 还能打进 plugin 分发,这是 D14 的内容。

概念讲清楚

Agent team:一队会互相说话的完整会话

官方Agent team 是多个 Claude Code 实例协同工作:你的主会话充当 team lead,负责协调、分派任务、汇总结果;每个 teammate 都是一个完整独立的 Claude Code 会话,有自己的上下文窗口,并且可以直接给其他队友发消息——你也可以绕过 lead 直接找某个队友对话。一个团队由四个部件组成:team lead(协调)、teammates(干活)、共享任务列表(认领工作)、mailbox(agent 间通信,每个 agent 一个 JSON 收件箱文件)。

实验性功能官方Agent teams 目前是实验特性,默认关闭。需在 settings.json 或环境变量里设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 才会启用;官方明确列出了它在会话恢复(/resume 不恢复 in-process 队友)、任务状态同步、关闭速度等方面的已知限制。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

官方启动不需要任何仪式:开启开关后,用自然语言描述任务和你想要的队友,Claude 会生成队友、填充共享任务列表并开始协调(v2.1.178 起不再需要先「建团队」的步骤,旧的 TeamCreate/TeamDelete 工具已移除)。Claude 判断任务适合并行时也可能主动提议组队,但都要你确认才会生成。几个值得记住的机制点:

任务列表:任务有 pending / in progress / completed 三种状态,可声明依赖;认领用文件锁防止两个队友抢同一个任务。lead 可以点名分派,队友也可以干完自取下一个。
复用角色:生成队友时可以直接引用 D10 定义过的 subagent 类型(如 security-reviewer),队友会遵守该定义的 tools 白名单和 model;定义正文会追加进队友的系统提示。
权限:队友继承 lead 的权限设置,权限确认会冒泡到 lead 会话由你亲自批;一个队友不能替你授权,也不能把被拒的操作转手让另一个队友绕过检查。
质量门:配合 D8 的 hooks,TeammateIdle / TaskCreated / TaskCompleted 三个钩子以退出码 2 拦截,可以在队友想收工时把它打回去继续干。
展示模式:默认 in-process(所有队友在同一终端,方向键选人、Enter 进对话);想一屏看到所有人可用 split panes(需 tmux 或 iTerm2),用 teammateMode 设置切换。

与 subagent 的区别:要不要互相讨论

官方两者都能并行干活,分野在于 worker 之间需不需要沟通:

	Subagents(D10)	Agent teams(本课)
上下文	独立上下文,结果返回给调用方	独立上下文,完全自主
通信	只向主 agent 汇报	队友之间直接互发消息
协调	主 agent 管理全部工作	共享任务列表,自行认领
适合	只关心结果的聚焦任务	需要讨论与协作的复杂工作
Token 成本	较低:结果压缩后回主上下文	较高:每个队友都是独立实例

官方官方给出的强场景:并行代码评审(安全 / 性能 / 测试覆盖各派一人)、竞争性假设排查(几个队友各持一个 bug 假设,互相辩论试图推翻对方,活下来的理论更可能是真正根因)、跨层协作(前端 / 后端 / 测试各占一摊)。反过来,顺序型任务、要改同一批文件、依赖链很长的工作,单会话或 subagents 更划算。

Dynamic workflow:把编排从上下文挪进代码

官方Dynamic workflow 是一段编排 subagents 的 JavaScript 脚本:你描述任务,Claude 替你把脚本写出来,一个独立于会话的 runtime 在后台执行它。关键设计是中间结果存在脚本变量里,而不进 Claude 的上下文窗口——会话只收到最终答案。谁持有计划也变了:subagents、skills、agent teams 都是 Claude 逐轮决定下一步,workflow 则是脚本持有循环、分支和中间结果,因此同一套编排可以原样重跑。需要 Claude Code v2.1.154+,付费计划可用;Pro 用户在 /config 里打开 Dynamic workflows 一行。

官方启动方式有三种:

在提示里要:写关键字 ultracode,或直接用自然语言说「用 workflow 做」,Claude 就为这个任务写脚本而不是逐轮干。
让 Claude 自己决定:/effort ultracode(xhigh 推理 + 自动编排),之后每个实质任务 Claude 都会规划成 workflow,token 消耗显著增加,仅当前会话有效。
跑现成命令:内置的 /deep-research(多角度搜索、交叉核验、产出带引用的报告),或你自己保存过的 workflow 命令。

官方保存下来的脚本长这样(meta 块 + 顶层 await 的脚本体):

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: { type: 'object', required: ['files'],
    properties: { files: { type: 'array', items: { type: 'string' } } } },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

官方agent() 起一个 subagent(可传 schema 拿结构化结果、label 给进度视图起名),pipeline() 对列表里每一项各跑一个 agent。被你中途停掉或撞上不可恢复 API 错误的 agent() 调用会解析成 null,pipeline() 会把 null 留在结果数组里,所以示例末尾用 .filter(Boolean) 清掉。文档示例只给出这两个原语;完整选项官方指向 Agent SDK 参考里的 Workflow tool 条目。运行进度在 /workflows 视图里按 phase(阶段)展示:每个阶段的 agent 数、token 总量、耗时,可以一路钻到单个 agent 的 prompt 和结果。

典型 workflow 流水线:发现 → 扇出 → 验证 → 汇总。中间各阶段的结果都留在脚本变量里,只有最终报告回到会话上下文。对抗验证这一步是 workflow 独有的可复用质量模式:让独立 agent 复核彼此的发现再上报。

官方运行时的硬约束:最多 16 个并发 agent(CPU 核少的机器更少)、单次运行上限 1000 个 agent、运行中不接受用户输入(阶段之间要人签字就拆成多个 workflow)、脚本本身不能直接碰文件系统和 shell——读写和命令都由 agent 执行,脚本只负责协调。权限上,workflow 生成的 subagent 一律跑在 acceptEdits 模式并继承你的工具白名单,不在白名单里的 shell 命令、web 抓取仍会中途弹确认,长任务开跑前先把要用的命令加进白名单。停掉的运行可在同一会话内恢复:已完成的 agent 通常直接回放缓存结果——扇出成许多小 agent 的脚本,比一个长 agent 保留的进度多得多。

官方跑出满意结果后,在 /workflows 里选中该次运行按 s 保存:存到项目的 .claude/workflows/(随仓库共享)或 ~/.claude/workflows/(仅自己、全项目可用),之后它就是一条 /<name> 命令,还能通过 args 接收调用时传入的参数(脚本里以全局变量 args 读取)。要跨团队分发,放进 plugin 的 workflows/ 目录,以 /插件名:workflow名 调用。

四种机制怎么选:看谁持有计划

官方官方给了一张总对照表,核心轴是「谁决定下一步」和「中间结果放哪」:

	Subagents	Skills	Agent teams	Workflows
它是什么	Claude 派出的 worker	Claude 遵循的指令	lead 督导的平级会话	runtime 执行的脚本
谁定下一步	Claude,逐轮	Claude,按提示	lead agent,逐轮	脚本
中间结果在哪	Claude 上下文	Claude 上下文	共享任务列表	脚本变量
可复用的是	worker 定义	指令本身	团队定义	编排本身
规模	每轮几个	同 subagents	几个长期运行的平级	单次几十到几百个
被打断时	整轮重来	整轮重来	队友继续跑	同会话内可恢复

本站观点一句话选型:只要结果、不要过程 → subagent;worker 之间要讨论、要互相挑战 → agent team;规模大、步骤确定、以后还要再跑 → workflow;要沉淀的是「方法」而不是「编排」→ skill(D7)。

成本意识:什么时候值得上编排

官方两种机制都比单会话贵得多,官方给了明确护栏。Agent team:token 消耗随队友数线性增长,3–5 个队友起步,每人 5–6 个任务最饱和;三个专注的队友常胜过五个散乱的;新手先从「不写代码」的调研、评审类任务开始;两个队友改同一个文件会互相覆盖,拆分时按文件划清边界。Workflow:先在小切片上试跑估算花费(一个目录而不是整个仓库);单次运行排到 25 个 agent 以上、或预计 token 超过 150 万时,任务面板会亮 Large workflow 警告(v2.1.203+,仅提示不拦截);/config 里的 size guideline 控制 Claude 写脚本时瞄准的 agent 规模,默认 medium(15 个以内,v2.1.219+);每个 agent 默认用会话当前模型,可让脚本给不吃算力的阶段路由更小的模型,或用 CLAUDE_CODE_SUBAGENT_MODEL 全局覆盖——大规模跑之前先看一眼 /model。

实战引导本站观点「一次性改 200 个文件」正是 workflow 扇出的主场:发现 → 每文件一个 agent 隔离改 → 逐个验证 → 汇总。具体拆法和防翻车细节见 Tip B3:批量修改 200 个文件。

当天能做完的实操

前置检查:claude --version 需 ≥ 2.1.154(今日最新为 2.1.222);Pro 计划先在 /config 打开 Dynamic workflows。以下 1–3 步约 30 分钟,第 4 步可选。

体验内置 workflow。在会话里跑 /deep-research 提一个你真想知道答案的问题,例如下面这条。预期:Claude Code 弹出是否允许 workflow 的确认,选 Yes 后运行转入后台,输入框下方任务面板出现一行进度摘要。
```
/deep-research Node.js 的 permission model 从 v20 到 v22 有哪些变化?
```
钻进进度视图。跑 /workflows,方向键选中这次运行按 Enter。预期:看到按 phase 分组的视图,每个阶段有 agent 数、token 总量、耗时;继续 Enter 可钻到单个 agent,读到它的 prompt、最近的工具调用和结果。结束后一份带引用的报告落回会话,没通过交叉核验的结论已被过滤。
写并保存你自己的 workflow。挑一个小目录(成本意识:先小切片),用自然语言要一个带对抗验证的审计 workflow。预期:审批提示列出计划的阶段,可选 View raw script(或 Ctrl+G 在编辑器打开)先读脚本再放行;跑完在 /workflows 里按 s 保存,Tab 切换项目 / 个人位置,之后它就是你的一条斜杠命令。
```
用 workflow 审计 src/routes/ 下的每个路由文件是否缺少鉴权检查,
每条发现在报告前先由独立 agent 做对抗验证,最后汇总成一份按严重度排序的清单。
```
(可选)拉起你的第一个 agent team。在 settings.json 的 env 里加 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1,重启会话后发下面的 prompt。预期:输入框下方的 agent 面板出现三个队友,方向键选人、Enter 进它的会话直接对话;干完后让 lead 汇总三份评审意见。注意:面板里出现 agent 不等于组了队(subagents 也在同一面板),如果 Claude 用了 subagents,明确再要一次 agent team。
```
生成三个队友并行评审这个 PR:
- 一个只看安全隐患
- 一个只看性能影响
- 一个只看测试覆盖
让他们各自评审后向你汇报,你再汇总成一份意见。
```

验收标准

能不看笔记说清 subagent、agent team、workflow 三者在「谁决定下一步」和「中间结果放在哪」上的差别,并各举一个适用场景。
跑通过一次 /deep-research,并在 /workflows 视图里钻到过某个 agent 的 prompt 与结果。
用自然语言让 Claude 写过一个 workflow,读过它生成的脚本(认得 meta / agent() / pipeline() / .filter(Boolean) 各自在干什么),并保存成了自己的斜杠命令。
能说出两条成本护栏:Large workflow 警告的触发阈值,以及 size guideline 的默认档位。
自测题:要把 200 个组件文件从 styled-components 迁到 Tailwind,选哪种机制?为什么不是 agent team?(参考答案:选 workflow——文件互相独立、不需要 worker 之间讨论,pipeline() 扇出天然匹配,且编排可保存重跑、中断可恢复;agent team 的价值在队友互相沟通与挑战,这里用不上,只会白付协调开销和更高的 token 成本。)