---
name: refine-prompt
description: >
  agentへのテキスト指示を、バイアスを排した実行者として動作するサブエージェントに読ませて改善提案リストを得て、
  人間が採否判断しながら反映する手法。
  対象はskill・slash command・タスクプロンプト・CLAUDE.md節・コード生成プロンプトなど。
  プロンプトやskillを新規作成・大幅改訂した直後、
  またはエージェントの挙動が期待通りにならない原因を指示側の曖昧さに求めたい場合に使用する。
# 元ネタ: https://zenn.dev/mizchi/articles/empirical-prompt-tuning
---

# プロンプトの改善案の検討

## 使用条件

frontmatterの発火条件に加えて、頻繁に使うskillや自動化の中核プロンプトを堅牢化したい場合にも使う。
挙動の不一致を起点にする場合は、指示文の追記へ進む前に`agent-toolkit/rules/01-agent.md`「規定の区分と標示」に従い、工程の変更と機械化を評価する。

## 使用しない条件

- 単発利用のプロンプト（サブエージェント起動コストに見合わない）
- 再現可能な品質改善ではなく、書き手の主観的選好を反映したい場合

新規サブエージェントを起動できない環境での扱いは「環境制約」節に従う。

## ワークフロー

本スキルはPlan modeの外で実行する。実行環境がPlan modeを提供する場合はPlan modeを抜けてから開始する。Claude Codeでは`ExitPlanMode`を使う。
`agent-toolkit:plan-mode`スキルは呼び出さない
（ユーザーが提示された改善案の採否を対話的に判断する前提であり、計画ファイル化が必要な場合はユーザーが別途指示するため）。

1. メインは`agent-toolkit:writing-standards`スキルを呼び出す。
2. 対象プロンプトを確定し、シナリオを与えるかを決める。
   シナリオを与える場合はサブエージェントが対象プロンプトに従って実行し、解釈に迷った点・裁量補完点も踏まえて指摘を返す。
   シナリオを与えない場合はサブエージェントが対象プロンプトを批判的に通読し、
   不明瞭・冗長・不足・誤り・過剰な指定などの観点で指摘を返す。
   サブエージェントの起動と終端観測は`agent-toolkit:delegation`に従う。
   シナリオ実行では前提知識のない実行者として読ませるため作成規範を渡さず、批判的通読では`agent-toolkit:writing-standards`の「エージェント向け文書の編集時に読む資料」を読ませる。
3. メインは対象の分量と論点数に応じて、サブエージェントの起動数を1体以上として決める。
   観点の多様性を確保するため、複数体を起動する場合は並列実行する。
   並列起動できない環境の扱いは「環境制約」節を参照する。
4. 各サブエージェントから戻った指摘を集約する。
   改善案を作成してユーザーへ提示する。
   詳細は「指摘の集約と改善案作成」節に従う。
5. 全処理が完了したら、続行か終了かをユーザーに確認する。
   - 続行する場合は新規サブエージェントで再評価する
   - ユーザーが終了を告げた時点で評価の反復を終える。反映後は対象の編集手順を定めるスキル（`agent-toolkit:writing-standards`など）、`agent-toolkit:check-execution`および`agent-toolkit:completion-report`の工程へ進む

## サブエージェントへの指示

サブエージェントに渡すプロンプトは次の構造を取る。
サブエージェントは指摘の列挙だけを担い、改善案・修正後文言・diffの提示はメインが担う。
サブエージェントには、見つけた指摘をすべて重要度付きで重要度の高い順に返すよう求める。取捨選択はメインが行う。

````text
あなたは <対象プロンプト名> を前提知識を持たずに読む実行者です。

## 対象プロンプト
<対象プロンプトの本文を全文挿入する、または Read で読ませるパスを指定>

## シナリオ（任意）
<シナリオの状況設定を1段落。指定がなければ「シナリオなし。批判的読みのみ」と記載>

## タスク
1. シナリオが指定されていれば、対象プロンプトに従って実行し、解釈に迷った点・裁量で補完した点を記録する。
   シナリオが指定されていなければ、対象プロンプトを通読し、不明瞭・冗長・不足・誤り・過剰な指定を洗い出す。
   シナリオが無い場合は、`agent-toolkit:writing-standards`の「エージェント向け文書の編集時に読む資料」の基準も使う。
