プロンプトのバージョン管理と本番運用｜コードに置くか、レジストリに置くかの判断

LLMを組み込んだ機能を1つ作って本番に出すと、しばらくして必ず同じ問題に当たります。プロンプトを直したい、でも直すのが怖いという状態です。誰かが試行錯誤の末にたどり着いた長いテキストが、コードのどこかに文字列リテラルとして埋まっていて、なぜその一文が入っているのか誰も説明できない。触ると何が壊れるか分からないので、追記だけが積み重なっていく。

プロンプトは、見た目は設定値ですが、振る舞いを決めるという意味ではコードです。そしてコードなら当然あるはずのもの、つまりレビュー・テスト・バージョン・ロールバックが、プロンプトにはしばしば付いていません。この記事では、プロンプトを本番で運用するための管理方法を実務の判断として整理します。プロンプトの書き方そのものは別記事に譲り、ここでは「どこに置き、どう変え、どう戻すか」に絞ります。

なお、この分野は2026年に入って前提が動きました。ベンダーが提供していたプロンプト管理機能の一部が畳まれ、OpenAIは「プロンプトをソースコードへ移す」という方針を公式の移行ガイドで明示しています。そこから話を始めます。

プロンプトは「設定」ではなく「コード」#

最初に整理しておきたいのは、プロンプトをどう位置づけるかです。よくある扱いは3つに分かれます。

1つ目は、アプリケーションコードの中に文字列として直接書く方法。最も手軽で、最初はこれで始まります。2つ目は、設定ファイルや環境変数に外出しする方法。デプロイなしで変えられる気がしますが、実際には設定の変更もデプロイを伴うことが多く、中途半端に終わりがちです。3つ目は、外部のレジストリに置いてIDやラベルで実行時に引く方法。運用が本格的になると検討対象に上がります。

どれを選ぶにしても、判断の起点は同じです。プロンプトを変えるとアプリケーションの振る舞いが変わる。つまりこれはリリースであって、設定変更ではありません。設定変更として扱った瞬間に、レビューもテストもロールバック手順も付かなくなります。

2026年に起きた揺り戻し#

数年前は、プロンプトをベンダーのダッシュボードで管理する方向が広がりつつありました。それが2026年に逆方向へ動きました。事実を先に押さえます。

OpenAI: 再利用可能なpromptオブジェクトは廃止へ#

OpenAIの公式deprecationsページには、APIの再利用可能なpromptオブジェクトを非推奨とする旨が記載されています。ダッシュボードでのprompt作成は2026年6月3日から扱いを下げ、v1/promptsは2026年11月30日にシャットダウン予定とされています。これまでpromptパラメータにid(pmpt_で始まる識別子)やversion、variablesを渡してResponses APIから参照できた仕組みが、なくなります。

注目したいのは、公式の移行ガイドが単なる代替手段の案内ではなく、方針を明示している点です。要約すると次のようになります。

• プロンプトの内容をソースコードへ移し、プロンプトの変更が製品ロジックと同じレビュー・リリース手順を通るようにする
• プロンプト変数を関数の引数に置き換え、動的な値をアプリケーション内で明示的かつ型付きにする
• promptオブジェクトを使う代わりに、Responses APIのinputでメッセージを渡す
• バージョン管理をリポジトリへ移し、gitのcommit、PRレビュー、テストやevalを使う
• 静的な内容を先に、動的な内容を後ろに置いてプロンプトキャッシュの利点を保つ(キャッシュヒットは完全なプレフィックス一致に依存するため)

実装上の推奨も具体的です。「コードベース全体にインラインでプロンプトを散らかさないこと。小さなprompts/モジュールを作り、各プロンプトを名前付きのビルダー関数として保持し、軽量なeval fixtureを追加して、プロンプトの変更が製品ロジックと同じようにレビューされるようにする」という趣旨の記述があります。

Anthropic: 旧Workbenchは2026年8月17日に終了#

Anthropicも同じ時期に動いています。公式のリリースノートによれば、Claude Consoleの旧Workbench(保存済みプロンプト、変数、evalを扱えたもの)は2026年8月17日にアクセス終了となりました。リリースノートは「保存済みプロンプト、変数、evalは更新後のWorkbenchではサポートされない」と明記しています。あわせて、プロンプトの生成・改善・テンプレート化を行っていた実験的なプロンプトツールAPI(/v1/experimental/generate_prompt、/v1/experimental/improve_prompt、/v1/experimental/templatize_prompt)も同日に引退し、削除後はエラーを返すとされています。

翌2026年8月18日には「WorkbenchはClaude ConsoleのPlaygroundになりました」というエントリが入りました。Playgroundは全Messages APIパラメータへの対応、テンプレート、SDKリクエストとAPIレスポンスの表示が主眼で、プロンプトの保存やバージョン管理、eval機能は掲げられていません。

