Claude Code 动态工作流(Dynamic Workflows)怎么用

01概览与速读

只有三分钟,看这一节就够。

一句话:Dynamic Workflow 是 Claude 为你的任务现写、后台执行的 JavaScript 编排脚本,它在脚本里并行调度几十到上千个 subagent,彼此可以交叉验证,最后只把结论回灌到你的主会话。它专为单个上下文窗口装不下、或需要并行 + 验证的大任务而生:代码库级审计、大规模迁移、需交叉核对的研究。

三种"工作流"别混淆

来源:code.claude.com/docs/en/workflows · common-workflows

关键事实速查(均已交叉验证)

02它到底是什么

核心思想:把"计划"从对话搬进代码。

普通模式下,Claude 在自己的上下文里一步步推理执行——计划、循环、分支、中间结果全都占用 token,任务越长上下文越脏、越容易退化。Dynamic Workflow 把这套控制流(循环 / 条件 / 扇出)和中间数据搬进一段 JS 脚本,由独立 runtime 执行;主会话的上下文只保留最终答案。这就是它能突破单上下文窗口、扩展到上千 subagent 的根本原因。

与其他执行方式的区别

来源:官方文档 "When to use a workflow" 表

一句话:subagent / skill 里 Claude 是编排者,逐回合决定派谁、每个结果都落进它的上下文;workflow 把循环、分支、中间结果都搬进脚本,Claude 的上下文只剩最终答案。这也让 workflow 能施加可复用的质量套路(对抗互审、多角度起草择优),而不只是"多派几个 agent"。Agent Teams 是另一条实验性、默认关闭的多实例编排路线,仅作对比。

03执行模型

从你敲下 prompt 到结果回灌,中间发生了什么。

• 隔离执行:runtime 在与对话隔离的环境里跑脚本,中间结果留在脚本变量里,不进 Claude 上下文。
• 异步后台:启动后立即返回一个任务 id,workflow 在后台跑,主会话仍可交互;完成时通知你。
• 并发受控:同时最多 16 个 subagent,多出的排队等空位;整个生命周期总量上限 1000。
• 上下文干净:中间推理默认不回到主会话(除非脚本用 log() 输出),因此长任务不会撑爆上下文。
• 可交叉验证:脚本可以让独立 subagent 互相审查彼此结论后再上报,或从多个角度起草方案再择优。

来源:官方文档 · 官方博客;并发 min(16, 核数−2) 来自运行时规范

04如何触发与上手

三种触发方式;最快是先跑内置的 /deep-research。

三种触发方式

1. prompt 里带 workflow 一词 —— 不改会话 effort,只把单个任务跑成 workflow。Claude Code 会高亮这个词并写脚本而非逐回合处理。(误触发?按 alt+w 本次忽略高亮)
   例:Run a workflow to audit every API endpoint under src/routes/ for missing auth checks
2. /effort ultracode —— xhigh 推理 + 自动编排:Claude 对会话里每个实质任务都自行决定是否起 workflow(一个请求可能连起好几个:先理解代码、再改、再验证)。仅当前会话有效,新会话重置;用 /effort high 退回。只在支持 xhigh 的模型上可用。
3. 跑已有的 workflow 命令 —— 内置的 /deep-research,或你保存过的 /<名字>。

运行前的审批

CLI 里每次运行会弹出计划好的阶段和这些选项:

• Yes, run it —— 开跑
• Yes, and don't ask again for <name> in <path> —— 开跑,且本项目此 workflow 以后不再问
• View raw script —— 先看脚本再决定(Ctrl+G 在编辑器打开;Tab 可在开跑前调整 prompt)
• No —— 取消

是否弹审批取决于权限模式:默认 / acceptEdits 每次都问(除非选了"不再问");Auto 仅首次、ultracode 开启时跳过;Bypass / claude -p / Agent SDK 从不问,直接开跑。桌面 App 是一张含名称、阶段列表、用量警示的审批卡(Once / Always / Deny)。

保存复用

某次运行达到你要的效果后,/workflows 选中它、按 s 保存为命令。保存位置 Tab 切换:.claude/workflows/(项目级,随仓库共享)或 ~/.claude/workflows/(个人级,所有项目可见、仅自己可见)。之后即可作为 /<名字> 复用;同名时项目级优先。

来源:官方文档(Run a bundled workflow / Have Claude write a workflow / Approve the plan / Save for reuse)

