多智能体编排——Feature-Dev 与 Code-Review 如何协调 AI 智能体

第 2 篇介绍了组件模型，为我们提供了基础构件。但 Claude Code 插件系统真正的威力，体现在 commands 将多个 agents 编排成协调工作流的那一刻——这些 agents 甚至可以来自不同的模型层级。官方插件中呈现出三种截然不同的编排模式，各自解决不同的问题。

feature-dev 实现了分阶段的人机协作工作流：并行探索 agents 汇聚到一个澄清问题的关卡，之后再进入架构设计和实现阶段。code-review 实现了多轮验证管道：初始发现的问题由全新的子 agents 独立核实。而 ralph-wiggum 则实现了自引用循环：Stop hook 拦截 agent 的退出动作，从而形成迭代执行的闭环。

这些不是纸上谈兵的理论模式——它们都是生产环境中的真实实现，展示了 prompt 工程、模型层级选择与生命周期 hooks 如何组合，构建出复杂的 AI 工作流。

Feature-Dev：7 阶段人机协作工作流

feature-dev 插件位于 plugins/feature-dev/commands/feature-dev.md，它实现了一个七阶段工作流，在 AI agent 的自动处理与人工决策节点之间交替推进：

flowchart TD
    P1["Phase 1: Discovery<br/>Understand the request"] --> P2
    P2["Phase 2: Codebase Exploration<br/>2-3 code-explorer agents ∥"] --> P3
    P3["Phase 3: Clarifying Questions<br/>🚫 CRITICAL HUMAN GATE"] --> P4
    P4["Phase 4: Architecture Design<br/>2-3 code-architect agents ∥"] --> P5
    P5["Phase 5: Implementation<br/>🚫 REQUIRES USER APPROVAL"] --> P6
    P6["Phase 6: Quality Review<br/>3 code-reviewer agents ∥"] --> P7
    P7["Phase 7: Summary<br/>Document outcomes"]

    style P3 fill:#E53935,color:#fff
    style P5 fill:#E53935,color:#fff
    style P2 fill:#FDD835
    style P4 fill:#4CAF50,color:#fff
    style P6 fill:#E53935,color:#fff

这一设计理念在 command 文件中有明确表述："先提问澄清"和"理解先于行动"被列为核心原则。让我们逐阶段来看。

阶段 1（探索） 相对轻量——创建待办清单、确认理解。不启动任何 agents。

阶段 2（代码库探索） 并行启动 2–3 个 code-explorer agents，每个 agent 聚焦于代码库的不同层面。command 文件给出了示例 prompt，例如 "Find features similar to [feature]" 和 "Map the architecture and abstractions for [feature area]." agents 返回结果后，编排 command 读取所有被识别的文件，以建立深度上下文。这是一种广度优先的探索模式。

阶段 3（澄清问题） 被标记为 CRITICAL——不可跳过。command 明确指出："Present all questions to the user in a clear, organized list"，并且 "Wait for answers before proceeding to architecture design." 即便用户表示"你觉得怎样好就怎样"，command 也会要求 Claude 给出自己的建议并获得明确确认。这道关卡的存在，是为了防止工作流在错误假设的基础上做出代价高昂的架构和实现决策。

plugins/feature-dev/commands/feature-dev.md#L56-L69

阶段 4（架构设计） 并行启动 2–3 个 code-architect agents，各自采用不同的优化目标：最小化改动、清晰架构或务实平衡。编排者随后形成自己的判断，并向用户呈现各方案的权衡。

阶段 5（实现） 包含整个文件中最醒目的指令："DO NOT START WITHOUT USER APPROVAL"（第 89 行）。这是第二道人工关卡——在用户明确批准所选架构之前，不得编写任何代码。

阶段 6（质量审查） 启动三个 code-reviewer agents，各有侧重：简洁性/DRY 原则、缺陷/正确性，以及项目规范。审查结果汇总后呈现给用户，由用户做出决策。

Agent 设计：模型层级与工具约束

feature-dev 插件对三种 agent 类型均使用同一模型层级（Sonnet），但工具集和指令经过了精心区分。这是一个有意为之的成本优化选择——Sonnet 速度快、成本低，非常适合这些 agents 所承担的以读取为主的探索和审查工作。

code-review 插件采用了不同的策略。查看位于 plugins/code-review/commands/code-review.md#L14-L55 的 command 文件，可以看到它为不同角色明确指定了不同的模型层级：

步骤	Agent 类型	模型	原因
Step 1（门控检查）	单个 agent	Haiku	快速、廉价——仅判断 PR 是否关闭或为草稿
Step 2（查找 CLAUDE.md）	单个 agent	Haiku	文件列举，无需推理
Step 3（PR 摘要）	单个 agent	Sonnet	摘要生成需要中等推理能力
Step 4（并行审查）	Agents 1-2	Sonnet	CLAUDE.md 合规——模式匹配
Step 4（并行审查）	Agents 3-4	Opus	缺陷检测——需要深度推理
Step 5（验证）	每问题子 agents	Opus/Sonnet	验证缺陷（Opus）vs. CLAUDE.md（Sonnet）

