[!info] related notes

• 前置概念: claude-code, Evaluator-Optimizer, Orchestrator-Workers
• 并列概念: Claude Code 多 Agent 编排模式
• 关系笔记: Agentic Workflow Patterns, 多 Agent 编排模式
• 相关工具: Claude Code Memory

Claude Code Workflow

一句话定义

Workflow 是 Claude Code 内置的多 Agent 编排引擎，用确定性 JavaScript 脚本定义控制流（循环、条件、屏障），让多个独立 sub-agent 各司其职，实现单个 Agent 无法完成的复杂任务。

它解决什么问题

单个 Agent 的上下文窗口和注意力是有限的。当任务复杂到一定程度（审查 50 个文件、跨模块重构、实现+审查+修复循环），一个 Agent 做不完或做不好。Workflow 让你把任务拆给多个专门的 Agent，由确定性脚本控制协作方式。

核心设计哲学：把编排逻辑从 AI 的判断中剥离出来。

• AI 擅长的：写代码、审查、理解语义 → 放在 agent() 里
• AI 不擅长的：稳定的控制流、精确的计数、可靠的循环退出 → 放在脚本里

架构

用户
 │
 ▼
Claude Code 主循环（主对话 Agent）
 │
 │  调用 Workflow 工具
 ▼
Workflow 引擎
 │
 ├─ 解析脚本（JavaScript）
 ├─ 管理执行计划（phases）
 ├─ 调度 Agent（并发控制、队列）
 ├─ 收集结果（schema 校验）
 └─ 返回最终结果
     │
     ▼
   多个 Sub-Agent（各自独立的上下文窗口）

关键理解：Workflow 脚本不是在本地机器上运行的 Node.js 程序，而是一段由 Workflow 引擎解释执行的声明式脚本，里面的 agent() 调用最终都是向 Claude API 发起的请求。

核心 API

agent(prompt, opts) — 基础执行单元

每次调用创建一个全新的 Claude 会话，有独立的上下文窗口，不知道其他 agent 的存在。

const result = await agent('审查这段代码...', {
  label: '安全审查',        // 显示在进度树上的名字
  phase: 'Review',          // 归入哪个阶段
  schema: MY_SCHEMA,        // 强制输出 JSON 格式
  model: 'sonnet',          // 可选：指定模型
  isolation: 'worktree',    // 可选：在独立 git worktree 中工作
  agentType: 'Explore',     // 可选：使用自定义 agent 类型
})

parallel(thunks) — 并行屏障

同时启动多个 agent，全部完成后才继续执行下一行。结果按传入顺序排列。

const [a, b, c] = await parallel([
  () => agent('审查安全性', { schema: REVIEW }),
  () => agent('审查正确性', { schema: REVIEW }),
  () => agent('审查性能',   { schema: REVIEW }),
])

• 并发上限：min(16, CPU核心数 - 2)
• 超出上限的调用会排队等待

pipeline(items, ...stages) — 流水线（非屏障）

每个 item 独立推进自己的阶段，互不等待。文件 A 在 Stage 2 时，文件 B 可能还在 Stage 1。

const results = await pipeline(
  files,                          // 待处理列表
  file => agent(`分析 ${file}`),  // Stage 1
  (analysis, file) => agent(`修复 ${file}: ${analysis}`),  // Stage 2
)

执行示意：

文件A: [分析] ─────→ [修复] ─────→ 完成
文件B:      [分析] ─────→ [修复] ─────→ 完成
文件C:           [分析] ─────→ [修复] ─────→ 完成

phase(title) — 阶段标记

phase('Review')
// 此后的 agent() 调用都归入 "Review" 阶段
// 在进度 UI 上显示为一个分组

纯视觉/组织用途，不影响执行逻辑。

log(message) — 进度输出

log('发现 3 个问题，开始修复...')

显示在进度树上方，让用户知道发生了什么。

Schema 校验 — 强制结构化输出

const REVIEW_SCHEMA = {
  type: 'object',
  properties: {
    pass: { type: 'boolean' },
    issues: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          severity: { type: 'string', enum: ['critical', 'major', 'minor'] },
          description: { type: 'string' },
        },
        required: ['severity', 'description'],
      },
    },
  },
  required: ['pass', 'issues'],
}

