rfdnxbro/multi-agent-orchestration

マルチエージェント編成パターン

Agent tool で非自明な並列・チーム作業を委譲する前に、以下の 3 つの判断を済ませる。

1. サブエージェント vs エージェントチームの判定

| 状況 | 採用 | |---|---| | 各タスクが独立、結果は親が統合するだけ | サブエージェント並列（Agent を fire-and-forget で複数起動） | | タスク間に依存（A の出力が B の入力になる） | エージェントチーム（TeamCreate → team_name 付き spawn） | | チームメイト同士で相談・通知が発生する | エージェントチーム | | 計画／設計フェーズで複数視点を組み合わせたい | エージェントチーム |

サブエージェントの限界: 親 → 子の一方向通信のみ。並列起動はできるが互いに会話できないため、依存があると「古い情報で並列実行 → 後で書き直し」になる。

エージェントチームの利点: SendMessage でチームメイト間の双方向通信が可能。TeammateIdle フックでアイドル時の振る舞いも制御できる。Plan Approval ワークフローで段階的承認も取れる。

2. レビュアー Teammate の組み込み

エージェントチームを組成する場合は、原則としてレビュアー Teammate を 1 人入れる。理由：

• オーケストレーター（Team Lead）が「設計者かつ判定者」になるのを避ける
• 3 冊跨ぎ・複数ファイル跨ぎの整合性は、独立した目で見たほうが取りこぼしが少ない
• メンタリングで自分自身が教えてきた「ガードレール 3 層」「Devil's Advocate」の実践

レビュアーの設計

1 人のレビュアー Teammate に 2 フェーズ で実行させる：

1. 整合性チェック: 既存方針（DESIGN.md / CLAUDE.md / その他規約）との齟齬、章番号・誘導リンク・命名の矛盾
2. Devil's Advocate: 「本当にその追加が必要か」「読者像／スコープから外れていないか」「既存で代替できないか」を逆張りで問う

レビュアーを 2 人に分けると視点がブレるので、1 人 2 フェーズが推奨。

レビュアーを省略してよい場合

• 出力が小規模（1 ファイルの単純編集など）
• 不可逆的な影響がない（ドラフトレベル）
• ユーザーが明示的に「レビュー不要」と言っている

3. 役割別モデル選択

| 役割 | モデル | 根拠 | |---|---|---| | 計画・設計・章立て・判断 | Opus | トレードオフ評価、整合性判断、抽象化が必要 | | 実装・調査・整理 | Sonnet | 速度重視、決められた手順の実行 | | 単純な変換・抽出・コピペ | Haiku | コスト最適化 | | レビュアー Teammate | Opus（原則） | 視点を持って判定するため |

model パラメータは明示する。省略すると agent definition の frontmatter or 親から継承で意図と異なるモデルになる可能性がある。

実行フロー（典型例）

依存ありのチーム作業の場合：

1. TeamCreate でチームを作る（名前は作業内容を表す、例: book-update-team）
2. 第 1 段の Teammate を Opus で spawn（team_name + name 付き）
3. 第 1 段完了 → 結果を見て第 2 段の Teammate に SendMessage で前提を伝える
4. 第 2 段の Teammate を並列 spawn（依存がない範囲で）
5. 全成果物が出揃ったらレビュアー Teammate を spawn（2 フェーズで実行）
6. レビュー結果を踏まえて元 Teammate に修正依頼を SendMessage
7. 最終成果物を Team Lead が統合・書き込み

アンチパターン

• 依存があるのにサブエージェント並列で済ませる: 後段が古い情報で動く
• レビュアーなしでオーケストレーターが自己レビュー: 設計者バイアスで甘くなる
• モデル省略で全部 Sonnet になる: 計画フェーズの判定が浅くなる
• チームメイトに name を付けない: SendMessage で再開できず、毎回 Agent 新規起動になる
• 作業中にチームを跨いで指示を出す: team_name を省略すると現在のチーム context に入る — 意図しないチームに紛れ込ませない

エフォートレベル別の適用範囲

現在のエフォートレベル: ${CLAUDE_EFFORT}

• low: 編成パターンの判定のみ（レビュアーの追加は省略）
• medium: 標準的な編成判定＋レビュアーの組み込み
• high/xhigh（Opus 4.7 のみ、他モデルは high にフォールバック）/max: 全ステップを完全実行（Devil's Advocate フェーズ含む）

注意事項

• このスキルは「編成パターンの決定」だけを担う。実装の詳細（具体的な SendMessage の中身や Agent への prompt）は呼び出し側のロジックに任せる
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が有効な環境を前提とする。無効な環境ではエージェントチーム機能は使えないため、サブエージェント並列にフォールバックする
• 判定に迷ったらユーザーに確認する。特に「レビュアーを入れるか省略するか」はコスト感が出るので相談したほうが良い場面がある