Claude Code Dynamic Workflows 学习笔记

1. 核心定义 【官方事实】

1.1 Dynamic Workflows 是什么

Dynamic Workflows（动态工作流）是 Claude Code 用 JavaScript workflow script 大规模编排 subagents（子代理）的机制。Claude 为任务写脚本，runtime 在后台执行，主会话保持响应。

1. 形式：JS 脚本
2. 内容：编排 subagents
3. 写法：Claude 为任务写
4. 执行：runtime 后台执行
5. 效果：主会话保持响应

1.2 与其他多代理机制的区别

核心差异：Workflow 把“计划”从 Claude 上下文移到代码里，因此中间结果保存在脚本变量中，编排本身可保存、可复用。

1.3 适用边界

官方示例：全仓库 bug 扫描、500 文件迁移、多来源交叉核查研究、多角度方案评审。

社区经验场景：大规模代码迁移 / 重构、深度研究与带引用报告、文档事实核查、对抗式验证、候选项排序、工单 triage、故障排查。

1.4 常用 workflow 模式 【社区说法】

不适合：单文件小改动、目标模糊且不可验证的任务、纯确定性 IO / 定时 / ETL / SLA 工作流。

2. 可用性、启用条件与运行限制

2.1 可用性 【官方事实】

2.2 script 机制 【官方事实】 【脚本原语事实】

2.3 parallel vs pipeline

2.4 限制与权限

• 最多 16 个并发 agents；每次运行最多 1000 agents。
• 无中途用户输入；阶段间人工签署应拆成多个 workflow。
• 脚本不能直接文件系统 / shell；读写文件、运行命令由 agent 通过工具完成。
• 同一 session 内可恢复；退出 Claude Code 后，下次 session 从头启动。
• subagents 以 acceptEdits 模式运行，文件编辑自动批准；但 shell、network fetch、不在 allowlist 的 MCP tools 仍可能提示。
• workflow 脚本不是 Node.js 全能力；不要依赖 filesystem / Node API，也避免 Date.now()、Math.random() 等非确定性调用。

3. workflow script 的结构输出：两条路线

3.1 schema 的定位 【脚本原语事实】 【实测现象】

schema 是 runtime 支持的结构化输出机制。是否使用 schema 是工程取舍：schema 路线更干净、更强约束，但 schema mismatch 可能导致 agent 失败；防御式 JSON 路线更宽容，但要自己写 tryParseJson、isValidFinding、fallback。

实测中，schema 模式可能因结构化输出不匹配导致 agent 失败；防御式 JSON 路线适合更重视容错与兜底产物的场景。

3.2 路线 A：schema 结构化输出路线

const result = await agent('...', {
  label: 'review:item-a',
  phase: 'Review',
  schema: SOME_JSON_SCHEMA,
})

3.3 路线 B：防御式 JSON 路线

agent 返回（可能是字符串）
  → tryParseJson 提取 JSON
  → isValidFinding / isValidVerdict 严格过滤
  → buildLocalReport 本地兜底

适合 schema 模式在当前环境不稳定、希望失败不拖垮整个 workflow、目标是尽量返回 useful artifact 的场景。

3.4 StructuredOutput 的正确理解

Error: agent({schema}): subagent completed without calling
       StructuredOutput (after 2 in-conversation nudges)

4. 防御式 workflow 模式 【实测现象】

4.1 tryParseJson

function tryParseJson(s) {
  if (s === null || s === undefined) return null
  if (typeof s === 'object') return s
  if (typeof s !== 'string') return null
  try { return JSON.parse(s) } catch (_) {}
  for (let i = 0; i < s.length; i++) {
    const ch = s[i]
    if (ch !== '{' && ch !== '[') continue
    // ...扫描平衡 JSON 块
  }
  return null
}

4.2 isValidFinding / isValidVerdict

const SEVERITIES = ['low', 'medium', 'high', 'critical']
const CONFIDENCES = ['low', 'medium', 'high']
const STATUSES = ['confirmed', 'uncertain', 'refuted']

function isValidFinding(f) {
  return !!f
    && typeof f.id === 'string' && f.id.length > 0
    && typeof f.summary === 'string' && f.summary.length > 0
    && typeof f.severity === 'string' && SEVERITIES.includes(f.severity)
    && typeof f.confidence === 'string' && CONFIDENCES.includes(f.confidence)
    && typeof f.rationale === 'string' && f.rationale.length > 0
}

4.3 buildLocalReport

const report = isValidReport(reportParsed)
  ? reportParsed
  : buildLocalReport(annotated)

核心思想：不完全依赖 synthesize agent；即便 synthesize agent 失败，脚本也能从 annotated findings 拼出 useful artifact。

4.4 prompt 三件套

TASK: <具体目标>
Return ONE JSON object with exactly these fields:
{ id, summary, severity, confidence, rationale }
BOUNDARY:
- Return ONLY the JSON object. No prose, no markdown fences.
- Do not invent file paths, line numbers, or function names.

