msd-core/docs/ja-JP/explanation/multi-agent-orchestration.md

GSD Core におけるマルチエージェントオーケストレーション

解説 — このドキュメントは、GSD Core がマルチエージェントオーケストレーションを中心に設計されている 理由 と、各部品がどのように組み合わさるか を説明します。ステップバイステップのガイドではありません。設定については、モデルプロファイルの設定 と 設定リファレンス を参照してください。完全なエージェントロスターについては、インベントリ を参照してください。

---

この設計が解決する問題

AI コーディングエージェントは劣化します。モデルが悪くなるからではなく、コンテキストウィンドウが満杯になる からです。会話が大きくなるにつれて、以前の決定やコードは中間ステップのノイズによって押し出されるか薄められます。複雑なタスクで 5 番目のファイルを書く頃には、エージェントは最初のメッセージで述べた制約をすでに忘れているかもしれません。これは コンテキスト腐敗 と呼ばれることがあります。

GSD Core のマルチエージェント設計はその問題への直接的な応答です。セッション全体を抱える一つの長期実行エージェントの代わりに、薄いオーケストレーターが短命の専門化されたエージェントを生成します。それぞれが フレッシュな 200K トークンのコンテキストウィンドウ と、自分の特定の仕事をするために必要な アーティファクトだけ を持ちます。オーケストレーターは自分では重い作業をしません。コンテキストを読み込み、適切なエージェントを生成し、結果を収集し、.planning/ の共有状態を更新します。

---

オーケストレーター → エージェントパターン

gsd-core/workflows/ のすべてのワークフローは同じ形を持ちます：

