empirical-prompt-tuning

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

プロンプトの作成者は、その品質を判断できません。書き手が明確だと思うほど、別のエージェントがつまずく可能性は高くなります。このスキルの核となるのは、偏りのない実行者に実際に指示を実行させ、両面から評価し、反復することです。改善が頭打ちになるまで続けてください。

使用するタイミング

• スキル／スラッシュコマンド／タスクプロンプトを新規作成、または大幅に改訂した直後
• エージェントが期待どおりに動作せず、指示の曖昧さが原因かどうかを特定したいとき
• 重要度の高い指示（頻繁に使うスキル、自動化の中核となるプロンプト）を強化するとき

使用しないケース：

• 使い捨ての単発プロンプト（評価コストに見合う効果がありません）
• 成功率の向上ではなく、書き手の主観的な好みを反映することだけが目的の場合

ワークフロー

0. 反復 0 — description と本文の整合性チェック（静的チェックのため、ディスパッチは不要）
   • フロントマターの description に記載されたトリガー／ユースケースを確認します
   • 本文が実際にカバーしている範囲を確認します
   • ずれがある場合は、イテレーション 1 に進む前に description または本文を調整します
   • 例：description では「ナビゲーション／フォーム入力／データ抽出」と記載されているのに、本文は npx playwright test の CLI リファレンスにすぎない場合など、そのようなずれを検出します
   • これを省略すると、サブエージェントが description に合うよう本文を「独自に解釈」し、スキルが実際には要件を満たしていないにもかかわらず、精度が高いという誤った結果が出ます（偽陽性）
1. ベースラインの準備：対象のプロンプトを固定し、以下の2点を準備します。
   • 評価シナリオ：2～3種類（中央値1つ＋エッジケース1～2つ）。対象のプロンプトが適用される実際の状況を想定した、現実的なタスクにします。
   • 要件チェックリスト（精度の算出用）。各シナリオについて、成果物が満たすべき項目を3～7個列挙します。精度（%）＝満たした項目数／全項目数。この内容は事前に固定し、後から変更しないでください。
2. バイアスのない読み取り：指示を「白紙状態」の実行者に読ませます。Task ツールを使って、新しいサブエージェントを呼び出してください。自分で読み直す方法で代用しないでください（自分が書いた文章を客観的に見ることは構造上不可能です）。複数のシナリオを並行して実行する場合は、1つのメッセージ内で複数の Agent 呼び出しを行います。呼び出しができない環境での対処については、「環境の制約」セクションを参照してください。
3. 実行：以下に記載する「サブエージェント呼び出し契約」に従ったプロンプトをサブエージェントに渡し、シナリオを実行させます。実行者は実装または出力を作成し、最後に自己報告を返します。
4. 両面評価：返された結果から、以下を記録します。
   • 実行者の自己報告（サブエージェントの報告本文から抽出）：不明瞭な点／裁量で補った箇所／テンプレートの適用に詰まった箇所
   • トレースの解釈：各不明瞭な点について、発生したフェーズ（「サブエージェント呼び出し契約」を参照：理解／計画／実行／フォーマット）をタグ付けします。フェーズに応じた修正のほうが、「プロンプトが不明瞭だった」という全般的な修正より効果的です。理解フェーズの曖昧さが1つあるだけでも、実行フェーズで連鎖的な失敗に見えることがあります。
   • 構造化された振り返り：各不明瞭な点について、Issue / Cause / General Fix Rule の形式で返します。General Fix Rule は、「失敗パターン台帳」に反映するためのクラスレベルの抽象化です。これがないと、修正が単発の対処にとどまり、後で同じ間違いが再発します。
   • 指示側の測定値（判定ルールはこのセクションで正式に定義します。他の箇所から参照してください）。
     • 成功／失敗：[critical] とタグ付けされた要件がすべて○の場合に限り、成功（○）とします。1つでも×または部分達成があれば失敗（×）です。判定は二値の○／×のみです。
     • 精度（要件チェックリストの達成率、%）。○＝満点、×＝0、部分達成＝0.5とし、合計して全項目数で割ります。
     • ステップ数（Task ツールの戻り値に付随する使用量メタデータの tool_uses フィールドをそのまま使います。Read／Grep も含め、除外しないでください）。
     • 所要時間（Task ツールの使用量メタデータにある duration_ms）。
     • 再試行回数（サブエージェントが同じ判断をやり直した回数。サブエージェントの自己報告から抽出します。指示側では測定できません）。
     • 失敗時は、根本原因の追跡用に、提示形式の「不明瞭な点」セクションに「どの [critical] 項目が未達だったか」を1行で追記します。
   • 要件チェックリストには、少なくとも1つの [critical] タグ付き項目を含める必要があります（ゼロの場合、成功判定が無意味になります）。事後に [critical] タグを追加または削除しないでください。
