refine-prompt

プロンプトの改善

プロセス

1. 評価 -- プロンプトに不足している要素を特定します。

要素	確認事項
タスク	中核となる行動が明確かつ曖昧さなく示されていますか？
制約	長さ、形式、トーン、範囲が定義されていますか？
出力形式	期待する構成が指定されていますか？
コンテキスト	モデルが実行するのに十分な背景情報がありますか？対象読者、入力形式、成功基準、範囲の境界、技術的制約を確認します。
例	期待する出力を明確にするために、例を示すとよいですか？
エッジケース	失敗時の動作や境界条件が扱われていますか？
読者	人間が曖昧さを解消できない状況でも、モデルが解釈できますか？該当する場合は、以下の「機械解析可能なテキスト」を適用します。

2. 書き換え -- 仕様としての言葉に変換します。正確で、命令形にし、不要な文言を省きます。会話ではなく、仕様としてプロンプトを扱います。

3. 検証 -- 評価表に照らして書き換えを確認します。ステップ1で特定した不足事項をすべて解消してください。

ルール

• 長さ：元の0.75～1.5倍にします。簡潔さは重要です。不足している内容だけを加え、曖昧な内容を削ります。
• 行動を変える行だけを残します。「曖昧な内容を削る」と「モデルがすでに行うことを削る」は異なる基準で、後者でははるかに多くの内容が削除されます。命令形にすれば、どの行も曖昧でなくなります。よくある問題は、モデルが標準で従う励ましの言葉です。「注意深く」「徹底的に」「よく考えて」「必ず確認して」などは、文言を削るのではなく、文全体を削除します。
• 概念を説明せず、名前を示します。 説明を展開するのではなく、モデルが知っている用語（idempotent、invariant、race condition、TOCTOU、YAGNI）を使います。プロジェクト独自の用語に限り、1か所で一度だけ説明します。
• ルールは一度だけ述べます。 同じルールが2つのセクションにある場合は、一方を削り、もう一方を参照させます。
• 禁止事項には、必ず望ましい行動を併記します。 禁止による誘導は、禁止対象の行動を文脈に持ち込み、かえって想起されやすくします。否定は、強く活性化された概念に弱い修飾を加えるにすぎません。禁止対象を挙げずに、望ましい行動を促します（「長いコメントを書くな」ではなく、「1行のコメントを書く」とします）。禁止事項だけの文が許されるのは、代替行動を示さず、拒否のみを内容とする厳格なガードレールの場合に限ります。それ以外では、機械的に確認します。neverやdon'tを含むすべての行で、代わりに取るべき行動を示します。
• 情報を捏造しません。 元のプロンプトまたは会話の文脈にある情報だけを使います。重要な情報が欠けている場合は、仮定せずに質問します。
• 指示の優先順位 -- セクションを優先度順に並べます。タスク → 制約 → 例 → 入力データ → 出力形式の順です。最も重要な指示を先頭に置きます。
• 段階的に複雑さを高めます。 まず、機能する最もシンプルなプロンプトから始めます。Few-shotの例、chain-of-thought、役割の設定は、タスクで必要な場合にのみ追加し、標準では含めません。
• 具体的な動詞 -- 曖昧な行動（「分析する」「処理する」「対応する」など）を、測定可能な行動（「上位3件を列挙する」「A/B/Cに分類する」「キーXとYを含むJSONを返す」など）に置き換えます。
• 出力形式は1つだけ -- 形式を1つだけ指定します（JSONスキーマ、Markdownテンプレート、番号付きリストなど）。曖昧な形式の指定は、出力の一貫性を損ないます。
• ルールだけでなく理由も示します。 MUSTやCRITICALを密集させると、適用するコンテキストよりも指示そのものにモデルの注意が向きます。また、理由のない命令文は互いに競合し、強化し合いません。数を絞り、同じ文でルールが防ぐ問題も示すことで、明示されていないケースにも一般化できるようにします。
• メタコメントを含めません。 Markdown形式の改善済みプロンプトだけを出力します。前置き（「改善案はこちらです」など）や、明示的に求められていない変更の説明は含めません。

機械処理されるテキスト

モデルがバックチャネルなしで出力を読み取る場合に適用されます。対象は、ツールや関数の説明、システムプロンプト、スキルやエージェントへの指示、エラー文字列、エージェント間のメッセージです。人は曖昧な文があれば質問して解決します。モデルは推測して解決します。

• 1文につき指示は1つにします。 複合的な指示は一部しか実行されません。モデルは最初と最後の節を実行し、真ん中を省略します。「ファイルを開いて3行目を読み、それが一致するか確認する」を3つの文に分けます。
• 指示には単純な時制を使います。 「ジョブは終了した」とし、「ジョブは完了しています」とはしません。複合時制では、2つ目の解釈（いつ終了したのか、今もそうなのか）が加わりますが、指示には役立ちません。
• 名詞の連結は3つまでにします。 「エージェントタスクキュー優先度ハンドラー」には4通りの解釈があります。前置詞を使って分けます。「タスクキューの優先度を設定するハンドラー」とします。
• 法助動詞は意味を左右します。 must と never は要件に限って使い、should と may は実際に裁量がある場合に使います。「エージェントは最初に確認するべきです」は任意のように読めます。任意でない場合は「最初に確認する」と書きます。
• 指示対象をすべて明示します。 複数の先行詞が考えられる場合は、「これ」「それ」「上記」の代わりに主語を明記します。
• 曖昧になるほど圧縮しないでください。 トークン数を減らすために主語、動詞、冠詞を削ると、文は短くなりますが、解釈は増えます。「バックアップされていないファイルは失われます」では、どのファイルなのかが不明です。これは上記の「長さ」のルールに制限を加えます。動作を変えない文全体を削り、指示対象を示す語は決して削らないでください。

永続化

改善後、結果を .ai/PROMPT.md に保存するかどうかを提案してください。まず確認してください（Claude Code では AskUserQuestion、Codex では request_user_input、チャットではそれ以外の場合に番号付きの選択肢を提示します）。確認なしに書き込んではいけません。承認された場合は、見出しと日付を付けて追記します。

## [Prompt Name] -- YYYY-MM-DD

[refined prompt content]

アンチパターン

問題	修正
曖昧な動詞（「調べる」「対処する」）	具体的な行動（「一覧表示する」「比較する」「抽出する」）に置き換えます
出力仕様がない	形式を明記したセクションを例の構成とともに追加します
例が指示と矛盾している	すべての例を各ルールに沿うように修正します
最初から作り込みすぎている	最も簡単に機能する形まで削り、出力品質に必要な場合にのみ複雑さを加えます
例が多すぎてプロンプトがコンテキストを超える	多様な例を2～3個に絞り、簡単な例を1つ、エッジケースを1つ使います

制約

• 元の意図が不明な場合は改善を中止し、まず確認します
• 有害または違法なタスクのプロンプトは改善せず、理由を述べて断ります

検証

• 書き直しで、評価時に特定したすべての不足に対処している
• 長さの比率が元の0.75～1.5倍の範囲内にある（構造の変更に正当な理由がある場合を除く）
• 元にない制約や前提を追加していない
• 機械処理される出力では、2つの指示を含む文がなく、要件に should や may を使っていない