ガイド：マルチエージェントプロジェクト
マルチエージェント協調を使うべきとき
機能が複数ドメインにまたがる場合 — バックエンドAPI + フロントエンドUI + データベーススキーマ + モバイルクライアント + QAレビュー。単一エージェントではフルスコープを処理できず、ドメインが互いのファイルを踏まずに並列進行する必要がある場合に最適です。
タスクが完全に1つのドメインに収まる場合は、特定のエージェントを直接使用してください。
全体の流れ：/plan から /review まで
Step 1：/plan — 要件とタスク分解
/plan
- 要件収集 — ターゲットユーザー、コア機能、制約、デプロイ先
- 技術的実現可能性分析 — MCP分析ツールで既存コードベースをスキャン
- APIコントラクト定義 —
.agents/skills/_shared/core/api-contracts/に保存 - タスク分解 — エージェント、タイトル、受入基準、優先度、依存関係
- ユーザーレビュー — 承認なしでは進行しない
- プラン保存 —
.agents/results/plan-{sessionId}.json
Step 2：/work または /orchestrate — 実行
| 側面 | /work | /orchestrate |
|---|---|---|
| 対話 | インタラクティブ — 各段階でユーザー確認 | 自動 — 完了まで実行 |
| PM計画 | 内蔵 | planが必要 |
| 永続モード | はい | はい |
| 最適な用途 | 初回使用、監視が必要な複雑プロジェクト | 繰り返し実行、明確なタスク |
Step 3：agent:spawn — CLIレベルのエージェント管理
oma agent:spawn backend "Implement user auth API with JWT" session-20260324-143000 -w ./api
ベンダー解決順序： --modelフラグ > model_preset (per-agent overrides via agents:) > default_cli > active_vendor > gemini
ワークスペース自動検出： モノレポ設定ファイル（pnpm-workspace.yaml、package.json、lerna.json、nx.json、turbo.json、mise.toml）をスキャンし、エージェントタイプのキーワードでスコアリング。
Step 4：/review — QA検証
OWASP Top 10セキュリティ、パフォーマンス、アクセシビリティ（WCAG 2.1 AA）、コード品質のフルパイプライン。--fixオプションで修正-検証ループ（最大3回）。
セッションID戦略
形式：session-YYYYMMDD-HHMMSS。メモリファイル、PIDファイル、ログファイル、結果のグループ化に使用。
ワークスペース割り当て
自動検出
| エージェントタイプ | キーワード（優先順） |
|---|---|
| frontend | web, frontend, client, ui, app, dashboard |
| backend | api, backend, server, service, gateway |
| mobile | mobile, ios, android, native, rn, expo |
フォールバック候補
- frontend：
apps/web、apps/frontend、frontend、web - backend：
apps/api、apps/backend、backend、api - mobile：
apps/mobile、mobile、app
コントラクトファーストルール
APIコントラクトはエージェント間の同期メカニズムです：
- 実装前にコントラクトを定義
- 各エージェントが関連コントラクトをコンテキストとして受信
- コントラクトがインターフェース境界を定義（メソッド、パス、スキーマ、認証、エラー形式）
- モニタリング中にコントラクト違反を検出
- QAレビューでコントラクト準拠を確認
マージゲート：4つの条件
- ビルド成功 — 全コードがエラーなしでコンパイル
- テストパス — 既存テストの継続パスと新テスト
- 計画ファイルのみ変更 — スコープ外の変更なし
- QAレビュークリア — CRITICALとHIGHの指摘なし
アンチパターン
- 計画のスキップ —
/orchestrateにplanなしは拒否される - ワークスペースの重複 — 同ディレクトリに2エージェントでファイル競合
- APIコントラクト未定義 — 互換性のないデータ形式
- QA指摘の無視 — CRITICAL/HIGHは本番で発覚するバグ
- 手動ファイル協調 — 自動パイプラインの方が確実
- 過剰並列化 — P0完了前にP1を実行しない
- 検証のスキップ — ビルド失敗やスコープ違反の伝播
クロスドメイン統合検証
- APIコントラクト整合性 — バックエンド実装がフロントエンド/モバイルのコントラクトに一致
- 型の一貫性 — TypeScript型、Pythonデータクラス、Dartモデルのフィールド名一致
- 認証フロー — JWT送信、トークン保存、リフレッシュの整合性
- エラーハンドリング — 全クライアントが文書化されたエラー形式を処理
- データベーススキーマ整合性 — ORMモデルとスキーマの一致
完了条件
- すべてのエージェントが全優先度ティアで正常完了
- 検証スクリプトがすべてパス
- QAレビューでCRITICALとHIGHがゼロ
- クロスドメインAPIコントラクト整合性が確認済み
- ビルド成功・テストパス
- 最終レポートがメモリに記録
- ユーザーの最終承認