---
name: empirical-prompt-tuning
description: agent 向けテキスト指示（skill / slash command / task プロンプト / CLAUDE.md 節 / コード生成プロンプト）を、バイアスを排した実行者に動かしてもらい、両面（実行者の自己申告 + 指示側メトリクス）で評価して反復改善する手法。改善が頭打ちになるまで回す。プロンプトや skill を新規作成・大幅改訂した直後、またはエージェントの挙動が期待通りにならない原因を指示側の曖昧さに求めたいときに使う。
source: https://github.com/mizchi/chezmoi-dotfiles/blob/main/dot_claude/skills/empirical-prompt-tuning/SKILL.md
---

# Empirical Prompt Tuning

プロンプトの品質は書いた本人には分からない。書き手が「明瞭だ」と思うものほど、別エージェントが読むと詰まる。**バイアスを排した実行者に実際に動かしてもらい、両面で評価して反復する** のが本 skill の核。改善が頭打ちになるまで止めない。

## いつ使うか

- skill / slash command / タスクプロンプトを新規作成・大幅改訂した直後
- エージェントが期待通り動かず、原因を指示側の曖昧さに求めたいとき
- 重要度の高い指示（頻繁に使う skill、自動化の中核プロンプト）を堅牢化したいとき

使わない場面:

- 一回限りの使い捨てプロンプト（評価コストが割に合わない）
- 成功率の改善が目的ではなく、書き手の主観的好みを反映したいだけのとき

## ワークフロー

0. **Iteration 0 — description と body の整合チェック**（静的、dispatch 不要）
   - frontmatter `description` が謳う trigger / 用途を読む
   - body がカバーする範囲を読む
   - 乖離があれば iter 1 に進む前に description か body を合わせる
   - 例: description「navigation / form filling / data extraction」と書いてあるが body は `npx playwright test` の CLI ref のみ、のような乖離を検出
   - これを飛ばすと、subagent は description に合わせて body を「再解釈」し、実質 skill が要件を満たしていないのに精度が出る（false positive）

1. **ベースライン準備**: 対象プロンプトを確定し、次の 2 つを用意する。
   - **評価シナリオ** 2 〜 3 種（中央値 1 + edge 1 〜 2）。現実に起こりうるタスクで、対象プロンプトを実際に適用する場面を想定する。
   - **要件チェックリスト**（精度算出のため）。シナリオごとに「成果物が満たすべき要件」を 3 〜 7 項目で列挙する。精度 % = 満たした項目数 / 全項目数。事前に固定すること（後から動かさない）。
2. **バイアス排除読み**: 指示を「白紙」の実行者に読ませる。Task tool で **新規 subagent を dispatch** する。自己再読で済ませない（直前に書いた文章を客観視することは構造的に不可能）。並列で複数シナリオを同時実行する場合は単一メッセージ内で複数 Agent 呼び出しを並べる。dispatch 不能環境の扱いは「環境制約」節を参照。
3. **実行**: 後述の **subagent 起動契約** に従ったプロンプトを subagent に渡し、シナリオを実行させる。実行者は実装や出力を生成し、最後に自己申告レポートを返す。
4. **両面評価**: 戻ってきた結果から次を記録する。
   - **実行者の自己申告**（subagent のレポート本文から抽出）: 不明瞭点 / 裁量補完 / テンプレ適用で詰まった箇所
   - **指示側の計測**（判定規則は本節で一元定義、他箇所は本節を参照する）:
     - 成功/失敗: `[critical]` タグの付いた要件が **全て ○** のときのみ成功（○）。うち 1 つでも × または部分的なら失敗（×）。ラベルは ○ / × の 2 値のみ。
     - 精度（要件チェックリストの達成率 %。○ = 満点、× = 0、部分的 = 0.5 で合算、全項目数で割る）
     - ステップ数（Task tool の戻り値に付く usage メタの `tool_uses` をそのまま使う。Read / Grep も含める、除外しない）
     - 所要時間（Task tool の usage メタの `duration_ms`）
     - 再試行回数（subagent が同じ判断をやり直した回数。subagent の自己申告レポートから抽出、指示側では測れない）
     - **失敗時は「どの [critical] 項目が落ちたか」を提示フォーマットの "不明瞭点" 節に 1 行添える**（原因追跡のため）
   - 要件チェックリストには `[critical]` タグ付き項目を **最低 1 つ** 含めること（0 件だと成功判定が vacuous になる）。事後に [critical] の付け外しをしない。
5. **差分適用**: 不明瞭点を潰す最小修正をプロンプトに入れる。1 イテレーション 1 テーマ（関連する複数修正は OK、無関係な修正は次回に回す）。
   - **修正前に「この修正が要件チェックリスト / 判定文言のどの項目を満たすか」を明示する**（軸名から推測した修正は届かないことが多い。後述「修正の波及パターン」節）。