つまり執筆時点で、Anthropicが提供しているのは全パラメータを試せるPlaygroundまでで、実行時にIDでプロンプトを引くレジストリは第一者としては見当たりません。なおAnthropicのリリースノートが述べているのは機能の終了と名称変更までで、「コードで管理せよ」という方針が示されているわけではありません。管理方法の選択はアプリケーション側に委ねられている、というのが正確な読み方です。

Google: prompts APIは維持されている#

一方、Google Cloud側のprompt managementは継続しています。公式ドキュメントにはprompts.createでプロジェクト内にprompt resourceを作り、prompts.create_versionでバージョンを作成し、prompts.getやprompts.get_versionで取得する、といったメソッドが並びます。prompts.restore_versionもあり、公式のコードサンプルでは、バージョン1を復元した結果が「バージョン2として復元した」という出力になっています。過去のバージョンを新しいバージョンとして作り直す挙動で、gitのrevertに近く、履歴が失われません。

ただし制約もあります。ドキュメントには「single-turnのプロンプトのみサポートされる」と明記されています。また、後述するproductionやstagingのような環境ラベルの仕組みは、公式ドキュメントに記載がありません。あるのはバージョンIDと復元だけなので、環境ごとの出し分けは自前で持つ必要があります。

既定はコード、例外がレジストリ#

以上を踏まえた実務の結論はシンプルです。既定はコード(git)に置く。レジストリは、置く理由が明確にあるときだけ選ぶ。

コードに置く根拠は、OpenAIの移行ガイドがそのまま使えます。レビュー・テスト・デプロイ・バージョニングの制御が既存の仕組みに乗り、変数が型付きの関数引数になり、CIでテストや評価を回せる。ロールアウトや実験は、アプリケーション側の設定やフィーチャーフラグで管理できます。要するに、プロンプト専用の仕組みを新たに1つ増やさずに済みます。

では、レジストリを選ぶ理由は何か。Langfuseの公式ドキュメントが掲げる設計思想が端的です。「プロンプトの更新をエンジニアリングのデプロイから切り離す」。つまり、エンジニアのリリースを待たずにプロンプトを変えたい人がいる場合です。PromptLayerも同様に、コードベースの外で整理すること、コードのdiffをやり取りせずにレビューと共同作業ができることを利点として挙げています。

判断軸は「誰が変えるか」です。技術的な高度さの問題ではありません。

レジストリを選ぶときに必ず出てくる懸念が「実行時に外部依存が増える」ことです。この点は、成熟したツールでは設計上の手当てがあります。LangfuseのSDKはクライアントサイドのキャッシュを持ち、既定のTTLは60秒、cache_ttl_secondsで変更でき、0で無効化できます。TTLが切れた場合も古い値を即座に返しつつバックグラウンドで再検証する挙動を取り、さらにfallbackパラメータでキャッシュもAPIも使えないときの代替プロンプトを指定できます。外部依存を可用性の単一障害点にしない仕組みが用意されている、という前提で評価するとよいです。

バージョン識別子とラベルは分ける#

置き場所を決めたら、次は「どのバージョンが本番なのか」をどう表すかです。ここは主要ツールの実装が揃っていて、共通の型が見えます。

コード管理でも考え方は同じです。バージョン識別子はcommit hash、ラベルに相当するのはリリースタグやフィーチャーフラグの値になります。「本番で動いているプロンプトの中身を、識別子から一意に引ける」状態を作ることが目的で、手段はどちらでも構いません。

段階的な出し分けまで必要な場合、PromptLayerにはDynamic Release Labelsという仕組みがあり、1つのリリースラベルに複数バージョンをぶら下げてトラフィックを比率分割できます(バージョン3に90%、バージョン4に10%といった指定)。リクエストのメタデータによるユーザーセグメント指定もでき、プロンプト層でのカナリアリリースに相当します。ただし、後述するキャッシュの分裂という副作用があるので、常時使うものではありません。

プロンプトを変えると必ず壊れる2つのもの#

ここからが本題です。プロンプトを変更するときは、必ず2つを確認する必要があります。手順に組み込んでおかないと、変更のたびに気づかない劣化が積もります。

確認するもの1: 評価との対応#

プロンプトを変えると、それまでのスコアが「どのバージョンで測ったものか」の対応が切れます。評価セットと採点方法とモデルを揃えれば変更前後の比較そのものは可能なので、問題は比較できないことではなく、記録がないと後からスコアを正しく解釈できなくなることです。変更前後で同じ評価セットを回し、バージョンと結果を紐づけて残しておけば、この問題は起きません。

