empirical-prompt-tuning

Empirical Prompt Tuning

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

いつ使うか

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

使わない場面:

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

ワークフロー

1. 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）

2. ベースライン準備: 対象プロンプトを確定し、次の 2 つを用意する。

   • 評価シナリオ 2 〜 3 種（中央値 1 + edge 1 〜 2）。現実に起こりうるタスクで、対象プロンプトを実際に適用する場面を想定する。
   • 要件チェックリスト（精度算出のため）。シナリオごとに「成果物が満たすべき要件」を 3 〜 7 項目で列挙する。精度 % = 満たした項目数 / 全項目数。事前に固定すること（後から動かさない）。

3. バイアス排除読み: 指示を「白紙」の実行者に読ませる。Task tool で 新規 subagent を dispatch する。自己再読で済ませない（直前に書いた文章を客観視することは構造的に不可能）。並列で複数シナリオを同時実行する場合は単一メッセージ内で複数 Agent 呼び出しを並べる。dispatch 不能環境の扱いは「環境制約」節を参照。

4. 実行: 後述の subagent 起動契約 に従ったプロンプトを subagent に渡し、シナリオを実行させる。実行者は実装や出力を生成し、最後に自己申告レポートを返す。

5. 両面評価: 戻ってきた結果から次を記録する。

   • 実行者の自己申告（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] の付け外しをしない。

6. 差分適用: 不明瞭点を潰す最小修正をプロンプトに入れる。1 イテレーション 1 テーマ（関連する複数修正は OK、無関係な修正は次回に回す）。

   • 修正前に「この修正が要件チェックリスト / 判定文言のどの項目を満たすか」を明示する（軸名から推測した修正は届かないことが多い。後述「修正の波及パターン」節）。

7. 再評価: 新しい subagent で再度 2 → 5 を回す（同一 agent は再利用しない: 前回の改善を学習している）。並列度はイテレーションを進めても改善が頭打ちにならない場合に増やす。

8. 収束判定: 目安「連続 2 イテレーションで新規の不明瞭点ゼロ かつ メトリクス改善が閾値以下（後述）」で停止。重要度が高いプロンプトは 3 連続にする。