05监控 · 成本 · 控制

能起上千 agent 的功能,成本与可控性是第一位。

用 /workflows 看与控

运行在后台,随时 /workflows 列出运行中与已完成的 workflow,方向键选中、Enter 进入进度视图——每个阶段显示 agent 数、token 总量、耗时;还能钻进某个 agent 看它的 prompt、最近工具调用与结果。输入框下方的任务面板也有一行进度摘要。

控成本:盯住模型

• workflow 里每个 agent 默认用你会话的模型,除非脚本把某阶段路由到别的模型。
• 大运行前先 /model 确认(尤其你平时会切到小模型做日常活时)。
• 描述任务时,可让 Claude 把不需要最强模型的阶段换成小模型。

关掉 workflow

不想用时三选一:/config 里关掉 Dynamic workflows;或 ~/.claude/settings.json 设 "disableWorkflows": true;或环境变量 CLAUDE_CODE_DISABLE_WORKFLOWS=1。组织级可用 managed settings。关闭后:bundled 命令不可用、workflow 词不再触发、ultracode 从 /effort 菜单移除。

来源:官方文档(Watch the run / Cost / Turn workflows off)

06限制与可用性

硬性数字与运行时约束,逐条可追溯。

可用性

研究预览(research preview),需 Claude Code v2.1.154+。可用于:所有付费方案(Pro / Max / Team / Enterprise) + Anthropic API + Amazon Bedrock + Google Cloud Vertex AI + Microsoft Foundry。Pro 上需在 /config 的 "Dynamic workflows" 行手动开启。可用界面:CLI、桌面 App、IDE 扩展、claude -p 无头模式、Agent SDK。

运行时约束(官方 "Behavior and limits" 表)

来源:官方文档 Behavior and limits / Note(并发"实际取 min(16, 核数−2)"为运行时规范补充)

续跑(resume)

停止后可续跑:已完成的 agent 返回缓存结果,其余实时跑。从 /workflows 选中按 p 恢复,或让 Claude 用同一脚本重新启动。续跑仅限同一 Claude Code 会话——运行中退出 Claude Code,下次会话会从头跑。

07脚本 API 参考

给想看懂 / 自己写脚本的人。

脚本骨架:meta 块 + 编排原语

export const meta = {
  name: 'find-flaky-tests',
  description: 'Find flaky tests and propose fixes',  // 必填,会显示在权限弹窗
  phases: [                                            // 每个 phase() 一项
    { title: 'Scan', detail: 'grep test logs for retries' },
    { title: 'Fix',  detail: 'one agent per flaky test' },
  ],
}
// meta 必须是纯字面量:不能有变量/函数调用/展开/模板插值

phase('Scan')
const flaky = await agent('grep CI logs for retry markers', { schema: FLAKY_SCHEMA })

phase('Fix')
const fixes = await parallel(flaky.tests.map(t => () =>
  agent(`Propose a fix for flaky test ${t.name}`, { schema: FIX_SCHEMA })
))
return { fixes }

核心原语

const bugs = []
while (budget.total && budget.remaining() > 50_000) {
  const r = await agent('Find bugs in this codebase.', { schema: BUGS })
  bugs.push(...r.bugs)
  log(`${bugs.length} found, ${Math.round(budget.remaining()/1000)}k left`)
}

来源:Claude Code 运行时规范(第一手);概念框架见 官方文档

08pipeline vs parallel:最该想清楚的取舍

默认用 pipeline;只有真正需要"所有结果一起"时才用 parallel 屏障。

pipeline() 让每个 item 独立流过各阶段——item A 可以在阶段 3,而 item B 还在阶段 1。墙钟时间 = 最慢的单条链,而不是"每阶段最慢之和"。parallel() 是屏障:必须等齐上一阶段全部结果才进下一步,慢的拖累快的。

来源:Claude Code 运行时规范;模式定位见 官方文档

09编排模式(可搜索 / 可筛选)

这些是工具箱,按任务自由组合。输入关键词或点分类筛选。

最常用的组合:评审 → 验证(pipeline)

