agent-team-orchestration

エージェントチームのオーケストレーション

明確な役割、体系化されたタスクフロー、品質ゲートを備えたマルチエージェントチームを運用するための実践ガイドです。

クイックスタート：最小構成の2エージェントチーム

ビルダーとレビュアーによる、実用的な最小構成のチームです。

1. 役割を定義する

Orchestrator (you) — Route tasks, track state, report results
Builder agent     — Execute work, produce artifacts

2. タスクを開始する

1. Create task record (file, DB, or task board)
2. Spawn builder with:
   - Task ID and description
   - Output path for artifacts
   - Handoff instructions (what to produce, where to put it)
3. On completion: review artifacts, mark done, report

3. レビュアーを追加する

Builder produces artifact → Reviewer checks it → Orchestrator ships or returns

これが基本のサイクルです。以下では、このパターンを拡張していきます。

基本概念

役割

各エージェントには、主な役割を1つ割り当てます。役割が重複すると混乱を招きます。

役割	目的	モデルの指針
オーケストレーター	作業を割り振り、状態を追跡し、優先順位を判断する	高い推論能力を備えたモデル（判断を担う）
ビルダー	コード、ドキュメント、設定などの成果物を作成する	定型作業にはコスト効率の高いモデルを使用できます
レビュアー	品質を検証し、不足点を指摘する	高い推論能力を備えたモデル（ビルダーが見落とした点を見つける）
運用担当	Cron ジョブ、定例会、ヘルスチェック、作業の割り振りを担当する	信頼性を確保できる範囲で最も低コストのモデル

→ 新しいチームを定義するときやエージェントを追加するときは、references/team-setup.md をお読みください。

タスクの状態

各タスクは、定義されたライフサイクルに沿って進みます。

Inbox → Assigned → In Progress → Review → Done | Failed

ルール：

• 状態の遷移はオーケストレーターが管理します。エージェント自身がステータスを更新することに頼らないでください。
• 遷移ごとにコメントを残します（誰が、何を、なぜ）。
• 失敗は有効な終了状態です。理由を記録して先に進みます。

→ タスクフローの設計や、停滞したタスクのデバッグを行うときは、references/task-lifecycle.md をお読みください。

引き継ぎ

エージェント間で作業を引き継ぐ際、メッセージには以下を含めます。

1. 実施内容 — 変更内容や出力の概要
2. 成果物の場所 — 正確なファイルパス
3. 検証方法 — テストコマンドまたは受け入れ基準
4. 既知の問題 — 未完了の点やリスク
5. 次の作業 — 引き継ぎ先のエージェントが行う明確な次のアクション

悪い引き継ぎ：「完了しました。ファイルを確認してください。」 良い引き継ぎ：「/shared/artifacts/auth/ に認証モジュールを作成しました。npm test auth を実行して検証してください。既知の問題：レート制限はまだ実装されていません。次の作業：レビュアーがエラーハンドリングの境界ケースを確認します。」

レビュー

役割をまたいだレビューにより、品質の低下を防げます。

• ビルダーが仕様をレビューする — 「これは実現可能ですか？不足している点はありますか？」
• レビュアーが成果物を確認する — 「仕様に合っていますか？境界ケースはどうですか？」
• オーケストレーターが優先順位をレビューする — 「今、取り組むべき作業ですか？」

レビューを省くと、3～5件のタスク以内に品質が低下します。例外はありません。

→ エージェント間の通信チャネルを設定するときは、references/communication.md をお読みください。 → 実績のある複数ステップのワークフローについては、references/patterns.md をお読みください。

リファレンスファイル

ファイル	読むタイミング
team-setup.md	エージェント、役割、モデル、ワークスペースを定義するとき
task-lifecycle.md	タスクの状態、遷移、コメントを設計するとき
communication.md	非同期／同期の通信や成果物のパスを設定するとき
patterns.md	具体的なワークフロー（仕様→構築→テスト、並行調査、エスカレーション）を実装するとき

よくある落とし穴

成果物の出力先を明確にせずにエージェントを開始する

エージェントが素晴らしい成果を出しても、見つけられないことがあります。開始時のプロンプトでは、必ず正確な出力先を指定してください。予測可能な構成の共有成果物ディレクトリを使用します。

レビュー工程がないと品質が低下する

「小さな変更だから、レビューは省略しよう。」これを3回繰り返すと、エラーが積み重なります。すべての成果物は、作成者以外の少なくとも1人の目で確認します。

エージェントがタスクの進捗をコメントしない

何も伝えないエージェントは、連携上の死角を生みます。開始時、ブロッカーの発生時、引き継ぎ時、完了時にコメントを必須にします。エージェントから応答がなくなった場合は、停滞していると考えてください。

割り当てる前にエージェントの能力を確認しない

ブラウザーにアクセスできないエージェントに、ブラウザーベースのテストを割り当てる。テキストのみのモデルに画像作業を割り当てる。作業を割り振る前に、能力を確認してください。

オーケストレーターが実行作業を行う

オーケストレーターの役割は、ルーティングと進捗管理です。作業を実行することではありません。「これをひとつだけ、さっとやろう」と思った瞬間、チームのほかのメンバーへの監督が行き届かなくなります。

このスキルを使用しない場合

• 単一エージェントの構成 — 標準的な AGENTS.md の規約に従ってください。チームのオーケストレーションは、単独のエージェントには不要なオーバーヘッドを追加します。
• 単発のタスク委任 — sessions_spawn を直接使用してください。このスキルは、複数回の引き継ぎを伴う継続的なワークフロー向けです。
• 簡単な質問の振り分け — 専門家に質問を転送するだけなら、それはメッセージであり、ワークフローではありません。

このスキルは、継続的なチームワークフロー、つまりエージェントが複数のタスクにわたって互いの成果物に依存する、繰り返し行われる協働パターン向けです。