6. **再評価**: 新しい subagent で再度 2 → 5 を回す（同一 agent は再利用しない: 前回の改善を学習している）。並列度はイテレーションを進めても改善が頭打ちにならない場合に増やす。
7. **収束判定**: 目安「連続 2 イテレーションで新規の不明瞭点ゼロ かつ メトリクス改善が閾値以下（後述）」で停止。重要度が高いプロンプトは 3 連続にする。

## 評価軸

| 軸                       | 取り方                                        | 意味                   |
| ------------------------ | --------------------------------------------- | ---------------------- |
| 成功/失敗                | 実行者が意図した成果物を出したか（二値）      | 最低ライン             |
| 精度                     | 成果物が要件を何 % 満たしたか                 | 部分成功の程度         |
| ステップ数               | 実行者が使ったツール呼び出し / 判断ステップ数 | 指示の無駄遣いの指標   |
| 所要時間                 | 実行者の duration_ms                          | 認知負荷の代替指標     |
| 再試行回数               | 同じ判断を何度やり直したか                    | 指示の曖昧さのシグナル |
| 不明瞭点（自己申告）     | 実行者が箇条書きで列挙                        | 質的な改善材料         |
| 裁量補完箇所（自己申告） | 指示で決まっていなかった判断                  | 暗黙の仕様の炙り出し   |

**重み付け**: 質的（不明瞭点・裁量補完）を主、量的（時間・ステップ数）を補助とする。時間短縮だけ追いかけるとプロンプトが痩せすぎる。

### `tool_uses` の質的解釈

精度だけ見ると skill の問題が隠れる。`tool_uses` を **シナリオ間の相対値** として使うと構造的欠陥が見える:

- シナリオ間で他シナリオ比 **3-5 倍以上** なら、その skill は **decision-tree index 寄りで自己完結性が低い** サイン。実行者が references descent を強いられている
- 典型例: 全シナリオ `tool_uses` が 1-3 なのに 1 シナリオだけ 15+ → そのシナリオ用の recipe が skill 内に無く、references/ を横断探索している
- 対処: iter 2 で「最小完成例 inline」や「いつ references を読むかの指針」を SKILL.md 冒頭に追加すると `tool_uses` は大幅低下する

精度 100% でも `tool_uses` の偏りがあれば iter 2 発動の根拠になる。「精度のみで判断して打ち切り」は構造的欠陥を見逃しがち。

### 修正の波及パターン (保守 / 上振れ / ゼロ振れ)

修正→効果は線形ではない。事前見積もりは次の 3 パターンが起こりうる:

- **保守的に振れる** (見積もり > 実測): 1 修正で複数軸狙ったが 1 軸しか動かなかった。「複数軸狙いは外しがち」
- **上振れ** (見積もり < 実測): 1 つの構造的な情報 (例: コマンド + 設定 + 期待出力の組合せ) が複数軸の判定文言を同時に満たした。「情報の組合せが構造的に多軸に効く」
- **ゼロ振れ** (見積もり > 0、実測 = 0): 軸名から推測した修正が、判定文言のどれにも届かなかった。「軸名と判定文言は別物」

これを安定させるには **差分適用前に subagent に「この修正が判定文言のどれを満たすか」を言語化させる**。閾値文言レベルで紐付けないと見積もり精度が出ない。評価軸を新設するときも、各点の判定基準を閾値文言レベルまで具体化しておくこと（「全部明示」「動く最小構成全文」のように、何があれば 2 点になるか subagent が判定できる粒度）。

## subagent 起動契約

実行者に渡すプロンプトは次の構造を取る。これが「両面評価」の入力契約。

```
あなたは <対象プロンプト名> を白紙で読む実行者です。

## 対象プロンプト
<対象プロンプトの本文を全文貼る or Read で読ませるパスを指定>

## シナリオ
<シナリオの状況設定 1 段落>

## 要件チェックリスト（成果物が満たすべき項目）
1. [critical] <最低ラインに含む項目>
2. <通常項目>
3. <通常項目>
...
（判定規則は「ワークフロー 4. 両面評価 / 指示側の計測」節に一元定義。[critical] は最低 1 つ必須。）

## タスク
1. 対象プロンプトに従ってシナリオを実行し、成果物を生成する。
2. 終了時に下記レポート構造で返答する。

## レポート構造
- 成果物: <生成物 or 実行結果サマリ>
- 要件達成: 各項目について ○ / × / 部分的（理由付き）
- 不明瞭点: 対象プロンプトで詰まった箇所、解釈に迷った文言（箇条書き）
- 裁量補完: 指示で決まっておらず自分の判断で埋めた箇所（箇条書き）
- 再試行: 同じ判断をやり直した回数とその理由
```

呼び出し側はレポートから自己申告部分を抽出し、`tool_uses` / `duration_ms` を Agent tool の usage メタから取得して評価軸表を埋める。

## 環境制約

新規 subagent を dispatch できない環境（既に subagent として動作している、Task tool が無効化されている等）では、本 skill は **適用しない**。