5. 差分の適用：不明瞭な点を解消するため、プロンプトに最小限の修正を加えます。1回の反復につき1つのテーマに絞ってください（関連する修正は複数でもかまいません。無関係な修正は次回に回します）。
   • 修正を適用する前に、「この修正によって要件チェックリスト／判定文言のどの項目を満たすのか」を明示してください（軸の名称から推測した修正は反映されないことがあります。以下の「修正の反映パターン」を参照してください）。
   • まず失敗パターン台帳を確認してください。構造化された振り返りの General Fix Rule が既知のパターンと一致する場合、最初に「なぜ既存の修正で防げなかったのか」を確認します。新しい台帳エントリーを追加する前に、修正をプロンプトの前のほうに移す、または表現を変える必要があるかもしれません。
6. 再評価：新しいサブエージェントを使って、手順2～5を再度実行します（同じエージェントは再利用しないでください。以前の改善点を学習しているためです）。反復しても改善が頭打ちにならない場合は、並列度を上げます。
7. 収束の確認：大まかな目安として、「新たな不明瞭な点が2回連続でゼロであり、かつ指標の改善が以下のしきい値を下回ったら」停止します。重要度の高いプロンプトでは、これを3回連続とします。

評価軸

軸	記録方法	意味
成功／失敗	実行者が意図した成果物を生成したか（二値）	最低限の基準
正確性	成果物が要件を満たす割合	部分的な成功の度合い
ステップ数	実行者が使用したツール呼び出し／判断ステップの数	指示の無駄を示す指標
所要時間	実行者のduration_ms	認知負荷の代理指標
再試行回数	同じ判断をやり直した回数	指示の曖昧さを示す兆候
不明点（自己申告）	実行者が箇条書きで列挙	定性的な改善材料
裁量による補完（自己申告）	指示で定められていない判断	暗黙の仕様を明らかにする

重み付け：定性的な項目（不明点／裁量による補完）を主軸とし、定量的な項目（時間／ステップ数）は補助とします。時間の短縮だけを追求すると、プロンプトが薄くなりすぎます。

tool_usesの定性的な解釈

正確性だけを見ていると、スキルに関する問題が見えません。シナリオ間での相対値としてtool_usesを使うと、構造上の欠陥が明らかになります。

• あるシナリオの値が他より3～5倍以上の場合、そのスキルは判断ツリーのインデックスに依存し、自己完結性が低いことを示しています。実行者は参照をたどることを強いられています。
• 典型例：すべてのシナリオのtool_usesが1～3なのに、あるシナリオだけが15以上の場合、そのシナリオ向けの手順がスキル自体にないため、参照資料を横断して検索しています。
• 対策：反復2で、SKILL.mdの冒頭に「インラインの最小完全例」または「参照資料を読むタイミングのガイダンス」を追加すると、tool_usesが大幅に減少します。

正確性が100％でも、tool_usesの偏りがあれば反復2を実施する理由になります。「正確性だけで打ち切る」と、構造上の欠陥を見落としがちです。

修正の伝播パターン（控えめ／過剰／ゼロ）

修正から効果へのつながりは線形ではありません。事前推定では、次の3つのパターンが起こり得ます。

