agent-orchestrator

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

概要

マルチエージェントの作業をエンドツーエンドで調整します。監査と修正を委任し、結果を調整し、品質ゲートを適用して、検証済みの成果を提供します。

次の基本パターンに従います。クラスターごとに新しい実装者を割り当て、その後、2段階のレビュー（最初に仕様への準拠、次にコード品質）を行います。

譲れないルール：変更を決して直接実装しないでください（コーディングやファイル編集は禁止です）。

エージェントの役割

以下の役割が環境で利用できるものとします。 エージェントの定義や設定は編集しないでください。必要な役割がない場合は、作業を中断してオペレーターに設定を依頼してください。

• architect（設計／意思決定／契約）
• auditor（読み取り専用の問題発見。修正は行わない）
• explorer / scout（読み取り専用のリポジトリ検索）
• worker（汎用ヘルパー）
• implementer（コードとテスト）
• spec_reviewer（読み取り専用、PASS/FAIL：不足も余分もないこと）
• quality_reviewer（読み取り専用、PASS/FAIL：保守性とテスト品質）

ワークフロー

1. サブタスクに直接合致するスキルを使用します

   • スキルがタスクに合致する場合は、明示的に実行して従ってください（例：$web-fetch-to-markdown <url>）。
   • 作業を委任する際は、プロンプトでサブエージェントに使用するスキルを伝えてください（例：「コミット作業には $commit を使用してください。」）。

2. スコープと成功基準を明確にします

   • ミッション、制約、「完了」の基準を具体的に言い直します。
   • 信頼できる情報源（ドキュメントや仕様）を特定し、どの主張に証拠が必要かを記録します。

3. フェーズ計画を作成し、最新の状態を保ちます

   • 環境の計画機能（利用可能であれば update_plan など）を使ってフェーズを追跡し、作業の逸脱を防ぎます。
   • 4〜7 ステップを目安とし、進行中のステップは常に 1 つだけにします。

4. サブシステムに分割します

   • 独立して監査できるサブシステム（API サーフェス、コアロジック、エラー処理、パフォーマンス、連携、テスト、ドキュメントなど）を選びます。
   • 各サブシステムについて、常に満たすべき不変条件を 2〜5 個定義します。

5. サブシステムごとに、独立した 2 回の監査を実施します

   • サブシステムごとに、独立した監査担当エージェントを 2 つ（auditA と auditB）起動します。
   • リスクが高い作業や微妙な判断を要する作業では、監査の前にサブシステムの範囲を絞り、不変条件と証拠要件を強化します。
   • 照合まで互いに連絡を取らず、独立して作業するよう指示します。
   • 問題の指摘にはすべて証拠を求めます（リポジトリ内の場所、再現手順、期待値と実際の結果、重大度）。

6. 監査結果を照合し、確認済みの問題リストにまとめます

   • auditA と auditB の結果を比較し、双方で確認された問題のみを残します。見解が分かれた問題は、explorer を使って独立に検証します。
   • 却下した候補には、簡潔な理由を記録します（証拠が不十分、スコープ外、再現性がないなど）。
   • この照合済みリストのみを実装作業の根拠とします。
   • 照合結果には以下を含めます。
     • 確認済みの問題（双方で確認されたもののみ）
     • 却下した候補（理由）
     • 合意に達したか：はい／いいえ

7. 明確な担当範囲を設け、問題をまとめて実装します

   • 確認済みの問題を、依存関係を最小限に抑えられる単位にまとめます。
   • 各単位につき、実装担当エージェントを 1 つだけ起動します。
   • 各実装担当者に担当ファイルを割り当て、大規模なリファクタリングを避けるよう求めます。
   • 単位ごとの作業を自分で実装してはいけません。小さな変更であっても、必ず実装担当者に委任します。
   • すべての修正に、適切な回帰テスト（ユニット、統合、E2E）を追加します。
   • 各単位について、以下の 2 段階のレビューループを実施します。
     • 実装担当者に、テストとセルフレビューを含めて作業を完了させ、変更内容を報告してもらいます。
     • spec_reviewer がコードを読んで「過不足がないこと」を検証します（報告を鵜呑みにしないでください）。
     • 仕様への準拠に合格した後にのみ、quality_reviewer が保守性とテストの品質を検証します。
     • いずれかのレビューが不合格の場合は、具体的なフィードバックを実装担当者に伝え、不合格となったレビュー段階を再度実施します。

8. レビューゲートを徹底します

   • 仕様への準拠とコード品質の両方について、具体的な参照箇所を伴う合格記録がない限り、単位をマージまたは反映してはいけません。

9. 統合して検証します

   • リポジトリ標準の検証（テスト、Lint、ビルド、型チェック）を実行します。
   • 明確なコマンドがない場合は、README、package.json、pyproject.toml、CI 設定などから確認します。

10. 簡潔な完了報告を提出します

    • 現時点で利用できるものを説明します。
    • 意図的に未対応としている内容と、次の手順や課題を説明します。
    • 実行したコマンド（少なくとも主要な検証コマンド）とその結果を列挙します。

サブエージェントへの依頼内容

メッセージはタスクに即した簡潔な内容にしてください。一般的な役割の説明を繰り返さず、そのタスクに集中します。

監査、レビュー、実装を依頼するメッセージには、以下を含めてください。

• 目標と成功基準（「完了」の定義）
• スコープの境界／担当ファイル（変更対象と対象外）
• 不変条件（満たすべき条件を 2〜5 個）
• 実行するコマンド（判明している場合）と、収集する証拠