OpenAIのAPI deployment checklistは、この点を具体的に書いています。プロンプトを変更したり新機能を追加したりする前に代表的なevalを回すこと、そしてタスク成功率・レイテンシ・入力・出力・推論トークン・キャッシュ書き込みトークン、および成功1件あたりのコストを比較すること、という趣旨です。移行ガイド側でも、本番プロンプトを変更する前に代表的なfixture、テスト、評価チェックを追加するよう述べています。

評価をどう作るかについては、Anthropicのテスト設計ガイドが原則を示しています。可能な限り自動化すること、そして「品質より量を優先する」こと。多少精度が落ちても自動採点で件数を稼ぐほうが、少数の手作業採点より良い、という考え方です。プロンプト変更のたびに人手でレビューするのは続かないので、この割り切りは実務的です。

確認するもの2: プロンプトキャッシュ#

こちらは見落とされがちですが、コストに直接効きます。プロンプトキャッシュは完全なプレフィックス一致で動くため、キャッシュ対象のプレフィックスに含まれる部分を1文字でも変えると、そのブレークポイントのキャッシュは無効になります。逆に言えば、変更箇所がブレークポイントより後ろであれば、手前のキャッシュは生き残ります。ここを設計できるかどうかが分かれ目です。

Anthropicの公式ドキュメントは、キャッシュヒットにはcache_controlでマークしたブロックまでのテキストと画像を含めて100%同一のプロンプトセグメントが必要だと明記しています。仕組みはハッシュベースで、ブロックをマークすると「そのブロックで終わるプレフィックスのハッシュ」が1件書かれます。ハッシュは累積的で、ブレークポイント以前のどのブロックを変えても次のリクエストでは別のハッシュになります。ヒットしなければ1ブロックずつ手前に遡って照合しますが、遡れる範囲は最大20ポジションとされています。プレフィックスの構成順序はtools、system、messagesの階層で、各階層の変更はその階層と以降すべてを無効化します。

ブレークポイントは複数置けます。Anthropicは最大4つのブレークポイントを扱え、ヒットしなければ最大20ポジション遡って照合します。OpenAI側も、ブレークポイントより後ろの変更は手前のキャッシュ済みプレフィックスを無効化しないこと、複数のブレークポイントが一致する場合は最長の一致プレフィックスから読むことを明記しています。つまり「共通部分の末尾にブレークポイントを置く」という設計ができていれば、その後ろのバージョン差分は共通キャッシュを壊しません。

公式ドキュメントには、具体的な失敗例も載っています。静的なシステムプロンプトの後ろにタイムスタンプとユーザーメッセージを含むブロックを置き、その最後のブロックにcache_controlを付けてしまうケースです。タイムスタンプが毎回違うのでハッシュが一致せず、遡ろうにも手前にエントリが書かれていないため、キャッシュが一切ヒットしません。対策は「キャッシュを共有したいリクエスト間で同一のプレフィックスを持つ、最後のブロックにcache_controlを置く」ことです。

もう1つの落とし穴が最小トークン数です。Anthropicのドキュメントでは、キャッシュ可能な最小トークン数がモデルによって異なり、512から4,096トークンの幅があるとされています。そして重要なのは、これを下回るプロンプトはcache_controlを付けてもキャッシュされず、エラーも返らないという点です。設定したつもりで効いていない状態に気づけません。

OpenAI側にも同様の最小値があり、モデル世代で条件が違います。公式ドキュメントによれば、GPT-5.6以降は1,024トークンが厳密な最小値で、キャッシュ書き込みはキャッシュなしの入力単価の1.25倍で課金されます。それ以前のモデルは最小値がモデルによって1,024から2,048トークンの幅があり、キャッシュ書き込みへの追加料金はないとされています。キャッシュミスの原因としては、ブレークポイントより前の内容変更(タイムスタンプ、ユーザー入力、ツール履歴)、tool定義や順序・スキーマの差異、過去メッセージの変更・削除・並べ替え、最小トークン数割れなどが挙げられています。「指示や例のような静的な内容をプロンプトの先頭に、可変の内容を末尾に置く」という指針も明記されています。

PromptOpsの観点でここから導かれる注意点は2つです。

OpenAIのdeployment checklistがcached_tokensとcache_write_tokensのログ取得を推奨し、書き込み量と後続のキャッシュ読み出しを比較して正味のコストを測りキーの粒度を調整するよう述べているのは、まさにこのためです。

モデルが変わるとプロンプトが壊れる#

プロンプトを何も変えていないのに振る舞いが変わる、というもう1つの経路がモデル更新です。ここへの備えも、プロンプト管理の一部として設計しておく必要があります。

OpenAIのprompt engineeringガイドは、一貫した挙動を保つために本番アプリケーションを特定のモデルスナップショットにピン留めすることを挙げています(ドキュメント内ではgpt-4.1-2025-04-14のような形式が例示されています)。

Anthropicのモデル非推奨ドキュメントは、モデルのライフサイクルを4つの状態で定義しています。

