マルチエージェントオーケストレーション — Feature-Dev と Code-Review に学ぶ AI エージェント連携の設計

第2回で説明したコンポーネントモデルは、あくまでも構成要素です。Claude Code のプラグインシステムが真の力を発揮するのは、コマンドが複数のエージェントを、場合によっては異なるモデルティアを組み合わせながら、協調したワークフローとして動かすときです。公式プラグインには3つの異なるオーケストレーションパターンが現れており、それぞれが異なる問題を解決しています。

feature-dev は段階的ヒューマンインザループワークフローを実装しています。並列探索エージェントが収集した情報を、確認質問ゲートを経てアーキテクチャ設計・実装フェーズへとつなげる構造です。code-review はマルチパスバリデーションパイプラインを採用しており、最初のレビューで見つかった指摘を、新鮮なサブエージェントが独立して検証します。そして ralph-wiggum は自己参照ループを実装しています。Stop フックがエージェントの終了を横取りし、反復実行サイクルを生み出す仕組みです。

これらは概念的なパターンではありません。プロンプトエンジニアリング、モデルティアの選択、ライフサイクルフックをどう組み合わせれば洗練された AI ワークフローが生まれるかを教えてくれる、実際の本番実装です。

Feature-Dev：7 フェーズのヒューマンインザループワークフロー

plugins/feature-dev/commands/feature-dev.md の feature-dev プラグインは、AI エージェントの作業と人間による判断点を交互に配置した7フェーズのワークフローを実装しています。

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

設計思想はコマンドファイルに明示されています。「確認質問をすること」「行動する前に理解すること」がコア原則として挙げられています。各フェーズを順に見ていきましょう。

フェーズ1（Discovery） は軽量です——todo リストを作り、理解を確認するだけで、エージェントは起動しません。

フェーズ2（Codebase Exploration） では、コードベースの異なる側面をそれぞれ担当する code-explorer エージェントを2〜3つ並列で起動します。コマンドには「[feature] に似た機能を探す」「[feature area] のアーキテクチャと抽象化をマップする」といったプロンプト例が記載されています。エージェントが戻ってきたら、オーケストレーターは識別されたすべてのファイルを読み込み、深いコンテキストを構築します。これは幅優先の探索パターンです。

フェーズ3（Clarifying Questions） は CRITICAL（絶対に省略不可）とマークされています。コマンドには明示的にこう書かれています：「すべての質問を整理してユーザーに提示すること」「アーキテクチャ設計に進む前に回答を待つこと」。ユーザーが「あなたの判断に任せます」と言っても、Claude 自身の推奨案を提示して明示的な確認を取るよう指示されています。このゲートが存在するのは、誤った前提のままアーキテクチャ設計や実装という高コストな判断を下してしまうことを防ぐためです。

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

フェーズ4（Architecture Design） では、最小限の変更・クリーンなアーキテクチャ・現実的なバランスといった、異なる最適化目標を持つ code-architect エージェントを2〜3つ並列で起動します。その後、オーケストレーターが自らの見解をまとめ、トレードオフをユーザーに提示します。

フェーズ5（Implementation） には、ファイル全体の中で最も力強い指示が書かれています：「ユーザーの承認なしに開始するな」（89行目）。これが第2の人間ゲートです——ユーザーが選択したアーキテクチャを明示的に承認するまで、コードは1行も書きません。

フェーズ6（Quality Review） では、シンプルさと DRY 原則・バグと正確性・プロジェクトの規約という3つの観点を担当する code-reviewer エージェントをそれぞれ起動します。結果は統合されてユーザーに提示され、最終判断を委ねます。

エージェント設計：モデルティアとツールの制約

feature-dev プラグインは3種類のエージェントすべてに同一のモデルティア（Sonnet）を使いますが、ツールセットと指示は慎重に差別化されています。これは意図的なコスト最適化の選択です——これらのエージェントが行う読み取り中心の探索やレビュー作業には、Sonnet の速度とコストのバランスがちょうどよいのです。

code-review プラグインは異なる戦略を採ります。plugins/code-review/commands/code-review.md#L14-L55 を見ると、役割ごとに異なるモデルティアが明示的に指定されています。

ステップ	エージェントの種類	モデル	理由
Step 1（ゲートチェック）	単一エージェント	Haiku	高速・低コスト——PR がクローズ/ドラフトかを確認するだけ
Step 2（CLAUDE.md の検索）	単一エージェント	Haiku	ファイル一覧の取得のみで推論は不要
Step 3（PR サマリー）	単一エージェント	Sonnet	要約には適度な推論が必要
Step 4（並列レビュー）	エージェント 1-2	Sonnet	CLAUDE.md 準拠確認——パターンマッチング
Step 4（並列レビュー）	エージェント 3-4	Opus	バグ検出——深い推論が必要
Step 5（バリデーション）	Issue ごとのサブエージェント	Opus/Sonnet	バグ検証（Opus）vs CLAUDE.md 確認（Sonnet）

これはモデルの得意領域に基づいた意図的なティアリングです。Haiku は最小コストでシンプルなチェックをこなします。Sonnet はパターンマッチングとコンプライアンス確認を担います。Opus は本当に難しい推論——コードの差分から微妙なバグを発見する作業——にのみ投入します。モデルティア間のコスト差を考えると、これは無視できない設計上の判断です。

