| name | empirical-prompt-tuning |
| description | プロンプト・スキル・スラッシュコマンドを反復的に改善する実証的チューニングスキル。「プロンプトを改善して」「スキルを最適化して」「指示が曖昧と言われた」「エージェントが意図と違う動きをする」などで発動する。偏りのない新しいサブエージェントで実行・評価し、指標が収束するまで反復する。 |
| metadata | {"version":"1.0.0","tier":"stable","category":"meta","tags":["prompt-tuning","evaluation","iteration","subagent","quality"]} |
実証的プロンプトチューニング
概要
「プロンプトの品質は、その作者には見えない」
自分が書いた指示を自分で読み返しても、バイアスを排除できない。このスキルは、偏りのない新しいエージェントに実行させ、両面評価と指標計測を繰り返すことで、プロンプトの品質を客観的・反復的に高める。
発動タイミング
| 状況 | 適用 |
|---|
| スキル・スラッシュコマンド・タスクプロンプトを新規作成・大幅改訂した | ✅ 適用 |
| エージェントが予期しない動作をし、指示の曖昧さが疑われる | ✅ 適用 |
| 重要度・使用頻度が高いプロンプトを堅牢化したい | ✅ 適用 |
| 使い捨ての簡易プロンプトで評価コストが見合わない | ❌ スキップ |
前提条件
このスキルはサブエージェント（Task ツール相当）のディスパッチ能力を必要とする。
- ディスパッチ不可の場合: 「実証的評価をスキップ: ディスパッチ不可」と明示し、後述の「構造監査モード」で代替する
- 自己レビューは禁止: バイアスが不可避なため、必ず新しいエージェントに委ねる
ワークフロー
ステップ0: 整合性チェック（反復前に一度だけ）
フロントマターの description とボディの内容が一致しているか確認する。ズレがあれば修正してからステップ1へ。
ステップ1: 評価シナリオと要件チェックリストの確定
反復を始める前に固定する（途中変更は過学習の原因になる）。
シナリオ設計（2〜3種類）:
- ベースラインシナリオ（典型的な使用例）
- エッジケースシナリオ（境界条件・例外的入力）
- （任意）ホールドアウトシナリオ（過学習チェック用、最後まで使わない）
要件チェックリスト（シナリオごとに3〜7項目）:
- [ ] [critical] <必達要件>
- [ ] <推奨要件>
[critical] は1つ以上必須。これが一つでも失敗すると総合判定は失敗。
ステップ2: エグゼキューターのディスパッチ
重要: 自分でプロンプトを読み返さない。必ず新しいサブエージェントに委ねる。
サブエージェントへの指示に含める内容:
- 対象プロンプトの全文
- 実行するシナリオの説明（1段落）
- 要件チェックリスト（
[critical] マーク付き）
- タスク実行指示
- 期待するレポート構造（後述）
ステップ3: エグゼキューターの実行とレポート収集
エグゼキューターが返すレポートの構造:
## 成果物サマリー
<実行した成果物の概要>
## 要件達成状況
- [critical] <要件名>: ✅/❌ — <根拠1文>
- <要件名>: ✅/❌ — <根拠1文>
## フェーズ別トレース
| フェーズ | 問題 |
|----------|------|
| 理解 | <問題なし、または具体的な問題> |
| 計画 | <問題なし、または具体的な問題> |
| 実行 | <問題なし、または具体的な問題> |
| フォーマット | <問題なし、または具体的な問題> |
問題がなければ各行を「問題なし」で一行にまとめてよい。
## 不明点（構造化）
| # | Issue | Cause | General Fix Rule |
|---|-------|-------|-----------------|
| 1 | <何が曖昧だったか> | <どのフェーズで発生したか> | <クラスレベルの修正指針> |
## 裁量補填
<指示に明示されていないのに自分で判断した点のリスト>
## リトライ回数
<同じ判断をやり直した回数>
ステップ4: 両面評価と指標計測
エグゼキューターのレポートを元に以下を計測する:
| 指標 | 算出方法 | 重み |
|---|
| 成功/失敗 | [critical] 要件が全て ✅ なら成功 | 最優先 |
| 精度 % | 達成要件数 ÷ 全要件数 × 100 | 最優先 |
| ステップ数 | フェーズ別トレースのツール呼び出し数 | 参考 |
| 所要時間 | 実行時間（認知負荷の代理指標） | 参考 |
| リトライ回数 | 曖昧さのシグナル | 参考 |
| 不明点（定性） | エグゼキューターの自己申告 | 最優先 |
| 裁量補填（定性） | 暗黙の仕様が露出した箇所 | 最優先 |
定性的フィードバック（不明点・裁量補填）を定量指標より優先する。
ステップ5: 最小限の修正適用
- 失敗パターン台帳を確認する（後述）
- 現在の General Fix Rule が既存パターンと一致する場合、なぜ以前の修正が効かなかったかを先に調査する
- 1回の反復で 1つの意味的テーマ のみ修正する（複数テーマの同時修正は効果の分離を妨げる）
ステップ6: 新しいエグゼキューターで再評価
ステップ2〜5を繰り返す。同じエグゼキューターを再利用しない（改善の学習が信頼性を汚染する）。
ステップ7: 収束判定
以下の全条件を 2回連続 で満たしたら停止する:
| 条件 | 基準 |
|---|
| 新規不明点 | ゼロ |
| 精度の改善幅 | ≤3ポイント |
| ステップ数の変動 | ±10% 以内 |
| 所要時間の変動 | ±15% 以内 |
ホールドアウトチェック（過学習検出）: 収束後、ホールドアウトシナリオで精度が15ポイント以上低下した場合はシナリオ設計を見直す。
構造的問題の判断: 3回以上の反復で不明点が減らない場合、パッチ適用ではなく抜本的な書き直しを検討し、ユーザーに報告する。
失敗パターン台帳
反復をまたいで累積する。毎回の修正前に照合する。
## 失敗パターン台帳
- パターン名: <説明的な名称>
- 例: <代表的な不明点の文言>
- General Fix Rule: <クラスレベルの修正指針>
- 発生: iter N, iter M
3回以上繰り返すパターンは構造的問題のサイン。個別パッチではなく設計の見直しを推奨する。
バリアント探索（任意）
収束条件を満たさないまま改善が頭打ちになった場合:
- 保守的バリアント: 最小限の変更（表現の明確化のみ）
- 探索的バリアント: 構造を変える大胆な変更
2つを並列で評価し、精度・ステップ数・不明点数で客観的に比較する。主観的なA/B判定は避ける。
構造監査モード（ディスパッチ不可時の代替）
サブエージェントをディスパッチできない場合に限り、静的テキスト整合性チェックのみ実施する。
チェック項目:
description とボディの内容が一致しているか[critical] 要件が少なくとも1つあるか- フェーズ（理解・計画・実行・フォーマット）が全て記述されているか
- 不明点の構造（Issue / Cause / General Fix Rule）が定義されているか
実証的評価の代替にはならないことをユーザーに明示する。
禁止事項
| 禁止 | 理由 |
|---|
| 自己レビューで新規エージェントの代替 | バイアスが不可避 |
| シナリオ1件のみ | 過学習を引き起こす（最低2件） |
| 複数テーマを1回で修正 | 効果の分離が不可能 |
| 定量指標を定性より優先 | 時間短縮が危険な不完全性を隠す |
| 同じエグゼキューターを再利用 | 改善学習が信頼性を汚染する |
| 連続2回クリアせずに停止 | 単発の成功は収束を意味しない |
エージェント互換性
このスキルは特定のAIエージェントに依存しない。以下のエージェントで動作する:
| エージェント | サブエージェント機能 | 備考 |
|---|
| Claude Code | Task ツール | ネイティブ対応 |
| GitHub Copilot | エージェントモード | ワークフロー要確認 |
| Kiro | エージェントモード | ワークフロー要確認 |
| OpenAI Codex CLI | — | ディスパッチ不可 → 構造監査モードで代替 |
| その他 LLM CLI | — | ディスパッチ可否を確認してから開始 |
ディスパッチ能力がない環境では「構造監査モード」を使い、その旨をユーザーに明示する。
クイックリファレンス
ステップ0: description ↔ ボディの整合性確認
ステップ1: シナリオ2〜3件 + 要件チェックリスト確定（固定）
ステップ2: 新規サブエージェントにディスパッチ
ステップ3: 実行 → 構造化レポート収集
ステップ4: 成功/精度/ステップ数/不明点/裁量補填 を計測
ステップ5: 失敗パターン台帳照合 → 1テーマのみ修正
ステップ6: 新規エージェントで再評価
ステップ7: 収束条件を2連続で満たしたら停止
