あなたはプロンプトを投入します。プレイグラウンドではうまく動きます。2週間後、誰かがバグを申告します。「特定の状況で、モデルがまったく違うことをしている」と。
あなたはプロンプトを読み返します。壊れているようには見えません。そこで書き直します。バグは消えますが、今度は別の3つの振る舞いが後退（回帰）します。それらを直すと、また同じサイクルが始まります。
これは、本番環境のLLMシステムで最もよくある失敗パターンです：直感によるデバッグ、書き換えによる修正。
問題はプロンプトが悪いことではありません。問題は、なぜ失敗しているのか、そしてどこに正確に修正を入れるべきなのかを、体系的に診断する方法がないことです。
代わりに、私が使う4ステップのプロセスを紹介します。
Step 1: Define the failure operationally
受け取れる最悪のバグ報告は「出力が間違っている」です。
何かに触る前に、失敗を運用上の定義に翻訳してください：
「状況Xでは、モデルはYを行うべきだ。ところがZをしている。」
これは当たり前に聞こえますが、ほとんどのデバッグはそれなしで始まります。「長すぎる」では実行可能な形になりません。「顧客向けの応答では、問い合わせが事実に基づく内容の場合に、答えが3文を超える」ならできます。
失敗は通常、次の2つの情報源のいずれかで表面化します：
- LLM-as-judgeがスケールして異常をフラグ付け（量があるときに有用）
- 本番での手動会話レビュー（量がないときに有用）
いずれにせよ、このステップの出力は、以降すべてに入力できる「正確な」説明になります。
Step 2: Audit for conflict before writing a single new instruction
新しい指示は、それ単体で存在しません。プロンプトのあるセクションに制約を追加すると、別の場所で定義されているロジックを静かに壊すことがあります。
何かを直す案を出す前に、現在のプロンプトが、失敗している振る舞いについてすでに何を言っているかを整理（マップ化）してください：
- このケースをカバーすべき既存の指示があるのに、ない（または適用されていない）？
- あなたが守らせたいことと矛盾するルールがある？
- 修正を追加すると、他のどんな振る舞いに影響しうる？
このステップだけで、多くの回帰バグが消えます。必要な修正が新しい指示でないことも多く、曖昧さを生んでいる既存の指示を削除するか、明確化することが答えであることがよくあります。
役に立つ頭の中のモデル：プロンプトをルールエンジン内の「一連の本番ルール」だと思ってください。間違った場所にルールを追加する、あるいは優先度が衝突するように書くと、既存の振る舞いが壊れます。監査は、プロダクションに到達する前に衝突を見つけるためのものです。
Step 3: Metaprompt with expected + observed as structured input
失敗が何で、競合をマップできたら、そのすべてをメタプロンプトのステップに投入します。
入力：
- 現在のプロンプト
- 期待される振る舞い（正確で、運用上の定義になっていること）
- 観測された振る舞い（理想的には、実際の会話履歴）
メタプロンプトは、候補となる修正を生成します。期待される振る舞いが曖昧だと、修正も曖昧になります。入力が「もっと簡潔にして」なら、出力は一般的になります。入力が「問い合わせが事実に関するもので、ユーザーが詳細を求めていない場合、応答は80語未満であるべきだ」なら、修正は外科的になります。
ここでアーキテクチャに関する質問が表面化しやすいのも同じです：
- システムプロンプトとユーザープロンプトのどちら？ 修正は、ユーザープロンプト内の「都度の指示」ではなく、システムプロンプトに恒久的な制約として入れるべきかもしれません。これを間違えると、トークンコストが増え、制約が時間とともに薄まります。
- ツール呼び出しにすべき？ 見た目がプロンプトの失敗に見えても、実はアーキテクチャ上の問題であることがあります。つまり、モデルに本来すべきでない「その場での処理」を行わせようとしているのです。
Step 4: Surgical insertion, not rewrite
メタプロンプトのステップの出力は、ほとんどの場合、完全な書き換えにはなりません。
通常は、1〜2個の変更です：
- 正しい位置に制約を追加する
- 曖昧な指示を明確化する
- 衝突するルールを削除する
目標は最小の差分で、最大の振る舞い変更です。
完全な書き換えは、失敗のための「新しい表面領域」を作ります。追加するすべてのトークンは、想定外に他の何かと相互作用しうるトークンです。変更が小さいほど、万一また何かが壊れたときに原因を切り分けやすくなります。
実装する前に、もう1つ質問してください：これは本当に回帰（regression）ですか？ プロンプトの以前のバージョンが、この点を正しく処理できていたか確認します。できていたなら、修正は新しいパッチではなく、部分的な巻き戻しかもしれません。
Why this works better than intuition-driven debugging
このフレームワークが、直感によるデバッグではできないことを3つ挙げます：
診断と修正を分離します。 ほとんどのプロンプトデバッグは、この2つをまとめてしまいます。何かおかしいのに気づいたら、すぐに編集を始めます。監査ステップは、変更する前に現在の状態を完全に理解することを強制します。
証跡（トレーサビリティ）を作ります。 失敗を運用上の定義で定め、競合の監査を文書化すると、プロンプトがなぜ変わったのかの記録が残ります。6か月後に「なぜこの指示がそこにあるの？」と聞かれたとき、答えがあります。
スケールします。 本番環境では複数のプロンプトが同時に失敗することがあります。そのとき、誰が一番うるさく苦情を言ったかではなく、同じ基準で重大度ごとにトリアージできます。
The diagnostic questions I ask before every fix
見落としやすい問題を一貫して浮かび上がらせる3つの質問：
1. 根本原因は正確にどこにありますか？
失敗はシステムプロンプトにありますか、ユーザープロンプトにありますか、あるいは特定の入力パターンに対するモデルの応答にありますか？それぞれで、取るべき修正が異なります。
2. それを解決するための最小変更は何ですか？
1文で直せるなら、それ以外は触らないでください。
3. このプロンプトのバージョンは、客観的基準で評価されていますか？
「よくなった気がする」だけではなく、具体的に：明確さ、具体性、構造、頑健性（ロバスト性）といった独立した次元として、より高いスコアになっていますか？
最後の質問は、私がその周りにツールを作ったものです。PromptEvalは、これら4つの次元でプロンプトを0〜100点でスコアリングし、特定の問題（一般的なフィードバックではありません）を特定し、上で説明した「反復（iterate）ワークフロー」を正確に実行します。期待される振る舞いと観測された振る舞いを渡すと、各変更について、根拠とリスク分類つきで外科的な修正案を提示します。
本番環境のプロンプトに取り組んでいるなら、無料枠だけで現在のシステムプロンプトに対する診断を実行できます。他の何かを使わない場合でも、やる価値があります。
登録する前に、完全な評価がどのようなものか見てみたいなら、こちらは例のレポートです。スコア、次元ごとの内訳、クリティカルな問題点、改善後のプロンプトが含まれています。
Add a prompt quality badge to your project
リポジトリ内でプロンプトファイルを扱っているなら、READMEに品質スコアを直接表示できます。CIステータスやテストカバレッジを見せるのと同じ要領です：
[](https://prompteval.vercel.app/en)
これは次のように表示されます：[PromptEval · 87/100]
評価を実行した後、87を実際のスコアに置き換えてください。
概要
| 手順 | 何をしているか | なぜ重要か |
|---|---|---|
| 1. 障害（失敗）を定義する | 「間違っている」を、期待される状態と観測された状態に分解して翻訳する | 正確な目標が得られる |
| 2. 競合を監査する | 新しい指示を追加する前に、既存の指示をマッピングする | 後戻り（回帰）を防ぐ |
| 3. メタプロンプト | 構造化された文脈を投入して、候補となる修正案を生成する | 汎用的ではなく、的を絞った変更が生まれる |
| 4. 外科的な挿入 | 最小限の差分で、最大の挙動変化を行う | プロンプトを安定させる |
本番環境でのプロンプトエンジニアリングにおけるボトルネックは、通常「良い状態が何かを知ること」ではありません。— それ以外のすべてを壊さずにそこへ到達するための体系的なプロセスがないことです。
競合監査のステップは、他の方々はどのように扱っていますか。手作業で行っていますか、それともそのためのツールを作っていますか？
