9.9 KiB
created, type, tags, source
| created | type | tags | source | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 2026-06-18 | resource |
|
https://code.claude.com/docs/en/workflows |
Claude Code Dynamic Workflows 最佳实践与实例
Dynamic workflow = Claude 自己写、运行时后台执行、你可读可重跑的一段 JS 脚本,用来编排几十到几百个并行子 agent。需 Claude Code v2.1.154+,付费计划/API/Bedrock/Vertex/Foundry 可用,Pro 在
/config打开。上层选型见 Claude Code 官方多Agent编排最佳实践 (2026);ECC 自建编排见 ECC orch- 编排家族与 v2.0 团队编排、ECC 编排实战手册。
一、何时用(vs subagents / agent teams)
核心区别:计划掌握在谁手里。Workflow 把计划搬进代码,中间结果留在脚本变量里,Claude 上下文只拿最终答案。
只在这两种情况用:
- 一个会话协调不过来:几十~几百 agent 的全库审计、500+ 文件迁移、广度研究。
- 想把编排固化成可复用、可重跑的资产:每个分支都跑的同一套审查/研究。
不值得用:一两轮能做完的、紧耦合顺序任务、单文件改动。
Workflow 的真正价值不是"多跑几个 agent",而是能施加可重复的质量模式——独立 agent 对抗式互审、多角度起草再权衡,比单遍更可信。
二、编程模型:三个原语 + meta
每个脚本必须以 export const meta 开头(纯字面量,不能有变量/函数/插值),phase 标题要和 phase() 调用一致。
export const meta = {
name: 'vue-newsletter',
description: 'Research Vue/Nuxt ecosystem sources in parallel for a given week',
phases: [
{ title: 'Research', detail: 'one agent per source' },
{ title: 'Curate', detail: 'dedupe + rank items by impact' },
{ title: 'Write', detail: 'synthesize the final newsletter' },
],
}
| 原语 | 语义 | 何时用 |
|---|---|---|
agent(prompt, opts?) |
起一个子 agent;给 schema 则强制结构化输出(工具层校验+重试,直接返回已验证对象) |
单个委派 |
pipeline(items, s1, s2…) |
每个 item 独立穿过所有 stage,stage 间无屏障 | 多 stage 默认 |
parallel(thunks) |
屏障:等齐所有结果;失败项变 null 不 reject |
仅当 stage N 需要 N-1 全部结果 |
workflow(name, args?) |
内联调另一个 workflow | 组合复用 |
agent 关键 opts:schema(强制 JSON)、phase(进度分组)、label(显示名)、model/effort(成本路由)、isolation:'worktree'(并行写文件防冲突,贵,仅必要时)。
黄金规则:默认 pipeline(),屏障只在真需要时用。 嗅探:若写成 parallel → 普通 map/filter/flatten → parallel,中间那步不需要屏障,改成 pipeline 内的一个 stage。pipeline 墙钟 = 最慢单条链,不是各 stage 最慢之和。
三、实例(真实脚本结构)
例 1:Vue 新闻信 —— fan-out → reduce → synthesize(经典三段式)
Phase 1 并行扇出(9 个源各一个 agent,schema 强制结构化):
const raw = await parallel(
SOURCES.map((s) => () =>
agent(s.prompt, { label: `research:${s.key}`, schema: ITEM_SCHEMA,
agentType: 'general-purpose' })
)
)
Phase 2 纯 JS 归约(去重/扁平不再起 agent):
const flatItems = collected.flatMap((c) =>
(c.items || []).map((it) => ({ ...it, source: c.source })))
Phase 3 顺序综合:
const curated = await agent(curatePrompt, { phase: 'Curate', schema: CURATED_SCHEMA })
const newsletter = await agent(writePrompt, { phase: 'Write' })
要点:归约用普通代码,不用 agent。扁平/去重/过滤这类无跨 item 依赖的操作放进 stage 里或纯 JS,别为它开屏障。
例 2:/deep-research(内置 workflow,5 阶段)
- Scope(1 agent):把问题拆成 5 个不同搜索角度
- Search(5 并行 agent):各自独立 web 搜索
- Fetch(顺序):URL 去重,抽 ~15 个源
- Verify(每条 claim 并行):三票制,怀疑者尝试证伪
- Synthesize(1 agent):只用存活的 claim 生成带引用报告
没survive 的 claim 永远进不了报告——这就是把质量门写进编排的范例。
例 3:Bun 移植(Zig→Rust,真实大规模)
Jarred Sumner 用 workflows 把 Bun 从 Zig 移植到 Rust:~75 万行、99.8% 测试通过、11 天合并。四阶段:
- Mapping:一个 workflow 为 Zig 里每个 struct 字段推断对应 Rust lifetime
- Translation:几百个并行 agent逐个
.zig→.rs,每文件配 2 个 reviewer - Fix loop:自动迭代 build+test 直到通过
- Optimization:通宵 workflow 消除多余拷贝,每项生成单独 PR 供人审
模式提炼:map(推断约束) → 并行翻译(每单元配双评审) → 自动修复循环 → 优化并拆成可审 PR。能力上限极高,但 token 成本对应也高。
四、质量模式(workflow 的精髓)
// 对抗式 / 多镜头验证:每个发现配不同视角的独立评判者(不是 N 个相同怀疑者)
const judged = await parallel(fresh.map((b) => () =>
parallel(['correctness', 'security', 'repro'].map((lens) => () =>
agent(`Judge "${b.desc}" via the ${lens} lens — real?`, { schema: VERDICT })
))
))
- 对抗式验证:每个发现 spawn N 个独立怀疑者,prompt 去证伪,多数证伪即杀——挡住"看似合理但错"的发现。
- 视角多样:一个发现能多种方式失败时,给每验证者不同镜头(正确性/安全/性能/能否复现),比冗余的相同怀疑者更能抓失败模式。
- 判官面板:多角度生成 N 方案 → 并行打分 → 从胜者综合 + 嫁接亚军亮点。
- loop-until-dry:未知数量的发现持续 spawn 直到连续 K 轮无新增。去重对
seen集合,不是对confirmed,否则被判官否掉的发现每轮重现、永不收敛。 - completeness critic:最后一个 agent 专问"还缺什么——没跑的模态/没验证的断言/没读的源",产出下一轮工作。
五、成本 / 资源 / 确定性
- 先小切片试跑:一个目录而非整库、一个窄问题而非宽问题,看
/workflows里每 agent 的 token 再全量。 - 硬上限:并发 ≤16 agent,单次 ≤1000 agent;脚本本身不能读写文件/跑 shell(由它编排的 agent 做)。
- 模型路由:每 agent 默认会话模型;机械 stage 显式降级
{model:'haiku', effort:'low'},只给最难的 verify/judge 升级。大跑前查/model。 - budget 驱动:
while (budget.total && budget.remaining() > 50_000) {…}或静态FLEET = floor(total/100k)。 - 资源约束:prompt 里让 agent 避开重资源命令,以便并行更多。
- 无声截断要
log():凡设了 top-N / 不重试 / 采样,都要 log,否则读起来像全覆盖。 - 确定性禁令:脚本内
Date.now()/Math.random()/ 无参new Date()都会 throw(为了 journaling 可恢复)。时间戳用args传入;要随机就按 index 变 prompt/label,不要真随机。
六、运维 / 协作
- 后台跑、会话不阻塞;
/workflows看分阶段进度,可暂停/停某 agent/重启。 - 同会话内可恢复:停了再起,已完成 agent 返回缓存结果;
resumeFromRunId对相同脚本 100% 命中。退出 Claude Code 则下次从头。 - 保存复用:满意的 run 按
s存成/<name>命令(项目.claude/workflows/或个人~/.claude/workflows/,同名项目优先)。 args传参:存好的 workflow 接收结构化args(研究问题/路径列表/配置),脚本直接当数组/对象用。- 审批:首跑展示 phase + token 警告;子 agent 一律
acceptEdits,但非白名单的 shell/web/MCP 仍会中途提示——长跑前先加白名单。 - 没有中途人工输入:要分阶段签字,把每个 stage 拆成独立 workflow。
- 触发:prompt 含
ultracode关键词跑单次;/effort ultracode让整会话每个实质任务都自动编排成 workflow。
七、Use case 目录(官方/社区)
- 全库 bug 扫描 + 独立验证发现
- 安全审计 / 加固(认证检查、输入校验)、profiler 引导的优化审计、死代码识别(Klarna 实践)
- 大规模现代化:框架替换、API 弃用迁移、语言移植(数千文件)
- 高风险关键工作:错误代价高时,用独立尝试 + 对抗测试再交付
- 广度研究:多角度搜索 → 取源 → 逐条 claim 交叉验证 → 带引用综合
八、反模式
- 紧耦合/顺序任务硬塞 workflow(屏障空等、token 白烧)。
- 全程一个
parallel()屏障到底(慢 agent 拖死快 agent)。 - 归约/扁平也用 agent 而非纯 JS。
- loop 对
confirmed去重而非seen(永不收敛)。 - 不试切片直接全量大跑;该升/该降的 stage 模型用反。
- 脚本里用
Date.now()/Math.random()(直接 throw)。
来源
- Orchestrate subagents at scale with dynamic workflows — Claude Code Docs(原语、16/1000 上限、保存/args/恢复、审批)
- Introducing dynamic workflows in Claude Code — Anthropic(Bun 移植四阶段、use case 分类)
- Deterministic Multi-Agent Orchestration — alexop.dev(Vue 新闻信完整脚本、对抗验证、确定性约束)
- A Thousand Agents, One Script — trilogyai
- Claude Code Adds Dynamic Workflows — InfoQ