empirical-prompt-tuning

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. 対象プロンプトの全文
2. 実行するシナリオの説明（1段落）
3. 要件チェックリスト（[critical] マーク付き）
4. タスク実行指示
5. 期待するレポート構造（後述）

ステップ3: エグゼキューターの実行とレポート収集

エグゼキューターが返すレポートの構造:

## 成果物サマリー
<実行した成果物の概要>

## 要件達成状況
- [critical] <要件名>: ✅/❌ — <根拠1文>
- <要件名>: ✅/❌ — <根拠1文>

## フェーズ別トレース
| フェーズ | 問題 |
|----------|------|
| 理解 | <問題なし、または具体的な問題> |
| 計画 | <問題なし、または具体的な問題> |
| 実行 | <問題なし、または具体的な問題> |
| フォーマット | <問題なし、または具体的な問題> |
問題がなければ各行を「問題なし」で一行にまとめてよい。

## 不明点（構造化）
| # | Issue | Cause | General Fix Rule |
|---|-------|-------|-----------------|
| 1 | <何が曖昧だったか> | <どのフェーズで発生したか> | <クラスレベルの修正指針> |

## 裁量補填
<指示に明示されていないのに自分で判断した点のリスト>

## リトライ回数
<同じ判断をやり直した回数>

ステップ4: 両面評価と指標計測

エグゼキューターのレポートを元に以下を計測する:

指標	算出方法	重み
成功/失敗	[critical] 要件が全て ✅ なら成功	最優先
精度 %	達成要件数 ÷ 全要件数 × 100	最優先
ステップ数	フェーズ別トレースのツール呼び出し数	参考
所要時間	実行時間（認知負荷の代理指標）	参考
リトライ回数	曖昧さのシグナル	参考
不明点（定性）	エグゼキューターの自己申告	最優先
裁量補填（定性）	暗黙の仕様が露出した箇所	最優先

定性的フィードバック（不明点・裁量補填）を定量指標より優先する。

ステップ5: 最小限の修正適用

1. 失敗パターン台帳を確認する（後述）
2. 現在の General Fix Rule が既存パターンと一致する場合、なぜ以前の修正が効かなかったかを先に調査する
3. 1回の反復で 1つの意味的テーマ のみ修正する（複数テーマの同時修正は効果の分離を妨げる）

ステップ6: 新しいエグゼキューターで再評価

ステップ2〜5を繰り返す。同じエグゼキューターを再利用しない（改善の学習が信頼性を汚染する）。

ステップ7: 収束判定

以下の全条件を 2回連続 で満たしたら停止する:

条件	基準
新規不明点	ゼロ
精度の改善幅	≤3ポイント
ステップ数の変動	±10% 以内
所要時間の変動	±15% 以内

ホールドアウトチェック（過学習検出）: 収束後、ホールドアウトシナリオで精度が15ポイント以上低下した場合はシナリオ設計を見直す。

構造的問題の判断: 3回以上の反復で不明点が減らない場合、パッチ適用ではなく抜本的な書き直しを検討し、ユーザーに報告する。

---

失敗パターン台帳

反復をまたいで累積する。毎回の修正前に照合する。

## 失敗パターン台帳

- パターン名: <説明的な名称>
  - 例: <代表的な不明点の文言>
  - General Fix Rule: <クラスレベルの修正指針>
  - 発生: iter N, iter M

3回以上繰り返すパターンは構造的問題のサイン。個別パッチではなく設計の見直しを推奨する。

---

バリアント探索（任意）

収束条件を満たさないまま改善が頭打ちになった場合:

1. 保守的バリアント: 最小限の変更（表現の明確化のみ）
2. 探索的バリアント: 構造を変える大胆な変更

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連続で満たしたら停止