这是经过深思熟虑的模型分层策略。Haiku 以极低成本处理简单检查，Sonnet 负责模式匹配和合规分析，Opus 则专注于高难度推理——在代码差异中发现隐蔽的缺陷。模型层级之间显著的成本差异，使这一架构决策具有实质意义。

提示： 设计多 agent 工作流时，不妨先问自己"完成这项任务所需的最低模型层级是什么？"用 Haiku 做门控，用 Sonnet 做结构化分析，只在深度推理确实必要时才动用 Opus。

Code-Review：多轮验证管道

code-review 插件实现了一个九步管道，其设计远比简单的"扇出、扇入"模式更有意思。它的核心创新在于逐问题验证——审查阶段发现的每个问题，都由一个全新的子 agent 独立核实。

flowchart TD
    S1["Step 1: Gate Check<br/>(haiku)"] -->|"PR open & needs review"| S2
    S1 -->|"PR closed/draft/trivial"| STOP["Stop"]
    S2["Step 2: Find CLAUDE.md files<br/>(haiku)"] --> S3
    S3["Step 3: PR Summary<br/>(sonnet)"] --> S4

    S4["Step 4: Parallel Review"] --> S4A["Agent 1: CLAUDE.md<br/>(sonnet)"]
    S4 --> S4B["Agent 2: CLAUDE.md<br/>(sonnet)"]
    S4 --> S4C["Agent 3: Bug scan<br/>(opus)"]
    S4 --> S4D["Agent 4: Deep bugs<br/>(opus)"]

    S4A --> S5["Step 5: Per-Issue Validation<br/>(parallel subagents)"]
    S4B --> S5
    S4C --> S5
    S4D --> S5

    S5 --> S6["Step 6: Filter Unvalidated"]
    S6 --> S7["Step 7: Output Summary"]
    S7 -->|"--comment flag"| S8["Steps 8-9: Post Inline Comments"]

    style S1 fill:#78909C,color:#fff
    style S4C fill:#9C27B0,color:#fff
    style S4D fill:#9C27B0,color:#fff
    style S5 fill:#FF5722,color:#fff

Step 5 正是这条管道的与众不同之处。它并不直接信任审查 agents 的输出，而是要求："For each issue found in the previous step by agents 3 and 4, launch parallel subagents to validate the issue." 每个验证子 agent 只接收 PR 标题/描述和待验证的具体问题。这种"全新视角"的方式，能有效捕捉原始审查 agent 可能因先入为主而产生的误报。

过滤标准明确以降噪为导向：

plugins/code-review/commands/code-review.md#L79-L86

已存在的问题、看似正确的缺陷、吹毛求疵的小问题、linter 可捕捉的问题，以及宽泛的质量建议，都被列为应避免的误报类型。command 明确指出："False positives erode trust and waste reviewer time."

PR Review Toolkit：6 Agent 专项分工

pr-review-toolkit 位于 plugins/pr-review-toolkit/commands/review-pr.md，采用了另一种思路：六个专项 agents，每个深度聚焦于代码质量的某一维度：

flowchart LR
    CMD["/review-pr"] --> SCOPE["Determine<br/>Review Scope"]
    SCOPE --> CA["comment-analyzer<br/>Comment accuracy"]
    SCOPE --> TA["pr-test-analyzer<br/>Test coverage"]
    SCOPE --> SFH["silent-failure-hunter<br/>Error handling"]
    SCOPE --> TDA["type-design-analyzer<br/>Type design"]
    SCOPE --> CR["code-reviewer<br/>General quality"]
    SCOPE --> CS["code-simplifier<br/>Simplification"]

    CA --> AGG["Aggregate<br/>Results"]
    TA --> AGG
    SFH --> AGG
    TDA --> AGG
    CR --> AGG
    CS --> AGG

    AGG --> OUTPUT["Categorized<br/>Output"]

与 code-review 的关键区别在于：pr-review-toolkit 默认按顺序运行 agents（可按需开启并行），根据变更文件的类型有条件地激活 agents（例如 type-design-analyzer 仅在有类型新增或修改时才运行），并将发现按 Critical / Important / Suggestions / Positive 分类输出。与 code-review 的深度优先验证管道相比，这是一种广度优先的审查方式。

这为团队提供了两种 PR 审查方案，可按需选择：code-review 适合追求高信噪比缺陷检测的场景，pr-review-toolkit 则适合需要全面多维度分析的场景。

Ralph Wiggum 模式：自引用 Agent 循环

ralph-wiggum 插件实现了一种颇具新意的机制——自引用循环：Claude 反复处理同一任务，每次都能看到自己之前的工作，直到满足完成条件为止。