- 代替案 1: 親セッションのユーザーに別 Claude Code セッションを起動して依頼してもらう
- 代替案 2: 評価を諦め、ユーザーに「empirical evaluation skipped: dispatch unavailable」と明示報告する
- **NG**: 自己再読で代替する（バイアスが入るので評価結果を信じてはいけない）

**構造審査モード**: empirical 評価ではなく、skill / プロンプトの **記述の整合性・明瞭性だけ** をチェックしたい場合は、構造審査モードとして明示的に切り分ける。subagent への依頼プロンプトに「今回は構造審査モード: 実行ではなくテキスト整合性チェック」と明記する。これにより subagent は環境制約節の skip 動作に引っかからず、静的レビューを返せる。構造審査は empirical の代替ではなく補助（連続クリア判定には使えない）。

## 反復の打ち切り基準

- **収束（停止）**: 連続 2 回で次を **全て** 満たす:
  - 新規不明瞭点: 0 件
  - 精度の前回比改善: +3 ポイント以下（5% → 8% のような飽和）
  - ステップ数の前回比変動: ±10% 以内
  - duration の前回比変動: ±15% 以内
  - **過適合チェック**: 収束判定時に、これまで使っていない hold-out シナリオ 1 本を追加して評価。精度が直近平均から 15 ポイント以上落ちたら過適合。baseline シナリオ設計に戻って edge を足す。
- **発散（設計を疑う）**: 3 回以上イテレーションしても新規不明瞭点が減らない → プロンプトの設計方針自体が間違っている可能性。修正パッチで直すのをやめ、構造を書き直す
- **リソース打ち切り**: 重要度と改善コストが釣り合わなくなったら止める（80 点で出す判断）

## 提示フォーマット

各イテレーションで次の形で記録・ユーザーに提示する:

```
## Iteration N

### 変更点（前回差分）
- <修正内容 1 行>

### 実行結果（シナリオ別）
| シナリオ | 成功/失敗 | 精度 | steps | duration | retries |
|---|---|---|---|---|---|
| A | ○ | 90% | 4 | 20s | 0 |
| B | × | 60% | 9 | 41s | 2 |

### 不明瞭点（今回新出）
- <シナリオ B>: [critical] 項目 N が × — <落ちた理由 1 行>   # 失敗時は必ず添える
- <シナリオ B>: <その他の指摘 1 行>
- <シナリオ A>: （新出なし）

### 裁量補完（今回新出）
- <シナリオ B>: <補完内容>

### 次の修正案
- <最小修正 1 行>

（収束判定: 連続 X 回クリア / 停止条件まであと Y 回）
```

## Red flags（合理化に注意）

| 出てくる合理化                                        | 実態                                                                                                                 |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 「自分で読み直せば同じ効果がある」                    | 直前に書いた文章を "客観視" はできない。必ず新規 subagent を dispatch する。                                         |
| 「1 シナリオで充分」                                  | 1 シナリオは過適合する。最低 2、できれば 3。                                                                         |
| 「不明瞭点ゼロが 1 回出たから終わり」                 | 偶然なこともある。連続 2 回で確定判定。                                                                              |
| 「複数の不明瞭点を一気に潰そう」                      | 何が効いたか分からなくなる。1 イテレーション 1 テーマ。                                                              |
| 「関連する微修正も純粋に 1 件ずつ別 iter に分けよう」 | 逆方向の罠。"1 テーマ" は意味単位。関連する 2-3 件の微修正は 1 iter にまとめて良い。分けすぎると iter 数が爆発する。 |
| 「メトリクスが良いから質的フィードバックは無視」      | 時間短縮は痩せすぎのサインにもなる。質的を主に。                                                                     |
| 「書き直した方が早い」                                | 3 回以上不明瞭点が減らないなら正解。それ以前の段階では逃げ。                                                         |
| 「同じ subagent を使い回そう」                        | 前回の改善を学習している。毎回新規に dispatch する。                                                                 |

## よくある失敗

- **シナリオが楽すぎる / 難しすぎる**: どちらもシグナルが出ない。現実の使用場面の中央値を 1 つ、edge を 1 つ
- **メトリクスだけ見る**: 時間短縮しか追わないと、重要な説明が削られて脆くなる
- **イテレーションごとに変更多すぎ**: 「あのときの修正のどれが効いたか」が追えなくなる。1 修正 1 イテレーション
- **シナリオを修正に合わせてチューニング**: 不明瞭点が潰れたように見せるため、シナリオ側を簡単にする → 本末転倒

## 関連

- `superpowers:writing-skills` — skill 作成時の TDD アプローチ。本 skill の「subagent で baseline → 修正 → 再実行」と本質的に同じ
- `retrospective-codify` — タスク後の学び固定化。本 skill はプロンプト開発中、retrospective-codify はタスク終了後、と使い分ける
- `superpowers:dispatching-parallel-agents` — 複数シナリオを並列で走らせるときの作法