const results = await pipeline(
  DIMENSIONS,
  d => agent(d.prompt, { label: `review:${d.key}`, phase: 'Review', schema: FINDINGS }),
  review => parallel(review.findings.map(f => () =>
    agent(`Adversarially verify: ${f.title}`, { phase: 'Verify', schema: VERDICT })
      .then(v => ({ ...f, verdict: v }))))
)
const confirmed = results.flat().filter(Boolean).filter(f => f.verdict?.isReal)
// 维度'bugs'的发现在验证时,维度'perf'还在评审 —— 不浪费墙钟

来源:Claude Code 运行时规范;对抗验证 / 多角度起草见 官方博客

10何时用 / 何时别用

这不是默认工具——刻意使用。

来源:Shipyard · MarkTechPost · 官方文档

11真实案例

旗舰证据点 + 早期用法。

其它被点名的用途

• 代码库级 bug 猎取 —— 全仓并行找 bug。
• profiler 引导的性能优化审计 —— 按性能画像批量定位优化点。
• 安全审计 —— 多维并行发现 + 交叉验证。
• 大规模迁移 / 交叉核对研究 —— 官方框定的典型场景。

来源:官方博客 · The New Stack

12完整实战示例

最有说服力的例子——本报告就是用下面这个 workflow 生成的。

我用一个动态工作流来调研动态工作流本身:研究阶段并行派 7 个域 agent 抓官方文档/博客/发布说明并各返回结构化发现;验证阶段对 6 条载重事实做多源交叉核对。1 分 38 秒返回,6 条事实全部 confirmed。下面是该脚本的忠实精简版:

export const meta = {
  name: 'research-dynamic-workflows',
  description: 'Deep research on Claude Code Dynamic Workflows',
  phases: [
    { title: 'Research', detail: '7 parallel domain agents fetch official docs/blog' },
    { title: 'Verify',   detail: 'cross-source check of load-bearing facts' },
  ],
}

// 每个 agent 用 schema 强制返回 {topic, summary, facts[{claim,detail,sources}], ...}
phase('Research')
const research = await parallel(TOPICS.map(t => () =>
  agent(t.prompt, { label: `research:${t.key}`, phase: 'Research', schema: RESEARCH_SCHEMA })
))

phase('Verify')
const verifications = await parallel(CLAIMS.map(c => () =>
  agent(`独立核对这条事实(≥2 个可信来源): "${c.text}"。confirmed/contradicted/unclear`,
    { label: `verify:${c.key}`, phase: 'Verify', schema: VERIFY_SCHEMA })
))

return { research: research.filter(Boolean), verifications: verifications.filter(Boolean) }

13注意事项与小结

使用时记住

• 研究预览:限制与行为可能变化;需 v2.1.154+,Pro 还要在 /config 开启。
• 成本敏感:一次能起上千 agent,计入用量与速率限制;大运行前看 /model,跑偏就 /workflows 停(不丢已完成工作)。
• 编排不碰 I/O:脚本本身无文件系统 / shell 权限、不接受运行中输入(只有 agent 权限弹窗能暂停);需阶段间人工签字就拆成多个 workflow。
• 默认 pipeline:屏障(parallel)只在真要全集时用,否则白白浪费墙钟。
• 验证再上报:对抗 / 多视角验证能显著降低"看似对实则错";去重要对"所有见过的"去重,否则循环不收敛。
• 可复现约束:脚本是纯 JS;Date.now() / Math.random() 不可用(为支持续跑);续跑仅限同一会话。
• 不是默认工具:约 95% 任务不需要它——刻意用在大审计 / 大迁移 / 交叉验证研究上。

14来源

所有断言可追溯到下列来源;API 精确签名另注为"运行时规范(第一手)"。

官方

• docscode.claude.com/docs/en/workflows — Orchestrate subagents at scale with dynamic workflows(权威文档)
• blogclaude.com/blog/introducing-dynamic-workflows-in-claude-code — 官方发布博客(含 Bun 案例、对抗验证)
• newsanthropic.com/news/claude-opus-4-8 — Opus 4.8 发布说明
• docscode.claude.com/docs/en/common-workflows — Common workflows(prompt 配方,区别于本功能)

媒体 / 第三方(用于交叉验证)

• mediaTechCrunch — Opus 4.8 + dynamic workflow 工具(并发/总量上限)
• mediaMarkTechPost — 版本要求 v2.1.154、16/1000 上限、可用范围
• mediaThe New Stack — 发布综述(转述 Bun 案例数字)
• guideAgentpedia — 第三方分步上手指南(触发示例)
• guideShipyard — 多 agent 编排取舍("95% 任务不需要")