vault: add Claude Code dynamic workflows best practices + concrete examples
This commit is contained in:
Yaojia Wang
@@ -0,0 +1,190 @@
|
||||
---
|
||||
created: "2026-06-18"
|
||||
type: resource
|
||||
tags: [resource, claude-code, dynamic-workflows, orchestration, multi-agent, pipeline, best-practices, anthropic]
|
||||
source: "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()` 调用一致。
|
||||
|
||||
```javascript
|
||||
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 强制结构化):
|
||||
```javascript
|
||||
const raw = await parallel(
|
||||
SOURCES.map((s) => () =>
|
||||
agent(s.prompt, { label: `research:${s.key}`, schema: ITEM_SCHEMA,
|
||||
agentType: 'general-purpose' })
|
||||
)
|
||||
)
|
||||
```
|
||||
**Phase 2 纯 JS 归约**(去重/扁平**不**再起 agent):
|
||||
```javascript
|
||||
const flatItems = collected.flatMap((c) =>
|
||||
(c.items || []).map((it) => ({ ...it, source: c.source })))
|
||||
```
|
||||
**Phase 3 顺序综合**:
|
||||
```javascript
|
||||
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 阶段)
|
||||
|
||||
1. **Scope**(1 agent):把问题拆成 5 个不同搜索角度
|
||||
2. **Search**(5 并行 agent):各自独立 web 搜索
|
||||
3. **Fetch**(顺序):URL 去重,抽 ~15 个源
|
||||
4. **Verify**(每条 claim 并行):**三票制,怀疑者尝试证伪**
|
||||
5. **Synthesize**(1 agent):只用存活的 claim 生成带引用报告
|
||||
|
||||
> **没survive 的 claim 永远进不了报告**——这就是把质量门写进编排的范例。
|
||||
|
||||
### 例 3:Bun 移植(Zig→Rust,真实大规模)
|
||||
|
||||
Jarred Sumner 用 workflows 把 Bun 从 Zig 移植到 Rust:**~75 万行、99.8% 测试通过、11 天合并**。四阶段:
|
||||
1. **Mapping**:一个 workflow 为 Zig 里每个 struct 字段推断对应 Rust lifetime
|
||||
2. **Translation**:**几百个并行 agent**逐个 `.zig`→`.rs`,**每文件配 2 个 reviewer**
|
||||
3. **Fix loop**:自动迭代 build+test 直到通过
|
||||
4. **Optimization**:**通宵** workflow 消除多余拷贝,**每项生成单独 PR** 供人审
|
||||
|
||||
> 模式提炼:**map(推断约束) → 并行翻译(每单元配双评审) → 自动修复循环 → 优化并拆成可审 PR**。能力上限极高,但 token 成本对应也高。
|
||||
|
||||
---
|
||||
|
||||
## 四、质量模式(workflow 的精髓)
|
||||
|
||||
```javascript
|
||||
// 对抗式 / 多镜头验证:每个发现配不同视角的独立评判者(不是 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](https://code.claude.com/docs/en/workflows)(原语、16/1000 上限、保存/args/恢复、审批)
|
||||
- [Introducing dynamic workflows in Claude Code — Anthropic](https://claude.com/blog/introducing-dynamic-workflows-in-claude-code)(Bun 移植四阶段、use case 分类)
|
||||
- [Deterministic Multi-Agent Orchestration — alexop.dev](https://alexop.dev/posts/claude-code-workflows-deterministic-orchestration/)(Vue 新闻信完整脚本、对抗验证、确定性约束)
|
||||
- [A Thousand Agents, One Script — trilogyai](https://trilogyai.substack.com/p/claude-codes-dynamic-workflows-a)
|
||||
- [Claude Code Adds Dynamic Workflows — InfoQ](https://www.infoq.com/news/2026/06/dynamic-workflows-claude-code/)
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
### Resources
|
||||
- [[Claude Code 官方多Agent编排最佳实践 (2026)]]
|
||||
- [[ECC orch- 编排家族与 v2.0 团队编排]]
|
||||
- [[ECC 编排实战手册]]
|
||||
- [[Autonomous Loops 自主循环模式]]
|
||||
|
||||
### Zettelkasten
|
||||
- [[20260618073140 编排即排序门控与委派]]
|
||||
- [[Plans as Prompts设计模式]]
|
||||
Reference in New Issue
Block a user