[!info] related notes

• 所属 MOC: Agent MOC, AI MOC
• 相关概念: Claude Code Workflow, Claude Code
• 并列概念: 多 Agent 编排模式, Orchestrator-Workers
• 易混淆概念: Evaluator-Optimizer

Claude Code 多 Agent 编排模式

范围

这篇笔记讨论 Claude Code 内部可用的多 Agent 协作方式，对比三种机制的适用场景、控制方式和结果质量。

三种机制对比

机制	控制方式	适用场景	结果质量	复杂度
直接对话	自然语言，主 Agent 自行决定	简单任务，单步完成	依赖单次能力	最低
Agent 工具	手动串联，主 Agent 逐个调用	需要委派子任务	单一视角	中等
Workflow	确定性脚本编排	多维度审查、修复循环、大规模扫描	多视角交叉验证	最高

1. 直接对话（默认方式）

最基础的方式：主 Agent 自己完成所有工作。

用户 → 主 Agent → 直接操作文件/命令

• 不涉及 sub-agent
• 适合简单明确的任务
• 上下文窗口是唯一限制

2. Agent 工具（手动委派）

主 Agent 通过 Agent 工具启动一个 sub-agent，等待结果后决定下一步。

主 Agent
  ├─ Agent("分析 src/ 目录结构")  → 返回分析结果
  ├─ Agent("根据分析实现功能")    → 返回实现代码
  └─ Agent("审查实现")           → 返回审查意见

特点

• 每个 Agent 有独立的上下文窗口
• 主 Agent 决定调用顺序和参数
• 结果是自然语言文本（除非手动解析）
• 可以串行也可以并行

局限

• 编排逻辑依赖主 Agent 的「记忆」和「判断」——可能忘记下一步、遗漏并行机会
• 没有 schema 校验，结果格式不稳定
• 没有进度追踪和缓存恢复

适用场景

• 一次性委派某个子任务（如「帮我搜索所有 TODO」）
• 不需要循环或复杂控制流的场景

3. Workflow（确定性脚本编排）

用 JavaScript 脚本定义控制流，由 Workflow 引擎执行。详见 Claude Code Workflow。

脚本定义：
  Phase 1: Implement  → 1 个 agent 写代码
  Phase 2: Review     → 3 个 agent 并行审查
  Phase 3: Fix        → 循环修复直到通过
  Phase 4: Verify     → 最终确认

核心优势

确定性控制流：循环、条件、计数器、屏障用代码写，不依赖 AI 的「记住要循环三次」。

Schema 校验：强制 agent 输出结构化 JSON，保证 agent 间通信可靠。

并发管理：自动处理队列、并发上限、结果收集。

进度追踪：phase + log 让用户实时看到进展。

缓存恢复：编辑脚本后可以从断点恢复，已完成的 agent 调用不重复执行。

适用场景

• 实现→审查→修复的循环
• 多维度并行审查（正确性、安全性、边界情况）
• 大规模文件扫描/迁移
• 需要保证质量的任务

选择决策树

任务来了
 │
 ├─ 单步就能完成？
 │   └─ 直接对话，不需要委派
 │
 ├─ 需要委派一个子任务？
 │   └─ Agent 工具，手动串联
 │
 ├─ 需要多维度审查或修复循环？
 │   └─ Workflow，脚本编排
 │
 └─ 大规模并行扫描？
     └─ Workflow + pipeline

Workflow 中的编排模式

Adversarial Verify（对抗性验证）

并行启动多个审查 agent，各自从不同角度审查，默认尝试反驳而非通过。

const reviews = await parallel([
  () => agent('从正确性角度尝试反驳这段代码', { schema: VERDICT }),
  () => agent('从安全性角度尝试反驳这段代码', { schema: VERDICT }),
  () => agent('从边界情况角度尝试反驳这段代码', { schema: VERDICT }),
])
const survives = reviews.filter(v => !v.refuted).length >= 2

Loop-Until-Dry（循环直到无新发现）

let dry = 0
while (dry < 2) {
  const found = await agent('查找 bug', { schema: BUGS })
  if (found.bugs.length === 0) { dry++; continue }
  dry = 0
  // 处理发现的 bug...
}

Pipeline-Verify（流水线验证）

每个文件独立走完 分析→修复→验证 全流程，不互相等待。

const results = await pipeline(
  files,
  f => agent(`分析 ${f}`, { schema: ANALYSIS }),
  (analysis, f) => agent(`修复 ${f}: ${analysis}`, { schema: FIX }),
  (fix, f) => agent(`验证 ${f} 的修复`, { schema: VERDICT }),
)

与其他多 Agent 模式的关系

Claude Code 的 Workflow 属于 Orchestrator-Workers 模式的一种具体实现，但加入了 Evaluator-Optimizer 的评审循环。

和外部框架的对比：

维度	Claude Code Workflow	LangGraph	CrewAI
控制方式	JavaScript 脚本	Python 图定义	YAML 角色定义
集成方式	内置于 Claude Code	独立框架	独立框架
最适合	Claude Code 内的编码任务	通用 agent 工作流	角色扮演式多 agent
学习成本	低（只需写 JS）	中（图概念）	中（角色抽象）

边界与易混淆点

• Agent 工具和 Workflow 不是替代关系，而是不同粒度的工具。小任务用 Agent，大任务用 Workflow。
• Workflow 不是「更高级的 Agent」——它的价值在于确定性控制流，不在于单个 agent 的能力。
• Workflow 里的每个 agent 都是全新的独立会话，它们之间不能直接通信，只能通过脚本传递结果。
• 并行不等于快——如果任务之间有依赖，强行并行会导致错误。

Related notes

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