其核心机制是一个 Stop hook。当 Claude 尝试退出时，位于 plugins/ralph-wiggum/hooks/stop-hook.sh 的 hook 会拦截退出动作，读取对话记录，并重新注入原始 prompt：

flowchart TD
    START["/ralph-loop PROMPT"] --> SETUP["Setup: Write state file<br/>.claude/ralph-loop.local.md"]
    SETUP --> WORK["Claude works on PROMPT"]
    WORK --> STOP["Claude tries to stop"]
    STOP --> HOOK["Stop hook fires"]
    HOOK --> CHECK{"State file<br/>exists?"}
    CHECK -->|No| EXIT["Allow exit"]
    CHECK -->|Yes| ITER{"Max iterations<br/>reached?"}
    ITER -->|Yes| EXIT
    ITER -->|No| PROMISE{"Completion<br/>promise met?"}
    PROMISE -->|Yes| EXIT
    PROMISE -->|No| REINJECT["Block stop<br/>Re-inject PROMPT"]
    REINJECT --> |"iteration + 1"| WORK

    style HOOK fill:#FF5722,color:#fff
    style REINJECT fill:#E53935,color:#fff

状态文件（.claude/ralph-loop.local.md）通过 YAML frontmatter 跟踪循环状态：

---
iteration: 3
max_iterations: 10
completion_promise: "All tests pass"
---

The actual prompt text goes here...

hook 解析这段 frontmatter，递增迭代计数器，并检查完成承诺——这是一段文本字符串，只有当声明的条件真正成立时，Claude 才能将其输出在 <promise> 标签内。hook 在第 119 行使用 Perl 正则表达式提取承诺文本，并通过字面字符串比较（非 glob 匹配）进行验证：

plugins/ralph-wiggum/hooks/stop-hook.sh#L114-L128

command 文件对诚信约束作出了强调："You may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop."

阻止退出时，hook 输出一个 JSON 决策：

plugins/ralph-wiggum/hooks/stop-hook.sh#L167-L174

jq -n \\
  --arg prompt \"$PROMPT_TEXT\" \\
  --arg msg \"$SYSTEM_MSG\" \\
  '{
    \"decision\": \"block\",
    \"reason\": $prompt,
    \"systemMessage\": $msg
  }'

"reason" 字段包含被重新注入的 prompt，"systemMessage" 则提供迭代元数据："🔄 Ralph iteration 4 | To stop: output <promise>All tests pass</promise>"。

提示： ralph-wiggum 模式非常适合"持续改进直到测试通过"或"重构这个模块直到代码质量分超过 90"这类任务。完成承诺机制确保 Claude 无法投机取巧地逃出循环。

编排模式对比

这三种模式代表了多 agent 协调的三种根本不同的思路：

维度	Feature-Dev	Code-Review	Ralph Wiggum
模式	分阶段人机协作	验证管道	自引用循环
人工介入	2 个强制关卡（阶段 3、5）	可选（--comment 标志）	启动后无需介入
Agent 并行度	较宽（每阶段 2-3 个）	较窄（4 个审查者 + 逐问题验证者）	顺序执行（单 agent 循环）
模型层级	单一层级（Sonnet）	混合（Haiku→Sonnet→Opus）	继承自当前会话
终止条件	自然结束（7 个阶段完成）	自然结束（管道结束）	承诺满足或达到最大迭代次数
成本特征	中等（Sonnet × 并行数量）	较高（Opus 用于缺陷检测）	不定（取决于迭代次数）
适用场景	复杂新功能开发	高信噪比的 PR 审查	迭代式改进任务

feature-dev 模式以人工控制为优先——它专为复杂决策场景设计，在这类场景中错误假设会层层放大。code-review 模式以信号质量为优先——验证步骤的存在就是为了过滤噪声。ralph-wiggum 模式以自主迭代为优先——适用于完成标准明确但路径不确定的任务。

flowchart LR
    subgraph "Human Control ←→ Autonomy"
        FD["Feature-Dev<br/>2 human gates"] --> CR["Code-Review<br/>Optional comment"]
        CR --> RW["Ralph Wiggum<br/>Fully autonomous"]
    end

    subgraph "Cost ←→ Quality"
        CHEAP["Haiku gates<br/>(cheap)"] --> MID["Sonnet analysis<br/>(moderate)"]
        MID --> EXPENSIVE["Opus reasoning<br/>(expensive)"]
    end

下一步

至此，我们已经了解了 commands 如何将 agents 编排成工作流。第 4 篇将深入 hook 系统，通过三个真实实现，展示其全部可能性。security-guidance 插件以概率化状态清理的方式监控九种安全反模式；hookify 实现了一个可配置的规则引擎，内置自定义 YAML 解析器和带 LRU 缓存的正则编译；而 explanatory-output-style 插件则证明，有时最强大的 hook 不过是 15 行 shell 脚本。