通知については、引退予定のモデルについてアクティブなデプロイを持つ顧客に対し、公開リリース済みのモデルであれば最低60日前に通知するとされています。あわせて、このページの日付はAnthropicが運営する基盤に適用され、パートナーが運営する基盤(Amazon BedrockやGoogle Cloud)は独自の引退スケジュールを設定するため、ライフサイクルの状態や日付が異なりうるとも明記されています。運用手順として役に立つのは、ConsoleのUsageページからエクスポートしたCSVでAPIキー別・モデル別の利用状況を監査でき、非推奨モデルが残っている箇所を洗い出せる、という点です。プロンプトのバージョンとモデルIDをセットで管理していれば、この棚卸しはさらに楽になります。

Google Cloud側のモデルライフサイクルのドキュメントには、初回リリースから最低12か月提供されるモデル群と、置換モデルのリリースから45日で引退する短期提供モデル群の区別があり、引退日程は延長されることはあっても記載より前倒しされることはない、と明記されています。

実務としては、プロンプトのバージョンにモデルIDと主要な生成パラメータを紐づけて記録しておくのが最小限の備えです。「このプロンプトはこのモデルで評価した」という対応が残っていれば、モデルを差し替えるときに再評価すべき対象が特定できます。

なお、生成パラメータについては注意が要ります。Anthropicのドキュメントによれば、temperature、top_p、top_kはClaude Opus 4.7以降で非推奨となり、既定以外の値を設定すると400エラーを返します。推奨は「省略して、プロンプトでモデルの挙動を導く」ことです。調整の対象がパラメータからプロンプト本文へ移りつつある、という流れの一例です。

テンプレート変数と、信頼できない入力#

プロンプトを管理対象にすると、ほぼ必ずテンプレート変数が出てきます。ここには設計上の分岐点が1つあります。変数に入る値が、自社が管理しているものか、外から来たものか、です。

Anthropicのjailbreak・インジェクション対策のドキュメントは、脅威を2つに分けています。1つはアプリの利用者自身が攻撃者である場合(直接的なプロンプトインジェクション)、もう1つは利用者は信頼できるが、モデルが処理する第三者コンテンツ(Webページ、メール、ドキュメント、ツール結果)に敵対的な指示が埋め込まれている場合(間接的なプロンプトインジェクション)です。

後者への対策として挙げられている項目のうち、テンプレート設計に直結するものを拾います。

JSONエンコードの原則は、テンプレート変数の実装そのものへの指針として読めます。文字列連結で組み立てているテンプレートは、この観点で一度見直す価値があります。

観測にバージョンを残す#

最後に、運用フェーズの話です。プロンプトのバージョンは、トレースやログに記録して初めて意味を持ちます。「先週から品質が落ちた」という報告に対して、その期間に本番で動いていたプロンプトのバージョンを特定できなければ、原因を切り分けられません。

Langfuseは生成呼び出しにpromptを渡すことでトレースに紐づけられ、バージョン単位で生成回数に加えて、生成レイテンシ・入出力トークン・コスト・スコアの各中央値と、初回・最終生成時刻を見られるようになっています。専用ツールを使わない場合でも、トレースの属性としてプロンプト名とバージョン識別子を入れておけば、同じ切り口の分析は自前で組めます。

最初の一歩#

大きな仕組みを一度に入れる必要はありません。既存のコードから始める順序を挙げます。

よくある質問#

まとめ#

プロンプト管理の話は、ツールの選定に見えて、実際には「プロンプトの変更をリリースとして扱うかどうか」という一点に集約されます。リリースとして扱うなら、レビューとテストとロールバックが必要になります。必要なものが決まれば、置き場所は自然に決まります。

2026年の動きは、その意味で示唆的です。OpenAIは再利用可能なpromptオブジェクトを畳み、プロンプトをソースコードへ移して製品ロジックと同じレビュー・リリース手順に乗せるよう明示しました。Anthropicは保存済みプロンプトとevalを扱えた旧Workbenchを終了しました。方針として明言しているのはOpenAIだけですが、結果として、プロンプト専用の管理面をベンダーに任せる前提は取りにくくなっています。

だからといってレジストリが不要になったわけではありません。エンジニアのデプロイを待たずにプロンプトを変える人がいるなら、レジストリは有効です。ただしそれは組織の事情から来る要件であって、技術的な先進性の問題ではありません。この区別が付いていれば、選定で迷うことは減ります。

そして、置き場所を決めた後に効いてくるのが、評価とキャッシュです。プロンプトを変えれば評価との対応は切れますし、キャッシュ対象のプレフィックスに手が入れば書き込みが発生します。この2つを変更手順に組み込んでおくと、プロンプトの変更は「怖いもの」から「測れるもの」に変わります。最初にやることは、散らばった文字列を1か所に集めて、代表的な入力を10件並べるところまでで十分です。