Claude Code Dynamic Workflow 实操指南

1它到底是什么

Dynamic workflow 是一段 Claude 编写、运行时在后台执行的 JavaScript 脚本,用来确定性地编排大量子代理(subagent)。

心智模型:它是"编排层",不是"又一个 agent"

普通对话里,主 Claude 自己一步步做事;复杂时它可以用 Agent 工具派几个子 agent。但当任务需要对几十上百个条目做同样的多阶段处理,靠主 Claude 即兴调度既慢又容易漏。Dynamic workflow 把"调度逻辑"固化成代码:你想象成一个 map/reduce 框架,只不过每个 worker 是一个完整的 Claude。

2什么场景该用 / 不该用

官方给 workflow 的定位是三类价值:要全面(分解后并行覆盖)、要可信(独立视角 + 对抗式核查后再下结论)、要扛规模(单个上下文装不下的迁移、审计、大范围扫描)。对照这三点判断:

判断口诀

"我是不是要对一批东西做同一套多步处理,或者需要多个独立视角核对才放心?" —— 是 → workflow;否 → 直接做或派几个普通 Agent。

3能做什么(四种核心能力)

4怎么用

方式 A:直接跑内置 workflow(最快上手)

最快看到效果的方式——你刚刚已经用过了:

/deep-research 调研一下 XXX

它在后台执行,结束返回带引用的报告。用 /workflows 看实时进度。

方式 B:让 Claude 给某个任务现写一个 workflow

两种触发:

• 在 prompt 里带关键词 ultracode,或用自然语言明确说"use a workflow / 用工作流 / fan out agents / 用多 agent 编排"。
• 设 /effort ultracode,之后 Claude 会对每个实质任务默认规划并运行 workflow(适合一整段重型会话)。

方式 C:理解脚本骨架(知其所以然)

每个脚本必须以 export const meta = {...} 开头(纯字面量,不能有变量/函数调用),然后是脚本体。最小骨架:

export const meta = {
  name: 'find-flaky-tests',
  description: 'Find flaky tests and propose fixes',  // 权限弹窗里显示这一行
  phases: [
    { title: 'Scan', detail: 'grep test logs for retries' },
    { title: 'Fix',  detail: 'one agent per flaky test' },
  ],
}
// —— 脚本体从这里开始 ——
phase('Scan')
const flaky = await agent('grep CI logs for retry markers', { schema: FLAKY_SCHEMA })

phase('Fix')
await parallel(flaky.tests.map(t => () =>
  agent(`Fix flaky test: ${t.name}`, { schema: FIX_SCHEMA })))

5脚本 API 速查

脚本语言限制(踩坑预防)

• 是 纯 JavaScript,不是 TypeScript——类型标注(: string[])、interface、泛型都会解析失败。
• Date.now() / Math.random() / 无参 new Date() 会抛错(它们会破坏 resume)。需要时间戳就从 args 传入;需要随机就用条目下标 index 区分。
• 没有文件系统 / Node API 访问;但能通过 ToolSearch 用所有会话连接的 MCP 工具。

6四个具体例子 case

以下脚本均为标准 workflow 写法示例,可直接交给 Claude 让它据此现写并运行。结合了你 CLAUDE.md / memory 里出现过的真实场景。

这是官方的"金标准"多阶段模式:按维度审查(pipeline),每个发现一出来就立刻派独立 skeptic 去验证(无需等其他维度审完)。

export const meta = {
  name: 'review-changes',
  description: 'Review changed files across dimensions, verify each finding',
  phases: [{ title: 'Review' }, { title: 'Verify' }],
}
const DIMENSIONS = [
  { key: 'bugs', prompt: '审查 diff 里的正确性 bug' },
  { key: 'perf', prompt: '审查 diff 里的性能问题' },
  { key: 'sec',  prompt: '审查 diff 里的安全问题' },
]
const results = await pipeline(
  DIMENSIONS,
  d => agent(d.prompt, { label: `review:${d.key}`, phase: 'Review', schema: FINDINGS_SCHEMA }),
  review => parallel(review.findings.map(f => () =>
    agent(`对抗式验证这条发现是否真实:${f.title}`, { phase: 'Verify', schema: VERDICT_SCHEMA })
      .then(v => ({ ...f, verdict: v }))))
)
const confirmed = results.flat().filter(Boolean).filter(f => f.verdict?.isReal)
return { confirmed }