ヒント： マルチエージェントワークフローを設計するときは、「この仕事をこなせる最低限のモデルティアはどれか？」という問いから始めましょう。ゲーティング処理には Haiku を、構造化された分析には Sonnet を、深い推論が必要な箇所にのみ Opus を使うのが基本です。

Code-Review：マルチパスバリデーションパイプライン

code-review プラグインは9ステップのパイプラインを実装しており、単純な「ファンアウト→ファンイン」パターンより洗練されています。最大の特徴は issue ごとのバリデーション——レビューステップで見つかった各指摘を、新鮮なサブエージェントが独立して検証する仕組みです。

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 です。レビューエージェントの出力をそのまま信頼するのではなく、コマンドにはこう明記されています：「前のステップでエージェント3と4が見つけた issue それぞれに対して、並列サブエージェントを起動して検証する」。各バリデーションサブエージェントには PR のタイトル・説明と検証対象の issue だけが渡されます。この「先入観のない目」によるアプローチが、元のレビューエージェントが偏りを持って見逃しがちなフォールスポジティブを捉えます。

フィルタリング基準はノイズ排除に徹しています。

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

既存の問題、正しく見えるバグ、些細な指摘、linter が検出できる問題、一般的な品質懸念——これらはすべて除外すべきフォールスポジティブとしてリストされています。コマンドにはこう書かれています：「フォールスポジティブは信頼を損ない、レビュアーの時間を無駄にする」。

PR Review Toolkit：6 エージェントによる専門分化

plugins/pr-review-toolkit/commands/review-pr.md の pr-review-toolkit は異なるアプローチを取ります。コード品質の6つの側面にそれぞれ深く集中する、6つの専門エージェントによる構成です。

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 との主な違いは3点あります。デフォルトでは逐次実行（オプションで並列化）、変更されたファイルに応じて適用エージェントを条件分岐（たとえば type-design-analyzer は型が追加・変更された場合のみ動作）、そして指摘結果を Critical・Important・Suggestions・Positive に分類して提示します。code-review が深さを重視したバリデーションパイプラインであるのに対して、こちらは広さを重視したアプローチです。

チームには PR レビューの目的に合わせた2つの選択肢があります。高品質なシグナルと検証が必要なバグ検出には code-review を、多角的な包括分析には pr-review-toolkit を使いましょう。

Ralph Wiggum パターン：自己参照エージェントループ

ralph-wiggum プラグインが実装しているのは、本当にユニークな仕組みです——Claude が同じタスクを繰り返し、自分の前回の作業を見ながら完了条件を満たすまで実行し続ける、自己参照ループです。

仕組みの核心は Stop フックです。Claude が終了しようとすると、plugins/ralph-wiggum/hooks/stop-hook.sh のフックが終了を横取りし、トランスクリプトを読み取り、元のプロンプトを再注入します。

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...

フックはこの frontmatter を解析してイテレーションカウンターをインクリメントし、completion promise を確認します。これは、記載された条件が本当に満たされたときに Claude が <promise> タグの中に出力しなければならないテキスト文字列です。フックは 119行目 の Perl 正規表現で promise テキストを抽出し、リテラル文字列比較（glob マッチングではない）で検証します。

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

コマンドファイルもこの整合性制約を強調しています：「この文言を出力できるのは、その条件が完全かつ明確に真である場合のみです。ループから抜け出すために虚偽の promise を出力してはいけません。」

停止をブロックする際、フックは 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" フィールドに再注入されるプロンプトが入ります。"systemMessage" にはイテレーションのメタデータが含まれます："🔄 Ralph iteration 4 | To stop: output <promise>All tests pass</promise>"。

ヒント： ralph-wiggum パターンは「テストが通るまで改善し続けろ」「コード品質スコアが90点を超えるまでこのモジュールをリファクタリングし続けろ」といったタスクに威力を発揮します。completion promise の仕組みによって、Claude がループから不正に抜け出すことを防げます。

オーケストレーションパターンの比較

これら3つのパターンは、マルチエージェント連携に対する根本的に異なるアプローチを体現しています。

観点	Feature-Dev	Code-Review	Ralph Wiggum
パターン	段階的ヒューマンインザループ	バリデーションパイプライン	自己参照ループ
人間の関与	必須ゲート2か所（フェーズ3・5）	任意（--comment フラグ）	起動後はなし
エージェントの並列性	広め（フェーズごとに2〜3）	狭め（レビュアー4つ＋issue ごとのバリデーター）	逐次（1エージェントがループ）
モデルティア	単一ティア（Sonnet）	混在（Haiku→Sonnet→Opus）	セッションから継承
終了条件	自然終了（7フェーズ完了）	自然終了（パイプライン終了）	Promise 成立 or 最大イテレーション数
コストプロファイル	中（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

次回予告

コマンドがエージェントをワークフローへと編成する仕組みを見てきました。第4回ではフックシステムを深く掘り下げ、何が可能かを示す3つの実装を取り上げます。security-guidance プラグインは確率的な状態クリーンアップを伴う9つのセキュリティアンチパターンを監視します。hookify はカスタム YAML パーサーと LRU キャッシュ付き正規表現コンパイルを備えた設定可能なルールエンジンを実装しています。そして explanatory-output-style プラグインは、わずか15行のシェルスクリプトが最も強力なフックになりうることを示します。