• 控えめな変化（推定値 > 実測値）：複数の軸を狙った修正が、1つの軸しか動かしませんでした。「複数の軸を狙うと、外しがちです。」
• 過剰な変化（推定値 < 実測値）：情報の構造的なひとかたまり（例：コマンド＋設定＋期待される出力）が、複数の軸にわたる評価文言を同時に満たしました。「情報の組み合わせは、構造的に複数の軸に働きかけます。」
• 効果なし（推定値 > 0、実測値 = 0）：軸の名称から推測した修正が、評価文言のどれにも届きませんでした。「軸の名称と評価文言は別物です。」

これを安定させるには、差分を適用する前に、サブエージェントに「この修正が満たす評価文言」を言語化させてください。しきい値の文言レベルで結び付けないかぎり、推定の正確性は得られません。新しい評価軸を追加するときは、各点の評価基準も、しきい値の文言レベルまで具体化してください（サブエージェントが判断できる粒度、たとえば「すべて明示されている」や「最小限の動作する設定の全文」などにし、何が2点に相当するかがわかるようにします）。

サブエージェント呼び出しの契約

実行者に渡すプロンプトは、以下の構成にします。これは「両側評価」の入力契約です。

You are an executor reading <target prompt name> with a blank slate.

## Target prompt
<Paste the full body of the target prompt, or specify a path for Read>

## Scenario
<One paragraph setting the scenario context>

## Requirements checklist (items the deliverable must satisfy)
1. [critical] <item that belongs to the minimum bar>
2. <normal item>
3. <normal item>
...
(Judgment rules are canonically defined in "Workflow 4. Two-sided evaluation / Instruction-side measurements". At least one [critical] is required.)

## Task
1. Follow the target prompt to execute the scenario and produce the deliverable.
2. On completion, respond with the report structure below.

## Report structure
- Deliverable: <artifact or execution summary>
- Requirement achievement: ○ / × / partial (with reason) for each item
- **Trace** (tag OK / stuck / skipped for each phase, one-line reason when not OK):
  - Understanding (reading the instruction and building a mental model)
  - Planning (deciding the approach / ordering)
  - Execution (actually doing the work)
  - Formatting (shaping the deliverable to the expected form)
  - *Collapsed form allowed*: when all four phases are OK, a single line `Trace: all OK` is sufficient. Emit phase-by-phase only when any phase is stuck or skipped. (This avoids happy-path boilerplate; the trace structure only earns its cost when something actually goes wrong.)
- **Unclear points (structured)**: for each issue, three lines:
  - Issue: <what observably happened>
  - Cause: <why, diagnosed at the instruction level>
  - General Fix Rule: <a class-level rule, not a spot fix, that would prevent this class of mistake>
- Discretionary fill-ins: places not fixed by the instruction and filled in by your own judgment (bullets)
- Retries: number of times you redid the same decision and why

呼び出し元は、レポートから自己申告の部分を抽出し、Agentツールの使用状況メタデータからtool_uses／duration_msを取得して、評価軸の表に記入します。

環境の制約

新しいサブエージェントを起動できない環境（すでにサブエージェントとして実行中、Task ツールが無効など）では、このスキルを適用しないでください。

• 代替案 1：親セッションのユーザーに、別の Claude Code セッションを開始して評価を委任するよう依頼します
• 代替案 2：評価を断念し、「実証的評価をスキップしました：起動できません」とユーザーに明示的に報告します
• 禁止：自分で読み直して代用すること（バイアスが入り、評価結果を信頼できないため）

構造レビュー モード：実証的評価を実行するのではなく、スキル／プロンプトの説明の一貫性と明確さだけを確認したい場合は、構造レビュー モードとして明示的に切り分けてください。サブエージェントへの依頼プロンプトには、「今回は構造レビュー モードです。テキストの一貫性を確認するものであり、実行はしません」と明記してください。これにより、サブエージェントは環境制約セクションのスキップ動作に抵触せず、静的レビューを返せます。構造レビューは実証的評価を補助するものであり、その代替にはなりません（連続合格の判定には使用できません）。