2. 重要度の高い順に指摘を後述のフォーマットで返す。
   重要度は「実害の大きさ・改善幅・適用頻度」を基準に判定する。
   範囲は発動条件・本文構造・記述精度・冗長性・命名・例示・整合性などを幅広く対象とする。
   取捨選択はメインが行うため、重要度の低い指摘も省かず重要度を付けて返す。
   文脈追跡を要する記述（他指摘への暗黙参照）は使わず、
   各指摘が単独で読み取れる粒度に揃える。
   改善案・修正後文言・diffは書かず、問題の所在と内容のみを返す。

## 指摘フォーマット（1件ごとに繰り返す）
### 指摘 N: <問題箇所を1行で>
- 該当箇所: <対象プロンプト中の引用または位置を1〜2文で>
- 問題内容: <何が問題か1〜2文>
- 想定される悪影響: <この問題を放置すると何が起きるか1文>
- 種別: 不明瞭 / 冗長 / 不足 / 誤り / 過剰な指定 / その他
````

## 指摘の集約と改善案作成

メインはサブエージェントから戻った指摘を集約・統廃合し、各指摘に対応する改善案を作成してユーザーに提示する。

- 統廃合: サブエージェント間で重複する指摘は1件にまとめ、近接する指摘も意図を保てる範囲でメインが統合する
  - 統廃合はメインだけが担う
- 取捨選択: 些末な指摘や的外れな指摘がサブエージェントから返ってきた場合は、メインの責任で除外する
  - メインは`agent-toolkit:review-standards`を起動し、`references/reviewee.md`に従って指摘ごとの採否を確定する。定義元の内容の転記を求める指摘は、`agent-toolkit:writing-standards`の`references/agent-documents-basics.md`「責務と構成」を読んで判定する
  - 各指摘の観点を再評価し、対象プロンプトの目的・スコープから外れたものを除外する
- 改善案の作成: 統廃合・取捨選択後の各指摘について、メインが対応する改善案（変更内容のdiff）を作成する
  - 作成時は事前に呼び出した`agent-toolkit:writing-standards`の基準に従う。エージェント向け文書では同スキルの「エージェント向け文書の編集時に読む資料」を読み、その基準で改善案を作成する
- ユーザーへの提示: 各指摘と改善案を後述フォーマットで本文へ転記する
  - サブエージェントの出力はユーザーに直接表示されないため、指摘部分は原文に近い形で残す
- 採否確認: ユーザー確認し、提案を回答可能な件数ずつまとめる。Claude Codeでは`AskUserQuestion`の`multiSelect`で最大4件ずつ1質問にまとめる
  - 片方だけの採用で本文が矛盾する提案は同じ選択肢にまとめる
  - 各質問本文へ`共通前提:`行を置き、質問本文と各`description`だけで採否を判断できるよう、`description`へ変更前後の要点を書く。各オプションの`label`は「提案N: <変更対象>」とする（努力目標。質問だけで採否を判断できるようにする）
  - チェックされた提案を採用、未チェックを却下として扱う
  - 修正したい改善案がある場合は自動付与の「Other」欄に番号と修正内容を書くよう、質問本文で案内する
- 反映: 採用が確定した改善案を対象プロンプトに反映する
  - 「Other」欄に修正指示があれば、その内容に沿って反映する

### ユーザー提示フォーマット（1件ごとに繰り返す）

````text
### 提案 N: <変更対象を1行で>
- 指摘元: <サブエージェントが報告した該当箇所と問題内容を1〜2文で>
- 変更理由: <なぜ変更すべきか1〜2文>
- 変更内容: 以下のdiff形式で示す。新規追加なら`+`のみ、削除なら`-`のみでよい

  ```diff
  - <現在の文言>
  + <変更後の文言>
  ```

- 期待効果: <この変更で何が改善するか1文>
- 追随対象: <採用時に追随する他の文書・記述。無い場合は「なし」>
- 種別: 加筆 / 書き換え / 削除
````

## 環境制約

`agent-toolkit:delegation`が定める委譲手段を利用できない環境では、
同一セッション内で直接評価を実施し、結果提示時に「サブエージェント不可のため直接評価」と明記する。

## 運用上の遵守事項

- サブエージェントは継続時も毎回新規に起動する。同一サブエージェントの再利用は前回の改善提案を学習しているため評価が偏る
- シナリオは初回設定のまま用い、修正に合わせて容易化しない。不明瞭点が解消したように見せる調整は本末転倒となる