--- name: refine-prompt user-invocable: false description: > エージェントへの指示文を前提知識のない評価担当に読ませ、解釈に迷う箇所の指摘を集めて反映する。 繰り返し使うスキル、役割文書、毎回読み込む規範の節を新しく作ってレビューへ渡す前と、 指示と挙動の食い違いを原因分析して指示文の改訂が必要と確定した時に、エージェントが自分で起動する。 引数auditでは、モデルやホストの更新を契機にエージェント向け文書を点検し、採否・編集をせず提案一覧を返す。 # 元ネタ: https://zenn.dev/mizchi/articles/empirical-prompt-tuning --- # プロンプトの改善案の検討 エージェントへの指示文を、前提知識を持たないプロンプト評価担当に読ませて指摘を集める。 メインエージェントはその指摘をもとに改善案を作成し、採否を判断して反映する。 評価担当の内部手順は`${CLAUDE_PLUGIN_ROOT}/share/refine-prompt.subagent.md`が定める(所在参照)。 起動と受領の手順は、本書の「プロンプト評価担当の起動と受領」、返却形式は「評価担当の返却契約」に従う。 引数が`audit`の場合は「文書の点検」を実施し、提案一覧を返して終了する。 引数なしの場合は既存のワークフローに従う。 評価担当の起動や試行には、委譲手段、参照資料、対象の実行環境が必要となる。 これらを利用できない環境では、提示されたプロンプトを現在のセッション内で直接評価する。 その際は、直接評価である事実と、未実施の試行内容を明記する。 独立した担当による試行やファイルへの反映は、委譲を実行できるClaude CodeやCodexで継続する。 指摘や改善案の文面を作成する際は、[文章の品質基準](references/quality-standards.md)を適用する。 ## 名指し参照の読込方法 名指し参照は`agent-basics:writing-standards/references/read-method.md`に従う。 | 時点または条件 | 全文読む資料 | | --- | --- | | 本文がこの資料の基準を使う場面で、資料を選択して取得する時 | `../user-confirmation-and-report/references/user-confirmation-and-report-decisions.md` | ## 読込表 | 時点または条件 | 全文読む資料 | 契機 | 配送操作 | 資料選択子 | | --- | --- | --- | --- | --- | | 改善案を作成する前(エージェント向け文書が対象の場合) | `agent-basics:writing-standards/SKILL.md` | | | | | 対話と成果物を評価する多ターン試行を選んだ時と結果を受領する時 | `references/multi-turn-trials.md` | 判断 | `delegation-result`、`read:agent-toolkit:*/skills/refine-prompt/references/multi-turn-trials.md` | | | 実セッションから小課題を作り、条文変更の効果を比較する方法を選んだ時 | `references/multi-turn-trials.md` | | | | | `audit`で文書を点検する前 | `agent-basics:writing-standards/references/agent-documents-additions-volume.md`、`agent-basics:writing-standards/references/host-official-references.md` | 判断 | `skill:refine-prompt` | | ## 使用条件 起動の契機は、文書を新しく作る作業と指示文を改訂する作業の前に読む`references/evaluation-triggers.md`と、文書の点検を求める作業項目が定める。 対象は利用頻度の高いスキルと自動化の中核となる文書に限り、起動コストに見合わない単発のプロンプトや、作成者の主観的な好みを反映するだけの作業は除外する。 この除外は本スキルという手段の選択に限定する。 プロンプトの欠陥が品質(Quality)に影響する場合は、`agent-basics:bugfix/references/root-cause-severity-impact.md`「QとC・Dの区別」に従って処置の要否を判断する。 指示と挙動の不一致を問題として調査するときは、原因を指示の曖昧さに限定せず、評価や追記案の検討に先立って`agent-basics:bugfix`を起動する。 初動対応・原因分析・対策選定を進めた結果、指示文の改訂が必要と判断された場合に本スキルを適用する。 通常のプロンプト改善は、この不具合調査の流れとは区別して進める。 ## 文書の点検 引数`audit`で起動する点検は、モデルやホストの更新を契機に文書を見直すための、読み取り専用の点検である。 費用のかかる通読を必要な文書に限るため、検索による判定と評価担当の通読の2段階で行う。 点検観点と削減の判断基準は`agent-basics:writing-standards/references/agent-documents-additions-volume.md`「文書記述量の管理」に従う。 1. 常時配送される規範(`share/rules/common/`と`share/rules/rules-main*.md`などの起動時本文)、agent-basics・agent-toolkitのスキル本体とreferences、hookがエージェントへ返す通知文を列挙する。 配送元の定義を使い、点検済みと未点検を区別する。 ホストの更新による点検では、変更履歴の該当項目と関係する規範だけを対象にする。 2. 処理するセッションのモデル・ホストに対応する公式プロンプトガイドを、`agent-basics:writing-standards/references/host-official-references.md`から確認する。 対象の版と適用条件を確かめ、点検対象の一覧と取得した一次資料の保存先を点検資料へまとめる。 3. 1段階目として、対象の全ファイルを点検の観点ごとに検索し、該当箇所を読んで判定する。 ファイルごとに、該当なし、提案あり、本文を読まないと判定できない、のいずれかと、検索語・一致件数を記録する。 4. 2段階目として、「プロンプト評価担当の起動と受領」から、前提知識のない担当へ対象本文を渡す。 対象は常時配送される規範と、1段階目で本文を読まないと判定できなかった文書に限る。 `シナリオ`は`なし`とし、`点検資料`へ手順2の資料の絶対パスを指定する。 対象が多い場合は、既存の委譲基準に従い点検範囲を分け、全範囲の結果を回収する。 5. 指摘を観点ごとの提案一覧へまとめ、提案ごとに対象ファイル・該当箇所・観点・根拠・推奨する処置を残す。 対象の全ファイルについて、1段階目の判定と評価担当が通読したかを示し、未点検範囲と未試行の比較も明示する。 採否判断と文書の編集には進まない。 6. 一覧を自身のmanaged-tempへ保存し、ユーザーへ本文と保存先を届けて終了する。 自律処理では報告用UWIにより届け、委譲先は一覧と保存先を委譲元へ返す。 提案に基づく編集はユーザーの採否を得た後に別のAWIとして扱う。 点検記録(点検した日付、基準にしたガイド、モデルID、ホストごとの確認済みの版、提案一覧の保存先)を、プロジェクトが点検の要否の判定に使う記録へ追加または更新する。 ## ワークフロー 1. 品質基準を揃えるため、Plan modeの外で実行し(Claude Codeでは`ExitPlanMode`)、`agent-basics:writing-standards`を呼び出す。 問題起点では「使用条件」で確定した原因と対策の範囲を入力とし、原因は調査結果で確定し、評価担当の指摘は参考情報とする。 元依頼の計画作成要否は変わらず、`agent-toolkit:write-plan`の呼び出しは不要である。 2. 公平に比較できるよう、対象と目的に応じて手法を選ぶ。 通常の評価はシナリオを与えた読み取り専用の単発評価とし、反復評価のシナリオは初回と同じ内容を維持する。 シナリオなしの通読は、同じ基準を適用する実行レビューと役割が重なるため、「文書の点検」だけで使う。 実際の操作・対話・成果物を採点する多ターン試行は、`references/multi-turn-trials.md`に従い、独立した2つの役割を起動できる環境で手動実行する。 結果の差異は、同一事例における観測事実として受け取る。 既存の固定課題や単発評価で判断できる場合はその結果を活用する。 実セッションに基づく比較が採否の判断に不可欠な場合に限り、同資料の「実セッション由来の小課題による比較」を選択する。 3. 独立した評価を得るため、分量や論点数から人数を決め、「プロンプト評価担当の起動と受領」の手順4・5へ進む。 委譲手段(`agent-toolkit:delegation`)を利用できない環境では、同一セッション内で直接評価を実施し、結果を提示する際に「プロンプト評価担当を起動できないため直接評価」と明記する。 ## プロンプト評価担当の起動と受領 ```text 起動対象: refine-prompt.subagent.md ``` 入力の定義はこの起動契約とagents_serverの`start`の検査が所有する。 起動準備はこの契約の入力一覧で完結する。 - 必須入力名: `対象プロンプト`、`シナリオ` - 任意入力名: `点検資料` `agent-toolkit:refine-prompt`を実行するエージェントが、本書に従ってプロンプト評価担当を起動し、指摘を受け取る。 プロンプト評価担当の手順は`${CLAUDE_PLUGIN_ROOT}/share/refine-prompt.subagent.md`に従う(所在参照)。 返却形式は本書「評価担当の返却契約」に従う。 ### 起動 4. 同じ条件で評価するため、指示文をUTF-8ファイルへ保存し、決定した人数分を同一入力で並行起動する。 `agents_server`の`start`へ次の引数を渡す。 再評価も新しい担当を起動し、シナリオは改訂内容に合わせず初回のまま渡す(指摘や修正履歴による評価の偏りを防ぐため)。 | 引数 | 値 | | --- | --- | | `cwd` | 対象プロンプトを保持するリポジトリの絶対パス | | `subagent_md_path` | `refine-prompt` | | `extra_params` | 次の名前付き入力だけ | - `対象プロンプト`: 対象プロンプトの名前と、本文を保存したファイルの絶対パス - `シナリオ`: ワークフローで決定した状況設定の1段落。 文書の点検では`なし` - `点検資料`: `audit`の場合だけ指定する、対象一覧と公式一次資料の保存先をまとめたファイルの絶対パス。 通常評価では省略する 単発評価は、読み取り専用で指摘を返却するまでの処理で完結させる。 ### 受領 5. 結果を利用できることを確かめるため、引数なしの`atk agents wait`で受け取り、「評価担当の返却契約」に形式が一致しなければ同一入力で新しい担当を1回だけ再起動する。 委譲元は入力と返却を当初の目的・現行要求と比較して検収し、`${CLAUDE_PLUGIN_ROOT}/share/work-contract-updates.md`「更新する時点」に従って記録を更新する。 `audit`の場合は対象と点検観点、該当文言、行動への影響、根拠、修正案と承認範囲への作用の対応を検収し、「文書の点検」の一覧保存・送達へ進む。 通常評価は「指摘の集約と改善案作成」の手順6へ進む。 多ターン試行を実施する場合は、`references/multi-turn-trials-dialogue.md`「両役の入力と返却」に基づく自由文形式の委譲を利用し、双方のセッション終了、対話履歴全体、提出物、採点結果を受け取る。 多ターン試行の結果は、通常のプロンプト評価担当による指摘一覧とは分離して管理し、機能面、非公開の要件、対話の適切さに関する判定を事例ごとに個別に確認する。 ### 評価担当の返却契約 以下の固定形式のみを返却する。 指摘1件ごとに`### 指摘`の見出しから`種別`の行までを繰り返して記述し、点検時は後述の欄を加える。 ```text 状態: completed ### 指摘 N: <問題箇所を1行で> - 重要度: 高 / 中 / 低 - 該当箇所: <対象プロンプト中の引用または位置を1〜2文で> - 問題内容: <何が問題か1〜2文> - 想定される悪影響: <この問題による行動への影響を1文で> - 種別: 不明瞭 / 冗長 / 不足 / 誤り / 過剰な指定 / その他 ``` 続行不能と追加報告行は、共通契約`../../share/rules/rules-subagent.md`「返却形式の受け渡し」に従う。 入力不足の場合は、対象プロンプトの不足情報と取得不能の根拠を記す。 `点検資料`がある場合は、各指摘へ次の4行を加え、末尾に点検済み・未点検範囲と未試行の比較を記載する。 指摘がない場合も、状態と点検範囲・比較の実施状況を返す。 ```text - 対象ファイル: <対象のパス> - 観点: <点検観点> - 根拠: <一次資料や現物の所在、該当文言、守る価値。仮説は区別する> - 推奨する処置: <具体的な修正案と、承認範囲・権限が広がるかの説明> ``` ## 指摘の集約と改善案作成 6. 元の意図を保つため、メインエージェントは重複や関連する指摘をまとめ、`agent-basics:review-standards`と同スキルの`references/reviewee.md`に基づいて採否を判定する。 転記を求める指摘は`agent-basics:writing-standards/references/agent-documents-basics-ownership.md`「定義の所有者」で評価し、採用する指摘の改善案をdiffで作る。 評価担当の出力はユーザーへ直接表示されないため、指摘の原表現をできる限り保持する。 7. `../user-confirmation-and-report/references/user-confirmation-and-report-decisions.md`「確認要否の判定」に沿って、技術的な指摘の採否を自ら判断して反映する。 目的や期待される結果の変更、あるいはユーザー固有の好みや認可が必要な事項に限ってユーザーに確認する。 8. 元の依頼を完遂するため、反映後は対象の編集手順を定めたスキルと`agent-basics:check-execution`に従う。 必要な評価と反映の後は、確認を挟まず元の残工程へ進む。 依頼の完了時に成果・検証結果を`agent-toolkit:report-completion`の1つの作業完了報告へ集約する。 評価の受領だけで全体を終了せず、同期の振り返りは起動しない。 ## 本文参照の取得条件 | 時点または条件 | 全文読む資料 | | --- | --- | | 固定課題による多ターン試行:両役の入力と返却の基準を適用する前 | `references/multi-turn-trials-dialogue.md` | | ユーザー確認とユーザーへの報告の基準を適用する前 | `../user-confirmation-and-report/SKILL.md` |