反復の停止基準

• 収束（停止）：次のすべてを満たすラウンドが 2 回連続した場合：
  • 新たな不明点：0
  • 前回と比べた精度の向上：+3 ポイント以下（例：5% → 8% のような飽和）
  • ステップ数の変動：±10% 以内
  • 所要時間の変動：±15% 以内
  • 過学習チェック：収束判定時に、これまで使っていないホールドアウトシナリオを 1 つ追加して評価します。最近の平均から精度が 15 ポイント以上低下した場合は過学習です。ベースラインのシナリオ設計に戻り、エッジケースを追加します。
• 発散（設計を疑う）：新たな不明点が 3 回以上の反復にわたって減少しない場合は、プロンプト自体の設計方針が誤っている可能性があります。パッチによる修正をやめ、構造を書き直してください。
• リソースによる打ち切り：重要度と改善コストのバランスが取れなくなった時点で停止します（「80 点で出荷する」という判断）。

失敗パターンの記録簿

反復を通じて、失敗モードの累積リストを維持してください。これがないと、反復のたびに同じ種類のミスが再発見され、同じ General Fix Rule が異なる表現で繰り返し現れていることに担当者が気づかないまま、精度の向上が停滞します。

記入形式：

- **Pattern name**: short descriptive handle (not "ambiguous X"; prefer "over-eager template application when skip clause is absent")
  - Example: <representative Issue wording from some iter>
  - General Fix Rule: <the class-level rule from that iter's structured reflection>
  - Seen in: iter N, iter M, ...

ルール：

• Workflow のステップ 5 で修正案を作成する前に、記録簿を確認してください。現在の General Fix Rule が既存の項目と一致する場合は、Seen in を更新し、既存の修正で再発を防げなかった理由（表現が曖昧だったか、プロンプト内の位置が遅すぎたか、例が不足していたかなど）を調査してから、新しい項目を追加してください。
• 対象を絞った修正を行っても 3 回以上繰り返されるパターンは、構造上の問題を示すサインです。修正を続けるのではなく、上記の「発散」基準に従ってください。
• 記録簿は対象プロンプトごとに管理し、実証的なプロンプト調整の実行間では共有しません。

バリエーションの検討（任意、停滞を打破するため）

反復が停滞に近づいているのに、収束基準（クリアが2回連続）を満たしていない場合は、局所最適に陥っている可能性を考え、2つのバリエーションで検証します。

• 保守的なバリエーション：現在のプロンプトに、次点の小さな修正を加えます
• 探索的なバリエーション：現在のプロンプトに、構成上の変更を1つ加えます。セクションの順序を入れ替える、密度の高い段落を分割する、重複するセクションを削除する、または不足している足場（例：具体的な例）を追加します

同じシナリオに対して新しいサブエージェントを並列で起動します（1つのメッセージで複数の Agent ツールを呼び出します）。正確性の高いバリエーションを採用します。同点の場合は、不明瞭な点が少ないほうを優先し、それでも同点なら tool_uses が少ないほうを優先します。

ペアワイズ比較に関する注意点：

• サブエージェントに「A と B のどちらがよいか」を直接評価させてはいけません。LLM の位置バイアスや自己選好バイアスにより、サンプル数が少ない場合は判断にばらつきが生じます。
• 客観的な評価軸（正確性、ステップ数、不明瞭な点の数、フェーズごとの弱点数）のみで比較します。これらは再現可能ですが、「どちらのプロンプトのほうがよく感じたか」は再現可能ではありません。
• 定性的な比較がどうしても必要な場合は、順序を入れ替えて（A、B）と（B、A）の両方を実行し、どちらの順序でも判断が一致した場合にのみ結論を採用します。

コスト：バリエーションの検討では、1回の反復あたりの起動数が2倍になります。停滞が疑われる場合に実施し、通常は行いません。

提示形式

各反復で、次の形式を使用して記録し、ユーザーに提示します。

## Iteration N

### Changes (diff from previous)
- <one-line fix content>
- Pattern applied: <pattern name from ledger, or "(new)">

