empirical-prompt-tuning

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 的环境中（例如已作为 subagent 运行、Task tool 已停用等），不适用本 skill。

• 替代方案 1：请父会话中的用户启动另一个 Claude Code 会话来执行
• 替代方案 2：放弃评估，并明确告知用户“empirical evaluation skipped: dispatch unavailable”
• 禁止：用自行重读代替（这会引入偏差，因此不能相信评估结果）

结构审查模式：如果想检查的不是 empirical 评估，而仅是 skill / 提示词的描述一致性与清晰度，请明确将其划分为结构审查模式。在委托给 subagent 的提示词中注明“本次为结构审查模式：检查文本一致性，而非执行”。这样 subagent 就不会受环境限制条款中的 skip 行为影响，可以返回静态审查结果。结构审查是 empirical 评估的补充，而非替代（不能用于判定连续通过）。

反复迭代的停止标准

• 收敛（停止）：连续 2 次同时满足以下所有条件：
  • 新增不明确点：0 项
  • 相较上次的准确度提升：不超过 3 个百分点（例如从 5% 提升到 8% 后进入饱和）
  • 相较上次的步骤数变化：在 ±10% 以内
  • 相较上次的 duration 变化：在 ±15% 以内
  • 过拟合检查：判定收敛时，额外加入 1 个此前未使用的 hold-out 场景进行评估。如果准确度比近期平均值低 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 回）

警示信号（警惕自我合理化）

出现的自我合理化	实际情况
“自己重读一遍也有同样效果”	无法“客观看待”刚写好的文本。必须调度新的 subagent。
“1 个场景就够了”	1 个场景容易过拟合。至少 2 个，最好 3 个。
“不明确点为零出现过 1 次，就可以结束了”	可能只是偶然。连续 2 次才能确认。
“一次性消除多个不明确点吧”	会搞不清哪些改动起了作用。每次迭代聚焦 1 个主题。
“相关的微小修改也要严格地每项单独拆成 1 次迭代”	这是反方向的陷阱。“1 个主题”是指意义单元。相关的 2～3 项微小修改可以合并到 1 次迭代中。拆得过细会导致迭代次数激增。
“指标很好，所以忽略定性反馈”	缩短时间也可能意味着内容过于单薄。应以定性反馈为主。
“重写更快”	如果连续 3 次以上都未减少不明确点，这就是正确做法。在此之前，这是在逃避。
“继续使用同一个 subagent”	它已经了解上次的改进。每次都要调度新的 subagent。

常见失败

• 场景太简单 / 太难：两者都无法提供有效信号。选择 1 个贴近真实使用场景中位数的场景，再加 1 个 edge 场景
• 只看指标：如果只追踪时间缩短，重要说明就会被删掉，令结果变得脆弱
• 每次迭代改动太多：无法追踪“当时哪些修改起了作用”。每项修改对应 1 次迭代
• 为了配合修改而调整场景：为了让不明确点看起来已被消除而简化场景 → 本末倒置

相关内容

• superpowers:writing-skills — 创建 skill 时采用的 TDD 方法。本 skill 的“通过 subagent 执行 baseline → 修改 → 重新运行”与之本质相同
• retrospective-codify — 固化任务后的经验。本 skill 用于开发提示词期间，retrospective-codify 用于任务结束后，应区分使用
• superpowers:dispatching-parallel-agents — 并行运行多个场景时的做法