这种"维度 bugs 的发现在验证时,维度 perf 还在审查"的交错,正是 pipeline 省墙钟时间的地方。你日常其实有现成的 /code-review ultra 走的就是云端多 agent 审查。

分解问题 → 并行多角度搜索 → 抓取去重 → 每条声明 3 票对抗验证(2/3 反驳才枪毙)→ 引用合成。循环到收敛的模式骨架:

// 循环到"连续 2 轮没有新发现"——处理未知规模的搜索
const seen = new Set(), confirmed = []
let dry = 0
while (dry < 2) {
  const found = (await parallel(FINDERS.map(f => () =>
    agent(f.prompt, { phase: 'Find', schema: ITEMS }))))
    .filter(Boolean).flatMap(r => r.items)
  const fresh = found.filter(b => !seen.has(key(b)))   // 对 seen 去重,纯代码不用 agent
  if (!fresh.length) { dry++; continue }
  dry = 0; fresh.forEach(b => seen.add(key(b)))
  // …对 fresh 做多视角验证,通过的进 confirmed…
}

适合"解空间很宽"的内容/方案任务:从不同角度生成 N 个独立草稿,并行打分,从赢家合成、同时嫁接亚军的好点子。比"一稿改到死"更好。可直接套用在你的 /doc-writer / /proposal-maker 这类产出上。

export const meta = {
  name: 'draft-panel',
  description: 'Generate N drafts from different angles, judge, synthesize winner',
  phases: [{ title: 'Draft' }, { title: 'Judge' }, { title: 'Synthesize' }],
}
const ANGLES = ['MVP 优先', '风险优先', '用户体验优先']
phase('Draft')
const drafts = await parallel(ANGLES.map((a, i) => () =>
  agent(`以「${a}」的角度写一版方案草稿(变体 ${i})`, { schema: DRAFT })))
phase('Judge')
const scores = await parallel(drafts.filter(Boolean).map(d => () =>
  agent(`给这版草稿打分并说明优缺点:${d.summary}`, { schema: SCORE })))
phase('Synthesize')
return await agent('以最高分草稿为主体,嫁接其他草稿的最佳点子,合成终稿', { schema: FINAL })

结合你 memory 里的真实项目。比如:你的 ~/.config/agents/ 是 canonical 源,软链到多个 agent 入口。要审计每个 agent 入口是否和 canonical 一致 + 软链是否健康,这正好是"对一批条目做同套检查"的扇出场景:

export const meta = {
  name: 'audit-agent-sync',
  description: '审计每个 agent 入口与 canonical 配置的一致性',
  phases: [{ title: 'Discover' }, { title: 'Audit' }],
}
phase('Discover')
// 先在主 Claude 侧 scout 出 manifest 里的 agent 列表,作为 args 传入(发现工作清单)
const targets = args.agents   // 例:['claude-code','codex','trae','gemini',...]

phase('Audit')
const reports = await parallel(targets.map(name => () =>
  agent(`检查 agent「${name}」的入口软链是否指向 ~/.config/agents 下的 canonical 文件,
列出:断链 / 内容漂移 / 缺失的 rule。只报问题,无问题返回空列表。`,
    { label: `audit:${name}`, schema: AUDIT_SCHEMA })))
const problems = reports.filter(Boolean).flatMap(r => r.issues)
log(`审计完成,发现 ${problems.length} 处问题`)
return { problems }

7使用注意事项(踩坑清单)

8给你的下一步

权威来源:① Claude Code 官方文档 code.claude.com/docs/en/workflows(dynamic workflow 定义、触发方式、版本要求);② Workflow 工具规范(脚本 API、pipeline/parallel 语义、并发与 agent 上限、JS 限制、resume 机制、质量模式)。本指南所有技术主张均来自上述一手来源,例子脚本为标准写法演绎。