---
name: tune-prompt
description: >-
  agent 向けの指示（skill / エージェント設定 / タスクプロンプト等）を、
  白紙のエージェントに実行させて品質を検証し、伝わらなかった箇所を修正するサイクルを回す。
  プロンプトや skill を作った直後、またはエージェントが期待通りに動かないときに使う。
  Use when tuning prompts or skills empirically with fresh executors and measurable criteria.
---

# Tune Prompt

対象のプロンプトや skill を **白紙のエージェントに実行させ、伝わらなかった箇所を特定して修正する** サイクルを回す。評価は「実行者の自己申告（どこで詰まったか）」と「要件チェックリストの達成率」の両面で行う。自分で読み返すのではなく、必ず別のエージェントに渡す。

## いつ使うか

- skill やプロンプトを新規作成・大幅改訂した直後
- エージェントが期待通り動かず、指示の曖昧さが原因かもしれないとき
- よく使う skill を堅牢にしたいとき

使わない場面:

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

## 前提

- Task tool やサブエージェント等、**新規コンテキストのエージェントを起動できる** こと。起動できない環境ではこのスキルは適用しない（ユーザーに別チャットでの実行を依頼するか、スキップを報告する）。
- 自分で読み返して代替するのは **NG**。書いた直後の文章にはバイアスが入るため、評価結果を信用できない。

## 準備

### 対象プロンプトの事前チェック

実行者に渡す前に、対象プロンプトの **frontmatter `description` と本文の整合性** を確認する。description が「A と B ができる」と謳っているのに、本文が A しかカバーしていない場合、実行者は description に引きずられて skill を「いい感じに解釈」してしまう。先に合わせておく。

### 評価シナリオの設計

対象プロンプトを実際に使う場面を **2〜3 個** 想定する。

- **典型ケース 1 つ**: 最もよくある使い方
- **エッジケース 1〜2 つ**: 境界条件や例外的な状況

1 つだけだとそのシナリオに最適化されてしまう。最低 2 つ。

### 要件チェックリストの作成

シナリオごとに、成果物が満たすべき要件を **3〜7 項目** で書く。最低 1 つに `[critical]` をつける。

```
1. [critical] 出力が指定のフォーマットに従っている
2. エラーケースが考慮されている
3. コード例が動作する
```

- `[critical]` が全て ○ → 成功、1 つでも × → 失敗
- 精度 = ○ の項目数 / 全項目数（部分的は 0.5 として計算）

シナリオも要件も **事前に固定する**。結果を見てから調整しない。

## 実行サイクル

以下を **不明瞭点がなくなるまで** 繰り返す。

### 1. 新規エージェントに実行させる

Task tool 等で **白紙のエージェント** を起動し、以下を渡す:

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

## 対象プロンプト
<全文を貼る or パスを指定>

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

## 要件チェックリスト
1. [critical] <項目>
2. <項目>
3. <項目>

## やること
1. 対象プロンプトに従ってシナリオを実行し、成果物を生成してください。
2. 終了後、以下のレポートを返してください。

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

複数シナリオを並列で走らせる場合は、1 メッセージ内で複数の Task を同時に呼ぶ。

### 2. レポートを読んで記録する

返ってきたレポートから以下を抜き出す:

- **不明瞭点**: どの記述で詰まったか（改善のヒントはここにある）
- **裁量補完**: プロンプトに書かれていないが実行者が勝手に判断したこと（暗黙の仕様の発見）
- **要件達成**: 各項目の ○ / × / 部分的 と精度
- **再試行回数**: 曖昧な指示のシグナル

ステップ数（tool_uses）が取得できる場合は記録する。シナリオ間で大きな差がある場合、ステップ数が多いシナリオに対する説明が skill 内に足りていない。

### 3. プロンプトを修正する

不明瞭点を **1 テーマ分だけ** 修正する。修正前に「この変更で要件チェックリストのどの項目が改善されるか」を明言する。

- 関連する微修正 2〜3 件は 1 回にまとめてよい
- 無関係な修正は次のサイクルに回す

### 4. サイクルを続けるか判断する

**次のエージェントには必ず新規を使う**（前回の実行者は改善内容を覚えている）。

- **続ける**: 新しい不明瞭点がまだ出ている
- **止める**: 連続 2 回で新規の不明瞭点が 0、かつ精度改善が +3 ポイント以下
- **設計を見直す**: 3 回以上回しても不明瞭点が減らない → 修正ではなくプロンプトの構造自体を書き直す
- **打ち切る**: 改善コストが重要度に見合わなくなったら 80 点で出す

## 報告フォーマット

各サイクルの結果を次の形でユーザーに報告する:

```markdown
## サイクル N

### 今回の修正
- <修正内容 1 行>

### 実行結果
| シナリオ | 成功/失敗 | 精度 | 不明瞭点 | 裁量補完 |
|---|---|---|---|---|
| A | ○ | 90% | 0 件 | 0 件 |
| B | × | 60% | 2 件 | 1 件 |

### 不明瞭点の詳細
- <シナリオ B>: [critical] 項目 N が × — <理由>
- <シナリオ B>: <その他>

### 裁量補完の詳細
- <シナリオ B>: <内容>

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

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

## 注意

- **自分で読み返して済ませない**。必ず別のエージェントに渡す。
- **シナリオは最低 2 つ**。1 つだとそのシナリオへの過適合を見逃す。
- **1 サイクル 1 テーマ**。複数を一気に直すと何が効いたか追えなくなる。
- **数値だけ追わない**。精度やステップ数の改善だけを目的にすると、必要な説明が削られて脆くなる。不明瞭点と裁量補完を主に見る。
- **シナリオを結果に合わせない**。不明瞭点を消すためにシナリオを簡単にするのは本末転倒。