s977043/codex-multi-agent

Multi-Agent Operating Guide

複数 agent を使って作業するときの共通運用ルール。

このスキルの中心はツール依存の操作手順ではなく、次の判断基準にある。

• いつ委譲するか
• どう分割するか
• 何を並列化してよいか
• 主担当がどう統合するか

Iron Law

今すぐ主担当が自分でやるべき作業は委譲しない

• 直後の意思決定に必要な調査や編集は主担当が自分で行う
• サブエージェントには、独立して進められる具体的なタスクだけを渡す
• 委譲は目的ではなく手段である。分割すると遅くなるなら分割しない

使う場面

• 実装と調査を並列で進めたい
• フロントエンド / バックエンド / テストを役割分担したい
• 読み取り専用の影響調査を別 agent に切り出したい
• レビューや検証を独立した agent に任せたい
• 大きなタスクを分割して、最後に主担当が統合したい

使わない場面

• 単純な 1 ファイル修正
• すぐに主担当が判断すべき設計変更
• 強く結合した変更で、分割すると手戻りが増える場合
• 「とりあえず並列化したい」だけで、独立タスクがない場合

Step 1: 主担当が先に決める

委譲前に、主担当が以下を自分で確定する。

1. ユーザー要求の要約
2. クリティカルパスの特定
3. 並列化できる独立タスクの抽出
4. 自分が今すぐ着手する作業の決定

ここが曖昧なまま委譲しない。

Step 2: タスクを分解する

サブエージェントに渡すタスクは、次の条件を満たすものだけにする。

• 入力が明確
• 完了条件が明確
• 変更範囲または責務が明確
• 主担当の直後の作業をブロックしない

良い例:

• 「app/admin 配下でこの UI に関係する既存パターンを 3 点探して報告する」
• 「Laravel 側の既存 API とテスト配置を調査し、変更候補ファイルを列挙する」
• 「この 2 ファイルだけを担当して型エラーを直す」

悪い例:

• 「いい感じに全部進めて」
• 「必要そうなものを全部見て実装して」
• 「まず調べて、必要なら設計して、実装して、レビューして」

Step 3: 役割を選ぶ

まず役割で考え、ツールごとの agent 名は後で割り当てる。

| 役割 | 使いどころ | | --- | --- | | planner | 要件整理、タスク分解、依存関係整理 | | researcher | 既存コード調査、影響範囲調査、読み取り専用分析 | | frontend-dev | UI / コンポーネント実装 | | backend-dev | API / ドメイン / リポジトリ実装 | | database | DB スキーマ、マイグレーション設計 | | tester | テスト設計、テスト追加、検証観点整理 | | debugger | 不具合原因調査、再現条件の切り分け | | reviewer | セキュリティ、性能、品質レビュー | | docs | ドキュメント整備 | | ops | Docker / CI / インフラ運用作業 |

迷ったら:

• 調査は researcher
• 実装は該当ドメインの *-dev
• テストは tester
• 計画は planner

Step 4: チーム規模を決める

必要最小人数で始める。人数を増やす基準は「仕事量」ではなく、独立した責務があるかどうか。

ここでの人数は、主担当 を含む総人数の目安を指す。 reviewer は抽象ロールであり、必要に応じて 1 agent でも複数 agent でもよい。ツール別の実体への割り当ては末尾の Tool Mapping を使う。

• 小規模（2-3 agent）: 調査 + 実装、単機能修正、局所的なレビュー
• 中規模（3-4 agent）: frontend-dev / backend-dev / tester の並列、または調査 + 実装 + レビュー
• 大規模（4-5 agent）: planner を含めた設計整理、複数レイヤーの実装、独立レビューの同時進行

増やしすぎの兆候:

• 各 agent の担当範囲を 1 行で説明できない
• 同じファイルや同じ意思決定を複数 agent が共有している
• 主担当が統合よりも調整に時間を取られている

迷ったら、1 段階小さい規模から始める。

Step 5: 並列化の判断

並列化してよいのは、互いに独立していて、成果物の衝突が小さいタスクだけ。

並列化しやすい組み合わせ

• researcher に調査を任せつつ、主担当が別の読み取りや軽い実装を進める
• backend-dev と frontend-dev が API 契約済みの範囲で並列実装する
• 実装と tester のテスト観点整理を並列で進める
• 実装後に reviewer へ独立レビューを出す