Orchestrator（ワークフロー .md ファイル）
    │
    ├── コンテキスト読み込み
    │   gsd-tools.cjs init <workflow> <phase>
    │   → JSON: プロジェクト情報、設定、状態、フェーズ詳細
    │
    ├── モデル解決
    │   gsd-tools.cjs resolve-model <agent-name>
    │   → opus | sonnet | haiku | inherit
    │
    ├── 専門化エージェント生成（Task/SubAgent 呼び出し）
    │   ├── エージェント定義（agents/*.md）
    │   ├── コンテキストペイロード（init JSON）
    │   ├── モデルアサイン
    │   └── ツール権限
    │
    ├── 結果収集
    │
    └── 状態更新
        gsd-tools.cjs state update / state patch / state advance-plan

オーケストレーターは意図的に薄く保たれています。ドメインについて推論せず、コードを書かず、次のステップへルーティングする以上に結果を解釈しません。この境界により各レイヤーの責任が明確になり、オーケストレーターのコンテキストにドメインノイズが蓄積するのを防ぎます。

エージェントロスター

GSD Core のエージェントは、調査 → 計画 → 実行 → 検証パイプラインにマッピングされる機能カテゴリに分類されます：

カテゴリ	エージェント	典型的な並列性
調査者	gsd-project-researcher、gsd-phase-researcher、gsd-ui-researcher、gsd-advisor-researcher	4 並列（スタック、機能、アーキテクチャ、落とし穴）
合成者	gsd-research-synthesizer	調査者完了後、順次実行
プランナー	gsd-planner、gsd-roadmapper	順次実行
チェッカー	gsd-plan-checker、gsd-integration-checker、gsd-ui-checker、gsd-nyquist-auditor	順次実行、最大 3 回の修正反復
エグゼキューター	gsd-executor	ウェーブ内並列、ウェーブ間順次
検証者	gsd-verifier	すべてのエグゼキューター完了後、順次実行
マッパー	gsd-codebase-mapper	4 並列サブプローブ
監査者	gsd-ui-auditor、gsd-security-auditor	順次実行

各エージェント定義（agents/*.md 内）は、許可されたツールアクセス、目的、ターミナル出力の色を宣言します。ファイルを読み取り、単一の出力ドキュメントを書くだけでよいエージェントには、まさにその権限だけが与えられます——Bash 実行なし、より広い状態へのアクセスなし。この制約は意図的です：エージェントが予期しない動作をした場合の影響範囲を小さく保ちます。

完全な 31 エージェントロスターについては、インベントリ を参照してください。

---

ウェーブベースの並行実行

マルチエージェント設計の最も目に見える表れは、/gsd-execute-phase が互いに依存しあうことのある計画セットをどう処理するかです。

エグゼキューターを生成する前に、オーケストレーターは ウェーブ分析 を実行します：各 PLAN.md ファイルの依存関係宣言を読み取り、計画をウェーブにグループ化します。宣言された依存関係がない計画がウェーブ 1 を形成し、並列に実行されます。ウェーブ 1 に依存する計画がウェーブ 2 を形成し、以下同様です。

Plan 01（依存なし）        ─┐
Plan 02（依存なし）        ─┤─── ウェーブ 1（並列）
Plan 03（依存: 01）        ─┤─── ウェーブ 2（ウェーブ 1 待ち）
Plan 04（依存: 02）        ─┘
Plan 05（依存: 03, 04）    ─── ウェーブ 3（ウェーブ 2 待ち）

ウェーブ内の各エグゼキューターは：

• フレッシュなコンテキストウィンドウ（200K トークン、または対応モデルでは最大 1M）を受け取る
• 担当する特定の PLAN.md を受け取る
• プロジェクトコンテキスト（PROJECT.md、STATE.md）を受け取る
• フェーズコンテキスト（CONTEXT.md、利用可能な場合は RESEARCH.md）を受け取る
• 完了時にアトミックな git コミットを生成する
• 構築したものを説明する SUMMARY.md を書く

ウェーブ内のすべてのエグゼキューターが完了した後、オーケストレーターはウェーブ全体のプリコミットフックを一度実行します。エグゼキューターは --no-verify でコミットし、複数のエージェントが並行してコミットするときのビルドロック競合（たとえば Rust プロジェクトでの Cargo ロック競合）を防ぎます。したがってフックはコミットごとに一度ではなく、ウェーブごとに一度実行されます。

並行コミットの安全性

複数のエグゼキューターが同時に実行される場合、2 つのメカニズムが書き込み競合を防ぎます：

1. STATE.md へのアトミックロック — STATE.md へのすべての書き込みはロックファイル（STATE.md.lock）と O_EXCL アトミック作成を使います。これにより、2 つのエージェントそれぞれがファイルを読み取り、異なるフィールドを変更し、後から書いた方が前の変更を上書きするという read-modify-write 競合が防止されます。古いロック（10 秒以上）は自動的にクリアされます。

2. ウェーブごとのフック実行 — 各エグゼキューターがプリコミットフックを独立して実行する代わりに（共有ビルドアーティファクトでファイルレベルの競合を引き起こす可能性がある）、オーケストレーターは各ウェーブが完了した後に git hook run pre-commit を一度実行します。

---

大窓モデルへのアダプティブコンテキスト拡充

標準の 200K コンテキストウィンドウは、エグゼキューターが単一の集中した計画を実装するには十分です。設定された context_window が 500K トークン以上の場合（たとえば Opus 4.6 または Sonnet 4.6 を 1M クラスモードで使用する場合）、オーケストレーターは標準ウィンドウでは収まらない追加コンテキストでサブエージェントプロンプトを自動的に拡充します：

• エグゼキューターエージェント は前のウェーブの SUMMARY.md ファイルとフェーズの CONTEXT.md/RESEARCH.md を受け取り、フェーズ内でのクロスプラン認識を得る
• 検証者エージェント はすべての PLAN.md、SUMMARY.md、CONTEXT.md ファイルと REQUIREMENTS.md を受け取り、履歴を考慮した検証が可能になる

この拡充は config.json の context_window の値に条件付きです。標準ウィンドウ設定では、プロンプトはトークン効率を最大化するためにキャッシュフレンドリーな順序で切り詰められたバージョンを使います。

---

なぜこの設計か——コンテキストエンジニアリングとの関連

オーケストレーター → エージェントパターンは、コンテキストエンジニアリング というより広いアプローチの一部としてのみ意味を持ちます：AI エージェントがコンテキストウィンドウで受け取るものが、モデルの層やプロンプト品質と同じくらい重要だという考え方。完全な解説については コンテキストエンジニアリング を参照してください。

マルチエージェントオーケストレーションはコンテキストエンジニアリングを 2 つの方法で実装します：

コンテキストの分離。 各エージェントは必要なものだけを受け取ります。調査者はプロジェクト説明とドメイン質問を受け取ります；完全な計画履歴は受け取りません。検証者はすべての計画とサマリーを受け取ります；生の調査は受け取りません。分離により各エージェントのコンテキストは他のパイプラインステージのノイズで薄まるのではなく、シグナルで密度が高く保たれます。

セッションをまたいだコンテキストの衛生。 すべての状態は（エージェントのコンテキストウィンドウではなく）.planning/ に人間が読める Markdown と JSON として存在するため、GSD ワークフローはコンテキストリセット（/clear）、タブ切り替え、複数日のブレークを超えて生き残ります。次のエージェントは常に、長い会話の再構築された記憶からではなく、永続化され検証されたアーティファクトから開始します。

---

トレードオフ

マルチエージェントオーケストレーションはタダではありません。

調整オーバーヘッド。 各エージェントの生成はラウンドトリップです：オーケストレーターがプロンプトをフォーマットし、コンテキストを渡し、サブエージェントが完了するまで待ち（通常 1〜5 分）、結果を解析する必要があります。一つのコンテキストで作業する一つの有能なエージェントは、シンプルなタスクをより速く終わらせるでしょう。GSD は依存関係が許す限りデフォルトで並列性を採用することでこれを軽減します——plan-phase の 4 人の調査者は順次ではなく同時に実行されます。

実行中の不透明性。 サブエージェントの実行中は、その作業は親セッションには見えません。ライブの進捗ストリームはありません。これはフレッシュコンテキスト設計の意図的な帰結です：サブエージェントは自分自身のコンテキストウィンドウで動作しています。オーケストレーターは生成ラインに生存通知を表示します（「サブエージェントで実行中——返ってくるまで出力なし」）で期待値を設定します。

コンテキストスティッチングコスト。 各エージェントに適切なアーティファクトをパッケージ化するには、オーケストレーターがコンテキストペイロードを組み立てて送信するためにトークンを使う必要があります。これが分離のコストです。gsd-tools.cjs init ハンドラーは、完全性とトークン予算のバランスを取る JSON ペイロードを生成し、繰り返し呼び出しでキャッシュにヒットするようにペイロードの安定した部分（プロジェクト定義、設定）にキャッシュフレンドリーな順序を適用します。

モデルコストの増幅。 Opus 層で 5 つのエージェントを並行して実行することは、1 つを実行するよりコストがかかります。モデルプロファイルシステム（model_profiles.md、model-profiles.cjs でエージェントごとに解決）により、重要度の低いエージェントに安価な層を割り当てることができます。dynamic_routing 機能は、すべてのエージェントを安価な層で開始し、ソフトフェイラー時にのみエスカレートすることでさらにコストを削減します。詳細なオプションについては 設定 を参照してください。

これらのコストの見返りとして、この設計は大きなフェーズにわたる一貫した品質を買います。400 行の計画で 10 番目のファイルを書くエグゼキューターは、コンテキストがフレッシュだから劣化しません。20 の要件を確認する検証者は、すべてを会話履歴ではなく構造化された入力として受け取ったから最初の 10 を忘れません。

---

Related

• コンテキストエンジニアリング — この設計を動機づける上流の原則
• モデルプロファイルの設定 — エージェントごとにモデル層を割り当てる方法
• 設定リファレンス — models、model_overrides、dynamic_routing、context_window を含む完全な config.json スキーマ
• インベントリ — 信頼できるエージェントロスターとワークフローリスト
• アーキテクチャ — オーケストレーター → エージェントパターンとウェーブ実行モデルの実装レベルの詳細
• ドキュメント索引