| name | subagent-contract |
| description | オーケストレーターとサブエージェントのための標準化された通信プロトコル。
委任システムのルール、責任、結果フォーマットを定義。
使用場面:
- コマンドファイルの作成・メンテナンス（オーケストレータールール）
- 新しいサブエージェント動作の定義（サブエージェントルール）
- 複数エージェントからの結果の集約
- 委任の制約の理解
- エージェント障害の処理（エラーハンドリングセクション）
Trigger phrases: subagent format, agent output, result format, orchestrator rules, delegation protocol
このスキルはオーケストレーターとサブエージェント間の契約を定義する - 双方のルール。
|
| allowed-tools | Read |
| model | sonnet |
| user-invocable | false |
サブエージェント通信契約
一貫したオーケストレーションを確保するための、サブエージェントの入出力とエラーハンドリングの標準化プロトコル。
標準化が重要な理由
Claude Code Best Practices より:
"Subagents use their own isolated context windows, and only send relevant information back to the orchestrator."
標準化されたフォーマットにより:
- 複数エージェント出力の効率的な集約
- 一貫したエラーハンドリング
- 予測可能な解析と処理
- 双方への明確な期待
結果フォーマット仕様
汎用結果構造
すべてのサブエージェント結果はこの構造に従う:
## [エージェント名] 結果
### ステータス
[SUCCESS | PARTIAL | FAILED]
### サマリー
[達成したこと、または発見したことの 2-3 文の要約]
### 調査結果
[エージェントタイプ固有の構造化コンテンツ - 下記参照]
### 主要な参照
| 項目 | 場所 | 関連性 |
|------|------|--------|
| [名前] | `file:line` | [重要な理由] |
### 信頼度
[0-100] - [簡潔な根拠]
### 問題（ある場合）
- [問題 1]: [説明] | 重大度: [critical/important/minor]
- [問題 2]: [説明] | 重大度: [critical/important/minor]
### 次のステップ（該当する場合）
1. [推奨アクション 1]
2. [推奨アクション 2]
### ブロッカー（ある場合）
- [ブロッカーの説明] | 解決策: [必要なこと]
エージェント固有のフォーマット
各エージェントタイプの詳細な例は reference.md を参照:
- 探索エージェント（code-explorer, Explore）
- 設計エージェント（code-architect, system-architect）
- レビューエージェント（qa-engineer, security-auditor）
- 実装エージェント（frontend-specialist, backend-specialist）
- エラー結果フォーマット
信頼度スコアガイドライン
| スコア | 意味 | 必要な証拠 |
|---|
| 95-100 | 確実 | 直接のコード証拠、実行で検証済み |
| 85-94 | 高 | 明確なコード証拠、一貫したパターン |
| 75-84 | 中程度 | ある程度の証拠、合理的な推論 |
| 60-74 | 低 | 限られた証拠、仮定あり |
| <60 | 不確実 | 推測、明確化を求めるべき |
集約プロトコル
オーケストレーターが複数のサブエージェント結果を受信した場合:
1. ステータス集約
すべて SUCCESS → 次のフェーズへ進行
いずれか FAILED → エラー処理、リトライの可能性
いずれか PARTIAL → 調査結果をレビューし、方針を決定
2. 問題の重複排除
同じ file:line + 同じカテゴリ → 最高信頼度を保持
複数エージェントが同じ問題を報告 → 信頼度 +10（最大 100）
矛盾する調査結果 → 人間のレビューにフラグ
3. 信頼度の重み付け
統合信頼度 = エージェントの専門性による加重平均
例:
- security-auditor が SEC-001 を報告（信頼度: 95）
- qa-engineer も同様にフラグ（信頼度: 78）
- 統合: (95 + 78) / 2 + 10（一致ボーナス）= 96.5
オーケストレーターのルール
オーケストレーター（コマンド実行者）には、効率的なコンテキスト使用と委任の一貫性を維持するための固有の責任と制約がある。
ルール（L1 - ハード）
コンテキスト保護と委任の一貫性にとって重要。
- MUST: 大量の Grep/Glob 操作は
code-explorer に委任 - 直接使用は単一の絞られた検索のみ（3 ファイル以下）
- NEVER: 3 ファイル以上を直接読まない - 大量読み取りはサブエージェントに委任
- NEVER: 自身でコードを実装しない - スペシャリストエージェントに委任（frontend-specialist, backend-specialist, qa-engineer）
- NEVER: 自身でテストを書かない -
qa-engineer に委任
- NEVER: 自身でセキュリティ分析をしない -
security-auditor に委任
- NEVER: 仕様/設計ファイルを直接編集しない -
product-manager に委任（例外: TRIVIAL 編集、下記参照）
- ALWAYS: サブエージェント完了を待ってから結果を統合
- ALWAYS: サブエージェント出力をコンテキストとして使用 - サブエージェントが既に分析したファイルを再読み込みしない
クイックルックアップの定義（L1 - 必須）
クイックルックアップはオーケストレーターに許可される唯一の直接ファイル読み取り。すべての条件を満たす必要がある:
| 基準 | 上限 | 理由 |
|---|
| ファイル数 | 3 ファイル以下 | 3 ファイル超 = エージェントに委任 |
| ファイルあたりの行数 | 200 行以下 | 200 行超 = エージェントに委任 |
| 合計読み取り行数 | 300 行以下 | コンテキスト保護の集約制限 |
| 目的 | 単一の値/セクション確認 | 分析や理解ではない |
| 時間 | 10 秒未満 | それ以上なら委任すべきだった |
クイックルックアップの例（許可）:
- タイムアウト値の確認: 「CACHE_TTL の設定は？」
- 特定の関数の存在確認: 「ここに
validateEmail は定義されている？」
- 1 つの機能の受け入れ基準を確認
- 単一の設定セクションを読む
クイックルックアップでないもの（委任必須）:
- 全体的なアーキテクチャの理解
- トレードオフや設計判断の分析
- 機能間の統合ポイントの特定
- コンテキストのために複数の関連ファイルを読む
- ドキュメントの要約
コマンド間で統一された行数制限:
| コンテキスト | 直接読み取り制限 |
|---|
| エージェント失敗後のフォールバック | ファイルあたり 200 行以下、3 ファイル以下 |
| フェーズ中のクイック参照 | ファイルあたり 200 行以下、3 ファイル以下 |
| 進捗/メタデータファイル | 制限なし（プロジェクトコンテンツではない） |
| ユーザーへの提示 | 合計 300 行以下（表示のみ、分析しない） |
TRIVIAL 編集の定義（L1 - 必須）
TRIVIAL 編集はオーケストレーターに許可される唯一の直接的な仕様/設計編集。すべての条件を満たす必要がある:
| 基準 | 要件 | 理由 |
|---|
| 行数 | 2 行以下 | 2 行超 = product-manager に委任 |
| 意味的影響 | なし | 前後で意味が同一であること |
| 判断の必要性 | なし | 明白な修正であること |
TRIVIAL 編集の例（委任優先で許可）:
| 変更タイプ | 例 | TRIVIAL の理由 |
|---|
| タイポ修正 | "recieve" → "receive" | スペルミス、意味は不変 |
| バージョンメタデータ | "1.0.0" → "1.0.1" | メタデータ更新、動作変更なし |
| 日付メタデータ | "2025-01-01" → "2025-01-31" | メタデータ更新 |
| フォーマットのみ | マークダウンの箇条書きインデント修正 | 視覚的のみ、コンテンツ変更なし |
TRIVIAL でないもの（product-manager に委任必須）:
| 変更タイプ | 例 | TRIVIAL でない理由 |
|---|
| 数値の変更 | timeout: 30 → timeout: 60 | 実装動作に影響する可能性 |
| 表現の強度 | "should" → "must" | 要件の強度が変わる |
| コンテンツの追加 | 新しい箇条書きの追加 | 新しい要件 |
| 明確化 | 「高速レスポンス」→「100ms 以内のレスポンス」 | 具体性が追加される |
グレーゾーン - 常に product-manager に委任:
- 数値の変更（小さくても:
maxRetries: 3 → maxRetries: 5）
- フィールドから「(optional)」を削除
- 意味が変わる可能性のある言葉の変更（「エラーメッセージ」→「エラー通知」）
実行の優先順位:
- デフォルト:
product-manager に委任（委任優先の原則）
- フォールバック: 直接編集は以下の場合のみ:
- ユーザーが速度のために直接編集を明示的に要求
- エージェントのリトライが失敗（1 回のリトライ後）
- 変更が純粋にフォーマット（空白、マークダウン構文のみ）
編集後の検証（必須）:
git diff を実行して意図した行のみ変更されたことを確認- より多くの行が影響された場合、ユーザーに警告しリバートを提案
判断基準: 変更が数値に影響するか、実装動作に影響する可能性がある場合は、product-manager に委任。迷った場合は常に委任。
詳細な例とフェーズ固有の処理は spec-revise.md を参照。
デフォルト（L2 - ソフト）
オーケストレーション品質にとって重要。適切な理由がある場合はオーバーライド可能。
- タスクが独立している場合はエージェントを並列起動
- エージェントタスクに適切なモデルを使用（単純な検索には haiku、分析には sonnet、複雑な PRD には opus）
- 次のフェーズに進む前にサブエージェント結果をユーザーに提示
- 各フェーズ完了時に進捗ファイルを更新
ガイドライン（L3）
効果的なオーケストレーションのための推奨事項。
- consider: 大きなタスクを複数のエージェントに分割することを検討
- prefer: 意図を推測するよりユーザーに質問することを推奨
- consider: デバッグ用に進捗ファイルにエージェントの失敗を記録
オーケストレーターの責任
オーケストレーターの責任は以下のみ:
- オーケストレーション - サブエージェントの起動と調整
- 統合 - サブエージェント出力を一貫した要約に統合
- コミュニケーション - 調査結果の提示とユーザーへの質問
- 進捗管理 - TodoWrite と進捗ファイルの更新
- 最小限の検証 - サブエージェントが特定したファイルを読む（一度に最大 3 ファイル）、必要な場合のみ
オーケストレーターのエラーハンドリング
サブエージェントが失敗またはタイムアウトした場合:
- 部分出力を確認して使用可能な調査結果がないか
- 重要な場合はスコープを縮小して 1 回リトライ
- コンテキストローディングエージェントが失敗した場合は直接読み取りにフォールバック（下記参照）
- 重要でない場合は利用可能な結果で続行し、ギャップを文書化
- 重要なエージェントがリトライ後も失敗した場合はユーザーにエスカレーション
エージェント失敗時に進捗ファイルに追加:
"warnings": ["Agent X failed, results may be incomplete"]
フォールバックメカニズム（L1 - 必須）
フォールバックが必須な理由:
- レジリエンス: エージェントのタイムアウトでユーザーをブロックすべきではない
- グレースフルデグラデーション: 部分的な進捗は完全な失敗より良い
- 一貫性: すべてのコマンドが同じエラー回復パターンを使用
フォールバックルール:
- プライマリパス: 常にまずエージェントに委任
- フォールバックトリガー: エージェントのタイムアウトまたはリトライ後の失敗
- フォールバックアクション: 直接ファイル読み取り（3 ファイル以下、各 200 行以下）
- 文書化: ユーザーに警告し進捗ファイルに記録
アンチパターン（絶対にしない）:
# 悪い例: タスクの明確さでエージェントをスキップ
タスクが明確なら → ファイルを直接読む、エージェントをスキップ
# 良い例: エージェント優先、フォールバック次
常に → エージェントに委任
エージェントが失敗したら → 直接読み取りにフォールバック + ユーザーに警告
委任優先であり、直接読み取り優先でない理由:
- コンテキスト保護: エージェントの読み取りはオーケストレーターのコンテキストを消費しない
- 一貫性: すべてのコマンドで同じパターン
- 専門性: エージェントは stack-detector とパターン認識を適用
- フォールバックの安全性: 直接読み取りはセーフティネットであり、プライマリパスではない
オーケストレーター例外リファレンス（L1）
委任優先の原則に対するすべてのオーケストレーター例外はここに定義。コマンドは説明を重複させる代わりにこのセクションを参照すべき。
| 例外 | 条件 | コンテキストコスト | 代替コスト | 正当性 |
|---|
| クイックルックアップ | 3 ファイル以下、200 行/ファイル以下、合計 300 以下 | ~100 トークン | ~700 トークン（エージェント） | 単一値の確認にエージェントのオーバーヘッドは不要 |
| フォールバック読み取り | エージェントタイムアウト/失敗 + 1 回リトライ後 | ~200 トークン | ユーザーがブロック | レジリエンス: エージェント失敗でユーザーをブロックすべきではない |
| TRIVIAL 編集 | 2 行以下、意味的影響なし、判断不要 | ~50 トークン | ~1000 トークン（エージェント） | 明白な修正にエージェントのオーバーヘッドは不要 |
| 進捗/メタデータ読み取り | オーケストレーター状態ファイルのみ | ~30 トークン | ~500 トークン（エージェント） | プロジェクトコンテンツではない。オーケストレーター自身の状態 |
共通原則: すべての例外は委任優先に従う。直接アクションはフォールバックであり、プライマリパスではない。
例外の適用時:
- 例外は許可であり必須ではない - 委任は常に受容可能
- 例外にはすべての条件を満たす必要がある - 部分一致 = 委任
- 例外にはアクション後の検証が必要 - スコープが期待通りだったことを確認
避けるべきアンチパターン:
- 利便性のためにエージェントをスキップするために例外を使用
- すべての条件を検証せずに例外を適用
- 例外を使用した場合に文書化しない
サブエージェントのルール
ルール（L1 - ハード）
オーケストレーションの一貫性とコンテキスト保護にとって重要。
- ALWAYS: 標準化された結果フォーマットを使用する（集約を可能にする）
- NEVER: サマリーを約 500 トークン以上にしない（コンテキスト保護が重要）
- ALWAYS: 完了を妨げるブロッカーを報告する（オーケストレーターが知る必要がある）
- ALWAYS: 結果を返す前に提出前検証チェックリストを完了する（下記参照）
- ALWAYS: 提出前に file:line 参照が存在することを確認する（ハルシネーション防止）
- NEVER: ハルシネーションされたファイルパスや行番号で結果を提出しない
- MUST: 信頼度 >= 75 の場合、信頼度の内訳を含める（verified_confidence + inferred_confidence）
デフォルト（L2 - ソフト）
品質と使いやすさにとって重要。適切な理由がある場合はオーバーライド可能。
- すべての調査結果に file:line 参照を含める（ナビゲーションを支援）
- 根拠付きの信頼度スコアを提供する（優先順位付けを可能にする）
- 探索結果を要約し、生の出力を返さない
- 問題を重大度でカテゴリ化する（critical/important/minor）
ガイドライン（L3）
より良い結果のための推奨事項。
- 該当する場合は次のステップを含める
- エラーの回復オプションを提案する
- 設計判断で考慮したトレードオフを記載する
- アーキテクチャの一貫性のために見つかったパターンを参照する
セルフ検証チェックリスト
サブエージェントは結果を提出する前に、ハルシネーションを防止し精度を確保するために出力品質を検証する。
提出前検証（L1 - 必須）
すべてのサブエージェントは結果を返す前にこのチェックリストを完了する:
### 検証完了
- [ ] **ファイル参照が有効**: すべての `file:line` 参照が存在することを確認
- [ ] **コードスニペットが正確**: 引用されたコードが実際のファイル内容と一致
- [ ] **ハルシネーションされたパスなし**: 推測や捏造されたファイルパスがない
- [ ] **証拠が文書化済み**: 各調査結果に裏付けとなる証拠が引用されている
信頼度の内訳（L1 - 信頼度 >= 75 で必須）
信頼度を 2 つの要素で報告:
- verified_confidence: 直接のコード証拠に基づく（ファイル読み取り、テスト出力）
- inferred_confidence: パターン分析と合理的な仮定に基づく
- combined_confidence: (verified + inferred) / 2
例:
- verified_confidence: 90（正確な関数を読み、バグを確認）
- inferred_confidence: 70（類似パターンが他にも存在する可能性）
- combined_confidence: 80
信頼度の根拠（L2 - 信頼度 >= 85 で必須）
高い信頼度（85+）を報告する場合、明示的な根拠を提供:
### 信頼度の根拠
**スコア**: [X]
**証拠数**: [直接のコード証拠がある調査結果の数]
**検証方法**: [調査結果をどのように検証したか]
**潜在的な盲点**: [見逃している可能性があるもの]
クロス検証トリガー（L2）
追加検証を要求する場合:
| 条件 | アクション |
|---|
| 単一の証拠ソース | 「裏付けが必要」としてフラグ |
| 矛盾する調査結果 | オーケストレーターにエスカレーション |
| 信頼度 < 70 | 「不確実性」セクションを含める |
| セキュリティ関連の発見 | コード証拠を要求 |
ハルシネーション防止の実践
- ファイルパスを捏造しない - 不確実な場合は Glob/Grep で確認
- 読まずにコードを引用しない - 常にまず Read ツールでファイルを読む
- 実装詳細を推測しない - 実際のコードで確認
- 不確実性を明示的にフラグ - 「不確実」や「仮定」のラベルを使用
例: 検証済み vs 未検証の出力
未検証（悪い例）:
src/auth/login.ts:45 で認証を発見
検証済み（良い例）:
src/auth/login.ts:45 で認証を発見
- 確認済み: Read ツールでファイルの存在を確認
- コード一致: `export async function authenticate()`
- 信頼度: 95（直接のコード証拠）