5. 实测错误清单 【实测现象】

findings 为空

findings 为空 ≠ 一定没发现问题；可能是 agent 返回字符串 / prose / 非结构化对象，导致过滤失败。应看 transcript、加 tryParseJson、强化 Return ONLY JSON。

6. agent() 字段与模型路由

6.1 默认模型行为 【官方事实】

6.2 agent() 字段 【脚本原语事实】

await agent(prompt, {
  label: 'review:item-a',
  phase: 'Review',
  model: 'claude-haiku-4-5',
  schema: SOME_SCHEMA,
})

6.3 模型路由

const MODEL_REGISTRY = {
  cheap: 'claude-haiku-4-5',
  strong: 'claude-opus-4-8',
}

await agent(prompt, {
  label: 'triage:item-b',
  phase: 'Triage',
  model: MODEL_REGISTRY.cheap,
})

7. args、保存与触发方式 【官方事实】

7.1 args

saved workflow 可通过 args 接收输入。脚本中读取全局变量 args；未传入时为 undefined。

> Run /triage-issues on issues 1024, 1025, and 1030

7.2 保存位置

7.3 触发方式

• /deep-research 内置 workflow
• prompt 中包含 ultracode
• 自然语言明确要求 “use a workflow” / “run a workflow” / “fan out agents”
• /effort ultracode：对实质性任务自动规划 workflow
• 保存后通过 /<name> 运行

8. 用户侧核心能力

8.1 判断何时用

适合：多文件 / 大规模 / 可并行 / 可验证 / 需要对抗验证或多角度比较
不适合：单文件小改动 / 目标模糊 / 纯确定性集成 / 成本高于收益

8.2 写 workflow request 的 8 个要素

8.3 审查 script

1. meta / phases 是否清楚。
2. agent() 字段是否符合实测可用写法，如 { label, phase, model, schema }。
3. 如果使用 schema：schema 是否过复杂，prompt 是否与 schema 一致。
4. 如果不用 schema：是否有 tryParseJson。
5. 是否有严格过滤与 fallback。
6. prompt 是否有 TASK / shape / BOUNDARY，且不要提 runtime 内部机制。
7. parallel / pipeline 是否选对。

8.4 不可信输入隔离

处理公开网页、issue、工单等不可信内容时，应隔离低权限读取 agent 与高权限执行 agent，避免原始恶意内容直接影响高权限操作。

9. 社区文章核对结论 【社区说法】

9.1 可采纳为社区经验

• 动态 workflow 把计划移入代码。
• 多 agent 隔离上下文，降低长上下文漂移。
• 适合迁移、审计、研究、事实核查、对抗验证。
• 常见模式：fan-out 汇总、对抗验证、生成筛选、锦标赛比较、循环直到无新发现。
• 成本较高，小任务不值得。
• /workflows 可查看进度，按 s 保存。

9.2 不要直接写成官方事实

• Bun 从 Zig 到 Rust 重写使用 Dynamic Workflows 的具体数据。
• Anthropic 内部团队已使用数月。
• 某个案例具体用了多少 agents、多少 tokens、耗时多久。
• “Claude API 支持 workflows”这类笼统表述；更准确是 Claude Code surfaces、claude -p、Agent SDK。
• “恢复后继续”必须限定为同一 Claude Code session 内。

10. 关键口诀

11. 调试原则

11.1 证据等级

官方事实 > 脚本原语事实 > 实测现象 > 社区说法 > 教学推测

11.2 排障顺序

1. 先看 /workflows 进度和 agent 详情。
2. 再看 transcript 中 agent 实际返回了什么。
3. 判断是 schema 路线失败，还是防御式 JSON 路线解析 / 过滤失败。
4. schema 失败：简化 schema、强化 prompt，或改走防御式 JSON。
5. findings 空：检查 tryParseJson、isValidFinding、prompt shape。

11.3 成本与范围

• 大任务先小范围试跑。
• /workflows 视图看每个 agent 的 token 使用。
• 可在 prompt 中要求某些阶段使用较小模型。
• 可用 budget 在脚本中控制后续 agent 调用。

12. 相关资源

12.1 官方文档

• Claude Code Dynamic Workflows 官方文档
• Claude Code sub-agents
• Claude Code tools-reference

12.2 社区文章

• https://x.com/PandaTalk8/status/2063918562318946740
• https://x.com/trq212/status/2061907337154367865
• https://x.com/0xCodez/status/2062127385923776831
• https://x.com/knoYee_/status/2062144250532561370
• https://x.com/AlphaSignalAI/status/2060361091474223504
• https://x.com/so_ainsight/status/2060598271161291042

🧪 复习测验

Q7：把防御式 JSON 路线按数据流排序

• ≡ agent 返回（可能是字符串或 prose）
• ≡ tryParseJson 提取 JSON
• ≡ isValidFinding / isValidVerdict 严格过滤
• ≡ buildLocalReport / fallback 兜底