const result = await agent('审查代码', { schema: REVIEW_SCHEMA })
// result 一定是 { pass: bool, issues: [...] } 格式
// 如果 agent 返回的 JSON 不符合 schema，引擎会自动重试

这是保证 Agent 间可靠通信的关键。没有 schema，就得靠自然语言解析 Agent 的输出——脆弱且不可靠。

args — 参数注入

// 调用时传入
Workflow({ script: myScript, args: { task: '实现 JWT 刷新机制' } })

// 脚本中使用
const task = args?.task || '默认任务'

budget — 预算控制

budget.total      // 用户设定的 token 上限（如 "+500k" → 500000）
budget.spent()    // 已消耗的 token 数
budget.remaining() // 剩余

// 动态循环：剩余预算不足时停止
while (budget.remaining() > 50_000) {
  await agent('继续找 bug...')
}

预算在主循环和所有 workflow 之间共享，不是每个 workflow 独立的。

workflow(name, args) — 嵌套调用

// 调用另一个已保存的 workflow
const sub = await workflow('find-bugs', { path: 'src/' })

嵌套仅限一层，子 workflow 共享父级的并发上限、agent 计数和预算。

脚本生命周期

脚本文本
  │
  ▼
持久化到 .claude/workflows/ 目录
  │
  ▼
Workflow 引擎解析
  │
  ▼
逐行执行，遇到 agent() 调用时：
  ├─ 创建 sub-agent 请求
  ├─ 排队（受并发上限约束）
  ├─ 等待返回
  └─ 将结果注入脚本上下文，继续执行
  │
  ▼
返回最终结果给主对话

缓存与恢复

// 第一次运行
const runId = await Workflow({ script: myScript })

// 中途暂停/编辑脚本后恢复
await Workflow({
  scriptPath: '.claude/workflows/my-script.js',
  resumeFromRunId: 'wf_abc123'
})
// 已完成的 agent 调用直接返回缓存结果
// 只有被编辑的部分重新执行

实现原理：确定性执行——相同脚本 + 相同参数 = 相同的 agent 调用序列，引擎可以跳过已完成的部分。

并发模型

Workflow 引擎
 │
 ├─ Agent 调度器（队列 + 并发上限）
 │   ├─ 运行中: agent-1, agent-2, agent-3  ← 同时
 │   ├─ 队列中: agent-4, agent-5           ← 等待
 │   └─ 已完成: agent-0                    ← 结果已收集
 │
 ├─ 并发上限: min(16, cpu_cores - 2)
 ├─ 单次 parallel/pipeline: 最多 4096 项
 └─ 全生命周期: 最多 1000 个 agent

使用方式

方式一：对话中直接调用

告诉 Claude Code：

“用 workflow 实现一个功能，然后用多个 agent 交叉验证”

主 Agent 会自动生成脚本并执行。

方式二：保存为可复用脚本

把脚本存到 .claude/workflows/ 目录下，以后通过名称调用。

方式三：Skill 触发

某些 skill 的指令中会要求使用 Workflow，此时 Claude Code 会自动编排。

典型模式

Implement-and-Verify（实现+验证循环）

实现 Agent ──→ 审查 Agent 1 (正确性)  ─┐
              → 审查 Agent 2 (安全性)  ─┼→ 汇总 → 修复 Agent → 再审查...
              → 审查 Agent 3 (边界)    ─┘

Loop-Until-Dry（发现循环）

循环运行 finder agent，直到连续 N 轮没有新发现。

Multi-Modal Sweep（多模态扫描）

并行启动多个搜索 agent，各自从不同角度（按文件、按内容、按实体）搜索，汇总去重。

边界与易混淆点

• Workflow 是大锤，简单任务不需要它。单次 Agent 工具就够的场景不要上 Workflow。
• 脚本里的 Date.now()、Math.random()、无参 new Date() 会抛错——它们会破坏缓存恢复的确定性。
• pipeline() 和 parallel() 的区别很关键：pipeline 不等待，parallel 等全部完成。误用 barrier 会浪费大量等待时间。
• schema 不是可选的装饰——它是 agent 间可靠通信的基础设施。不用 schema 就得靠自然语言解析，不可靠。

Related notes

• Claude Code
• Claude Code 多 Agent 编排模式
• Evaluator-Optimizer
• Orchestrator-Workers
• Agentic Workflow Patterns