| name | empirical-prompt-tuning |
| description | agent 向けの skill、slash command、AGENTS.md/CLAUDE.md 節、タスクプロンプト、コード生成プロンプトを実証的に改善する。新規作成または大幅改訂した指示の明瞭性、trigger と本文の整合、実行時の不明瞭点、裁量補完、成功率を検証したいときに使う。 |
| metadata | {"short-description":"agent 向け指示を実証評価して改善する"} |
Empirical Prompt Tuning
agent 向け指示は、書いた本人が明瞭だと思っていても、別の実行者が読むと詰まることがある。この skill は、指示を静的に点検し、必要に応じて新規 agent に実行させ、実行者の自己申告と固定チェックリストの両面から改善点を出すための手順である。
元の考え方は Claude Code 向けの empirical prompt tuning だが、この版では Codex の制約に合わせる。特に、Codex では subagent の利用はユーザーが明示した場合だけに限る。
モード選択
最初に、今回どのモードで進めるかを判定する。
- 構造審査モード: ユーザーが「確認して」「レビューして」「最適化して」などと言い、subagent 評価を明示していない場合。新規 agent は使わず、description/body の整合、曖昧さ、評価シナリオ、改善案を出す。
- empirical 評価モード: ユーザーが「subagent で評価」「並列 agent で検証」「empirical evaluation」「バイアス排除読み」などを明示した場合。新規 agent を使ってシナリオ実行まで行う。
- 編集モード: ユーザーが skill やプロンプトの配置・修正を依頼した場合。構造審査を先に行い、最小差分で編集する。評価実行は明示がある場合だけ行う。
迷った場合は構造審査モードを選ぶ。自己再読だけを empirical 評価として扱ってはいけない。
対象
この skill は次のようなテキスト指示に使う。
SKILL.md- slash command や task prompt
AGENTS.md / CLAUDE.md / 運用ルールの一節- コード生成、レビュー、調査、通知、リリース作業などの agent 向け定型プロンプト
使わない場面:
- 一回限りの使い捨てプロンプト
- 成功率ではなく、書き手の好みだけを反映したい場合
- ユーザーが速度優先で、評価コストを避けたいと明示している場合
Workflow
0. Static Consistency Check
dispatch は不要。対象文書を読み、次を確認する。
- frontmatter
description が謳う trigger、用途、成果物
- body が実際にカバーしている手順、制約、出力
- description が広すぎないか、body が狭すぎないか
- skill 名、trigger、本文、関連リソースの読み方が食い違っていないか
乖離がある場合、Iteration 1 に進む前に description か body を合わせる。ここを飛ばすと、実行者が description から勝手に意図を補い、skill 本体が弱いのに成功したように見える。
1. Baseline Setup
対象プロンプトを固定し、評価に使う材料を先に決める。後から都合よく動かさない。
- 評価シナリオ: 2-3 件。中央値 1 件、edge 1-2 件。
- 要件チェックリスト: シナリオごとに 3-7 項目。
[critical] 項目: 各シナリオに最低 1 件。これが落ちたら成功扱いにしない。
チェックリストは、実行結果から客観的に判定できる粒度で書く。曖昧な「よい感じ」「適切に」は避ける。
2. Empirical Dispatch
この手順は、モード選択で empirical 評価モードと判定した場合だけ行う。
- シナリオごとに新規 agent を起動する。
- 同じ agent を次 iteration に使い回さない。前回の文脈を学習してしまうため。
- 評価 agent には原則としてファイル編集をさせない。成果物や判断をレポートで返させる。
- 編集を伴う検証が必要な場合は、作業範囲と保存先を明示し、既存差分を壊さないように指示する。
Codex では spawn_agent を使う。並列実行する場合でも、各 agent のタスクは独立したシナリオに分ける。
3. Runner Prompt Contract
評価 agent へ渡すプロンプトは次の形にする。
あなたは <対象プロンプト名> を白紙で読む実行者です。
## 対象プロンプト
<対象プロンプト本文、または読むべき絶対パス>
## シナリオ
<現実に起こりうる状況を 1 段落で説明>
## 要件チェックリスト
1. [critical] <最低ラインに含む項目>
2. <通常項目>
3. <通常項目>
## タスク
1. 対象プロンプトに従ってシナリオを実行してください。
2. 原則としてファイルは編集しないでください。編集が必要だと判断した場合は、その必要性をレポートに書いてください。
3. 最後に次のレポート構造で返答してください。
## レポート構造
- 成果物: <生成物または実行結果サマリ>
- 要件達成: 各項目について ○ / × / 部分的（理由付き）
- 不明瞭点: 対象プロンプトで詰まった箇所、解釈に迷った文言
- 裁量補完: 指示で決まっておらず自分の判断で埋めた箇所
- 再試行: 同じ判断をやり直した回数と理由
- 探索量: 読んだ主要ファイル、使った主要ツール、迷った分岐の概算
Evaluation
戻ってきた結果を次の軸で評価する。
| 軸 | 判定方法 | 重み |
|---|
| 成功/失敗 | [critical] がすべて ○ なら成功。それ以外は失敗 | 高 |
| 精度 | ○ = 1、部分的 = 0.5、× = 0 として達成率を算出 | 高 |
| 不明瞭点 | 実行者が詰まった文言や不足情報 | 高 |
| 裁量補完 | 実行者が独自判断で埋めた仕様 | 高 |
| 再試行 | 同じ判断をやり直した回数 | 中 |
| 探索量 | 読んだファイル、使ったツール、分岐の概算 | 低 |
| 所要時間 | 親側で観測できる範囲の概算 | 低 |
Claude Code 版の tool_uses / duration_ms は Codex では安定して取得できないことがある。取れないメトリクスを無理に主指標にせず、質的フィードバックと固定チェックリストを主にする。
Iteration Rules
- 1 iteration では 1 テーマだけ直す。関連する 2-3 件の微修正は同じテーマならまとめてよい。
- 修正前に「この修正がどの要件または不明瞭点に効くか」を明示する。
- シナリオやチェックリストを、修正に合わせて簡単にしない。
- 3 iteration 続けても不明瞭点が減らない場合は、小パッチではなく構造の書き直しを検討する。
Stop Criteria
empirical 評価モードでは、次を目安に停止する。
- 連続 2 iteration で新規不明瞭点が 0 件
- 精度改善が +3 ポイント以下
- 成功/失敗が安定している
- hold-out シナリオで直近平均から 15 ポイント以上落ちない
- 追加評価コストに対して改善見込みが小さい
重要度が高い skill では、連続 3 iteration まで見る。
Report Format
ユーザーへは次の形で簡潔に報告する。
## Iteration N
### 変更点
- <前回からの最小差分>
### 実行結果
| シナリオ | 成功 | 精度 | retries | 探索量 |
|---|---|---:|---:|---|
| A | ○ | 100% | 0 | 低 |
| B | × | 60% | 2 | 高 |
### 新規の不明瞭点
- <シナリオ B>: [critical] 項目 N が ×。<理由>
### 裁量補完
- <シナリオ A>: <実行者が補った判断>
### 次の修正
- <次に入れる 1 テーマの修正>
構造審査モードでは、実行結果表は出さず、次だけ返す。
- description/body の整合
- 曖昧な箇所
- 不足している実行契約
- 推奨する最小修正
- empirical 評価を行う場合のシナリオ案
Red Flags
- 自分で読み直した結果を empirical 評価と呼ぶ。
- 1 シナリオだけで成功判定する。
[critical] を後から付け替える。- 不明瞭点を一気に全部潰して、何が効いたか分からなくする。
- メトリクスだけを見て、実行者の不明瞭点と裁量補完を無視する。
- 同じ subagent を再利用する。
description の trigger を強くしすぎて、body が対応していない用途まで発火させる。
Codex Notes
spawn_agent を使うかどうかは、モード選択の条件を満たす場合のみとする。- 評価 agent に編集させる場合は、書き込み範囲を分ける。読み取りだけで足りる評価では no-edit を維持する。
- ローカルファイルを参照させる場合は絶対パスを渡す。
- 既存の未コミット差分はユーザー作業の可能性があるため、評価や修正で巻き戻さない。
