# Empirical Prompt Tuning

> プロンプト・スキル・スラッシュコマンドを反復的に改善する実証的チューニングスキル。「プロンプトを改善して」「スキルを最適化して」「指示が曖昧と言われた」「エージェントが意図と違う動きをする」などで発動する。偏りのない新しいサブエージェントで実行・評価し、指標が収束するまで反復する。

- Skill: `ynitto/empirical-prompt-tuning` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ynitto/empirical-prompt-tuning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ynitto/empirical-prompt-tuning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ynitto (https://skillmd.com/u/ynitto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ynitto/empirical-prompt-tuning

---


# 実証的プロンプトチューニング

## 概要

**「プロンプトの品質は、その作者には見えない」**

自分が書いた指示を自分で読み返しても、バイアスを排除できない。このスキルは、偏りのない新しいエージェントに実行させ、両面評価と指標計測を繰り返すことで、プロンプトの品質を客観的・反復的に高める。

## 発動タイミング

| 状況 | 適用 |
|------|------|
| スキル・スラッシュコマンド・タスクプロンプトを新規作成・大幅改訂した | ✅ 適用 |
| エージェントが予期しない動作をし、指示の曖昧さが疑われる | ✅ 適用 |
| 重要度・使用頻度が高いプロンプトを堅牢化したい | ✅ 適用 |
| 使い捨ての簡易プロンプトで評価コストが見合わない | ❌ スキップ |

## 前提条件

このスキルはサブエージェント（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連続で満たしたら停止
```