### Execution results (per scenario)
| Scenario | Success/Failure | Accuracy | steps | duration | retries | Weak phase |
|---|---|---|---|---|---|---|
| A | ○ | 90% | 4 | 20s | 0 | — |
| B | × | 60% | 9 | 41s | 2 | Execution |

### Structured reflection (newly surfaced this time)
- <Scenario B>: [critical] item N is × — <one-line reason for drop>
  - Issue: <what observably happened>
  - Cause: <why, at the instruction level>
  - General Fix Rule: <class-level abstraction>
- <Scenario A>: (nothing new)

### Discretionary fill-ins (newly surfaced this time)
- <Scenario B>: <fill-in content>

### Ledger updates
- Added: <pattern name> (from Scenario B)
- Re-seen: <pattern name> (originally iter K) — existing fix did not prevent recurrence because <reason>

### Next fix proposal
- <one-line minimum fix>

(Convergence check: X consecutive clears / Y rounds remaining to stop condition)

危険信号（正当化に注意）

表面化する正当化	実態
「自分で読み返しても同じ効果がある」	書いたばかりの文章を「客観的に」見ることはできません。必ず新しいサブエージェントを起動してください。
「シナリオは1つで十分」	1つのシナリオでは過剰適合します。最低2つ、理想的には3つ必要です。
「不明瞭な点が一度ゼロになったので、完了です」	偶然かもしれません。2回連続でクリアしてから完了としてください。
「不明瞭な点を複数まとめて一気に解消しよう」	何が効果的だったのか追跡できなくなります。1回の反復につき1つのテーマにしてください。
「関連する小さな修正はそれぞれ厳密に別の反復に分けよう」	逆方向の落とし穴です。「1つのテーマ」とは意味上のまとまりです。関連する小さな修正は2〜3個まとめて、1回の反復で扱えます。細かく分けすぎると、反復回数が膨らみます。
「指標が良いので、定性的なフィードバックは無視しよう」	時間の短縮は、内容が薄すぎる兆候でもあります。定性的な評価を第一にしてください。
「最初から書き直したほうが速い」	3回以上の反復を経ても不明瞭な点が減らない場合は適切です。それより前の段階では、現実からの逃避です。
「同じサブエージェントを再利用しよう」	そのサブエージェントは以前の改善内容を学習しています。必ず新しいものを起動してください。

よくある失敗

• シナリオが簡単すぎる／難しすぎる：どちらも有益な判断材料になりません。実際の利用の中央値に当たるものを1つ、境界的なものを1つ用意します
• 指標だけを見る：時間短縮だけを追うと、重要な説明が削られ、壊れやすくなります
• 1回の反復で変更しすぎる：「以前どの修正が効果的だったのか」を追跡できなくなります。1回の反復につき修正は1つです
• 修正に合わせてシナリオを調整する：不明瞭な点が解消されたように見せるためだけにシナリオを簡単にするのは、本末転倒です

関連項目

• superpowers:writing-skills — スキル作成における TDD アプローチです。基本的には、このスキルの「ベースライン → 修正 → サブエージェントで再実行」と同じです
• retrospective-codify — タスク完了後に学びを定着させます。このスキルはプロンプト開発中に使い、retrospective-codify はタスク終了後に使います。用途に応じて使い分けてください
• superpowers:dispatching-parallel-agents — 複数のシナリオを並行して実行する際の規約です
• waxa-eval — waxa CLI の操作マニュアルです。YAML シナリオ形式と永続化される台帳を使い、評価と反復のループを外部プロセスで自動化します。このスキル（empirical-prompt-tuning）では、手法とセッション内の Task ツールによるサブエージェントのフローを扱い、waxa-eval ではCLI の操作と YAML の作成を扱います。両者は補完し合う関係です。CLI プロセスからは利用できない Iter 0 の静的チェック、[critical] タグ付きチェックリスト、tool_uses に基づくスキル診断には empirical を使い、永続化、CI での再現性、外部導入のゲートが必要な場合は waxa-eval を使ってください。