並列化しにくい組み合わせ

• 同じファイルを複数 agent が触る
• API 仕様未確定のまま frontend / backend を同時着手する
• 設計未確定のまま複数 worker に実装させる

Step 6: 委譲プロンプトの作り方

各 agent には、最低限以下を渡す。

目的:
- 何のための作業か

担当範囲:
- 読み取りだけか、編集ありか
- 対象ファイル/モジュール

完了条件:
- 何を返したら完了か

制約:
- 既存パターン準拠
- 触ってよい範囲
- 他 agent の変更を巻き戻さない

コード変更を任せる場合は、担当ファイルを明示する。

あなたの担当:
- `app/admin/src/...`
- `packages/shared-components/...`

注意:
- あなたは単独作業ではない
- 他者の変更を revert しない
- 変更したファイルパスを最後に列挙する

Step 7: 運用ルール

• 具体的で自己完結した依頼だけを渡す
• 書き込み担当のスコープを明示する
• 同じ未解決タスクを重複委譲しない
• 既存 agent を再利用するのは、その文脈が活きるときだけ
• 待機を増やさず、待ち時間は主担当が別作業を進める
• 結果統合後、不要になった agent は閉じるか運用上の完了状態にする

推奨パターン

1. 調査 + 実装

主担当:
- クリティカルパスの実装を開始

researcher:
- 既存パターン、影響範囲、変更候補を調査

2. フルスタック並列

planner:
- 変更単位と依存関係を整理

backend-dev:
- API / UseCase / Repository を担当

frontend-dev:
- API 契約に基づく UI 実装を担当

tester:
- 受け入れ条件に沿ったテスト観点を整理

3. 実装 + 並列レビュー

主担当または implementation owner:
- 実装を完了

reviewer:
- セキュリティ / パフォーマンス / テスト不足を確認

出力フォーマット

必要に応じて、委譲前に次を短く整理してから実行する。

チーム構成

| 役割 | 担当 | スコープ | | --- | --- | --- | | planner | 依存整理 | 計画のみ | | backend-dev | API 実装 | バックエンド | | frontend-dev | UI 実装 | フロントエンド | | tester | テスト観点整理 | テストのみ |

依存関係

Task A: API 契約確定
Task B: バックエンド実装
Task C: フロントエンド実装
Task D: テスト確認

A → B
A → C
B, C → D

統合時のルール

• サブエージェントの結果を鵜呑みにせず、主担当が最終判断する
• 競合や設計不整合は主担当が解消する
• 最終報告は、誰が何を担当したかではなく、ユーザー成果を中心にまとめる

アンチパターン

• 主担当が空になり、待機ばかりする
• 曖昧な依頼を複数 agent に投げる
• 直列で十分な作業まで無理に並列化する
• 同一ファイルを複数 worker に触らせる
• レビュー結果を統合せず、そのまま羅列する

Tool Mapping: Codex

Codex では、役割を次のように割り当てる。

| 役割 | Codex の agent | | --- | --- | | planner | project_planner | | researcher | explorer_agent | | docs | documentation_writer | | skill-design | skill_designer | | conductor | workflow_conductor | | orchestrator | orchestrator | | reviewer (bridge) | claude_code_reviewer |

上記は PlanGate フレームワークの標準構成。 プロジェクト固有の specialist agent（frontend, backend, tester 等）は導入先リポジトリで追加する。

Codex での代表的な操作:

• 新規委譲: spawn_agent
• 継続指示: send_input
• 必要時のみ待機: wait_agent
• 不要になったら終了: close_agent

Tool Mapping: Claude Code

Claude Code では、役割を既存の Team / Task 運用へ読み替える。

• チーム設計・メンバー構成は setup-team の手順に読み替える
• 役割名は researcher, backend-dev, frontend-dev, tester などのまま使ってよい
• Team / Task ツール上の member 種別や owner 設定は、上の役割表を基準に割り当てる

Claude Code 側では、ツール固有のチーム操作は setup-team を参照する。

関連スキル

• setup-team: Claude Code の Team / Task ベース運用
• subagent-driven-development: 実装タスクを委譲して二段階レビューを回すときに併用