プロンプトのバージョン管理手順｜Git・評価・ロールバック

プロンプトのバージョン管理は、指示文を保存するだけでなく、入力契約、出力形式、例示、参照ルール、モデル識別子、評価結果を同じリリース単位で追跡する運用です。変更理由と復旧先が分からないプロンプトは、業務ロジックとして公開できません。

本稿では、顧客問い合わせの返信案を作る「SUP-REPLY」という架空プロンプトを、コード管理へ移し、72件で評価し、5%の限定公開から段階的に切り替える例を扱います。読後の成果物は、テンプレート一式、manifest、評価データ、変更申請、公開判定票、ロールバック記録です。

現行一次情報からプロンプト管理の方針を決める

管理基盤を選ぶ前に、利用中サービスの現行仕様と終了予定を確認します。OpenAIの公式Promptingページは、プロンプトをアプリケーションコードとして扱い、名前付きモジュール、型付き引数、代表的なfixture、公開工程に組み込む評価、Git履歴、レビュー、リリースタグ、feature flagを使う方針を案内しています。継続更新ページの参照日は2026年7月30日です^[1]。

同社の公式移行ガイドは、再利用可能なPrompt ObjectをAPIから廃止予定とし、2026年6月3日から作成を縮小、v1/promptsを2026年11月30日に終了予定と記載しています。移行先は、プロンプト内容をアプリケーションコードへ置き、レビュー、試験、配備、版管理を自社工程で制御する構成です^[2]。これはOpenAI固有の予定であり、すべての提供元が同じ仕組みを廃止するという意味ではありません。

さらに公式Deprecationsページでは、Prompt Objectに加え、OpenAI Evals基盤も2026年6月3日に非推奨化が告知され、既存評価が2026年10月31日に読み取り専用、ダッシュボードとAPIが2026年11月30日に終了予定とされています^[3]。そのため、評価ケースと期待値を特定ダッシュボードだけへ保存せず、JSONLやCSVなどで自社保管し、別の実行器でも再現できる形にします。

本稿の管理原則：正本はコード、サービス上の設定は配備先、評価データは独立資産、公開状態はfeature flag、復旧点は変更不可のリリース識別子として分けます。

開始条件を確認し、動いているプロンプトを棚卸しする

版管理は、新しいプロンプトを書くところから始めません。まず、現在の文面がどこにあり、どの入力で、どのモデルとツールを呼び、結果が何へ渡るかを一枚にします。ソースコード、管理画面、表計算、ワークフロー設定に同じ目的の文面が散在している場合は、実際の実行ログから使用中のものを特定します。

開始には、リポジトリへのレビュー権限、検証環境、匿名化済み評価データ、実行ログ、切替権限、手動業務へ戻す経路が必要です。顧客情報を開発端末へ複製してはいけません。評価用入力は必要箇所だけを合成・匿名化し、原案件への対応表は業務部門の制限領域へ分けます。

棚卸しの合格条件：直近30日の実行について、prompt_key、テンプレート版、モデル識別子、評価対象となる出力、利用場所を一つの実行IDから追える状態です。一項目でも取得不能なら、候補版の公開より観測性の修正を優先します。

版番号を見た人が互換性と再評価範囲を判断できるようにする

本稿ではSUP-REPLYの版を2.3.1の三桁で表し、変更の影響をMAJOR、MINOR、PATCHへ割り当てます。Semantic Versioning 2.0.0は、本来は明確な公開APIを持つソフトウェア向け仕様で、互換性を壊す変更をMAJOR、互換性を保つ機能追加をMINOR、互換性を保つ修正をPATCHと定めます^[5]。プロンプトへの割り当ては同仕様そのものではなく、編集部による運用上の応用です。

「意味を変えない誤字」も無試験で公開しません。否定語、数値、区切りの修正は挙動へ影響し得るため、実際の差分を基にMINOR以上へ引き上げます。版番号は作業量ではなく、利用者と下流処理から見た互換性で決めます。判断が割れた場合は大きい区分を選び、変更申請へ理由を残します。

リリースはGitのannotated tagでprompt/SUP-REPLY/v2.3.1のように固定し、タグ注記へ評価結果ID、承認者、適用開始日を入れます。Git公式git-tag文書は2026年6月29日更新の2.55.0で、annotated tagが作成日、作成者、メッセージなどを持ち、リリース用途に向くと説明しています。また、公開済みタグの付け直しは利用者が同じ名前で異なる内容を持つ危険を生むため、新しい名前を使うよう注意しています^[4]。公開済みの版内容は書き換えず、修正版を新しいタグで発行します。

テンプレート、例示、台帳、履歴を一つのリリースへ結び付ける

プロンプト本文だけを一ファイルへ置くと、出力スキーマや評価データの版が離れます。SUP-REPLYでは、業務単位のディレクトリに指示、例示、入力・出力スキーマ、manifest、変更履歴を置きます。実行コードはprompt_keyからこの部品を読み、起動時にmanifestの整合性を検査します。

prompts/
  SUP-REPLY/
    prompt.md
    examples.yaml
    input.schema.json
    output.schema.json
    manifest.json
    CHANGELOG.md
evals/
  SUP-REPLY/
    fixtures-v5.jsonl
    rubric-v2.json
    dataset-card.md
releases/
  SUP-REPLY/
    rollout-policy.yaml

manifestには、版番号、各ファイルのハッシュ、所有者、対応する評価集合、許可モデル、必要な検索索引、公開状態、直前の安定版を記録します。prompt.mdから外部ファイルを読み込む場合も、その版またはハッシュを固定します。「常に最新の社内規程」のような参照は再現できないため、実行時に取得した規程IDと改訂日をログへ残します。

{
  "prompt_key": "SUP-REPLY",
  "version": "2.3.1",
  "owner": "customer-support",
  "template_hash": "sha256:...",
  "example_set": "sup-reply-examples-v4",
  "input_schema": "sup-reply-input-v2",
  "output_schema": "sup-reply-output-v3",
  "eval_set": "sup-reply-fixtures-v5",
  "rubric": "sup-reply-rubric-v2",
  "allowed_model_snapshots": ["approved-snapshot-A"],
  "previous_stable": "2.3.0",
  "release_status": "candidate"
}

秘密情報、実顧客文、APIキーをリポジトリへ含めません。テンプレート変数には型を付け、未入力時の既定値で事実を推測しないようにします。例示セットはFew-shot担当者が管理しても、manifest経由でリリースへ固定します。業務担当者が管理画面で直接文面を変えられる場合は、本番値と正本の差分を定期検知し、未承認差分があれば配備を停止します。

72件の評価データをベンダーから独立させる

評価集合は、あるサービスでしか読めない形式を正本にしません。SUP-REPLYではJSONL一行を一案件とし、入力、期待要素、禁止要素、重大度、適用製品、正解根拠、承認情報を持たせます。実行器を変えても同じcase_idと採点規則を使えるよう、モデル呼出部分とgrader部分を分離します。

各ケースの正解は、文字列完全一致だけにしません。必須の規程ID、禁止する約束、要確認フラグ、出力スキーマは決定的に判定し、文章の自然さは評価票で人が確認します。モデルgraderを使う場合も、重大な権限違反を単独で合格にできない構成にします。graderの版とプロンプトも別の管理対象です。

NIST AI 600-1は2024年7月26日公開で、掲載ページが2026年4月8日に更新された公的資料です。生成AIの設計・開発・利用・評価を通じ、組織の目的とリスク許容度に合わせた管理を扱います^[6]。本稿の72件と配点は同文書が義務付ける数値ではなく、SUP-REPLYの変更を比較可能にする想定例です。

{"case_id":"SUP-BND-014","severity":"critical","input":{"question":"年払いを途中解約したら全額返金されますか","product":"PRO-A","contract_state":"active"},"expected":{"needs_human":true,"required_citation":"refund-policy-v7"},"forbidden":["全額返金されます","返金はありません"],"approved_by":"support-policy-owner"}

評価データを更新すると過去スコアの意味が変わるため、fixtures-v5を上書きせずv6を作ります。誤りを見つけた案件は候補領域へ置き、個人情報処理、正解レビュー、重複確認を経て次版へ入れます。現行版と候補版を比較するときは同じ評価集合を使い、集合変更の効果とプロンプト変更の効果を一回の数字へ混ぜません。

候補版の作成から承認までを九段階で進める

一回の変更では主要な仮説を一つに絞ります。「返金を断定する誤りを減らす」が目的なら、モデル、例示、検索条件を同時に変えません。差分の理由、対象ケース、期待改善、悪化し得る点を変更申請へ書き、候補版をpre-releaseとして作ります。

1. 変更要求を受け付ける：誤りの実行ID、期待結果、影響範囲、緊急度、申請者を記録します。
2. 原因を再現する：現行タグと同じ依存関係で失敗を再実行し、入力、検索、指示、モデルのどこに原因があるか特定します。
3. 互換性を分類する：出力契約と権限が変わるかを確認し、MAJOR、MINOR、PATCHの候補を決めます。
4. 作業ブランチを作る：manifestのversionをpre-releaseへ上げ、prompt.mdまたはexamples.yamlの対象箇所だけを変更します。
5. 静的検査を行う：変数未定義、閉じタグ、JSON Schema、秘密情報、禁止語、manifestのハッシュを自動確認します。
6. 72件を実行する：現行版と候補版を同じモデル識別子、設定、fixtureで比較し、case_id別の差を保存します。
7. 人が重大ケースを読む：境界16件と禁止8件は業務責任者が全文を確認し、自動採点だけで承認しません。
8. 変更レビューを承認する：差分、評価票、コスト、復旧先、公開割合、停止条件を品質確認者と所有者が署名します。
9. 変更不可のタグを発行する：承認済みcommitへ正式タグを付け、タグと評価run_idをリリース記録へ関連付けます。

緊急修正でも評価をゼロにはしません。権限外出力を止める修正なら、該当criticalケース、入力・出力スキーマ、通常返信の代表件を最低限実行し、適用後に全72件を完了します。緊急経路を使った理由、承認者、未実施試験、完了期限を記録し、期限を過ぎた候補版は自動的に人手運用へ戻します。

段階公開で影響を限定し、版だけでなく処理状態も戻す

評価環境で合格しても、本番入力の分布、検索結果、下流連携は完全には再現できません。SUP-REPLYでは、社内確認専用、5%、25%、100%の四段階を想定し、各段階に最低件数と観測時間を置きます。割合は編集部の例であり、月間件数が少ない業務では件数基準を優先します。

feature flagはprompt_keyとversionを明示し、単にnew_prompt=trueとしません。実行開始時に割り当てた版を途中で変えず、結果ログへ割当理由を残します。新旧比較では顧客属性など不要な個人情報を分析キーにせず、製品、問い合わせ類型、入力長、要確認状態といった業務変数で偏りを確認します。

ロールバックは、active versionを前版へ戻す操作だけでは不十分です。候補版が作った返信案のうち未承認、送信済み、差戻し済みを分け、送信済みで誤りが疑われる案件を業務責任者へ通知します。検索索引や出力スキーマも同時に変わった場合は、互換性のある依存版へ戻す順序をrunbookへ書きます。

ロールバック記録
incident_id: PRM-2026-071
detected_at: 2026-07-30T14:12:00+09:00
from_version: 2.4.0
to_version: 2.3.0
trigger: 返金確約の重大失敗1件
affected_runs: 37
sent_outputs: 0
pending_outputs: 37
disabled_locations:
  - web-support-draft
reopen_condition: 原因ケース合格、全72件92点以上、所有者再承認

バージョン管理で起きやすいエラーを原因別に直す

版番号が表示されていても、内容と評価結果が対応しなければ監査できません。障害調査では、正本、ビルド成果物、配備設定、実行ログ、評価runの五点を照合します。画面に表示された版だけを信じず、実行時template_hashがタグのmanifestと一致するか確認します。

評価データの汚染は見つけにくい問題です。誤答した本番入力をそのまま例示へ追加し、同じ入力を評価にも残すと、候補版の点が不自然に上がります。例示用、開発用、固定評価用、公開後監視用のcase_id領域を分け、内容ハッシュでも重複を探します。類似表現まで完全に排除する必要はありませんが、同一案件の言い換えで点を稼がないよう人が確認します。

復旧不能の版を出さないため、四半期に一度は停止訓練を行います。テスト版へ5%を割り当て、当番が検知、限定停止、前版復旧、影響件数確認、再開保留まで実施します。訓練で権限や連絡先が古いと分かった場合は、プロンプト文面よりrunbookを先に修正します。

100点の評価票と変更トリガーで公開判断をそろえる

SUP-REPLYの候補版は、内容品質、根拠、契約、停止、安全、効率を100点で見ます。全体点が高くてもcriticalケースの失敗は不合格です。次の配点と92点という閾値は想定例であり、顧客へ自動送信しない「返信案」用途を前提にしています。自動送信へ範囲を広げる場合は別のリスク評価と承認が必要です。

公開候補の想定条件
総合点 = 六評価軸の獲得点合計
総合点 >= 92
criticalケースの重大失敗 = 0
出力スキーマ妥当率 = 100%
現行版より5点以上悪化する評価軸 = 0
rollback_targetの復元試験 = 合格

判定方法を確認する仮想例では、計算式を「六軸の獲得点の合計」とし、24、20、15、20、10、8なら総合点は97点です。ただし、criticalケースで権限外情報を一件でも返した版は、97点でも公開しません。総合点は通常品質の比較に使い、重大失敗0件、スキーマ100％、復旧試験合格を独立した必須条件として扱います。この数値はSUP-REPLYの判定ロジックを説明する計算例であり、実測性能ではありません。

月5件という件数は実績値ではありません。月100件なら5%ですが、月一万件なら0.05%です。母数と影響を一緒に見て、自社の変更条件を確定します。規程改訂やサービス終了のように件数へ表れない事象は、告知日と発効日を基に計画変更を開始します。

停止・再開条件を明文化し、管理が重過ぎる用途は除外する

全体停止は、権限外情報の出力、返金・補償の未承認確約、別顧客データの混入、実行版を特定できない状態のいずれかで即時に行います。限定停止は、特定製品だけで規程IDが欠ける、特定言語だけSchema違反が連続二件といった場合です。停止した入力は破棄せず、人手キューへ移して担当者を明示します。

この管理方式が向かないケース

一度きりの個人メモ、結果を業務へ接続しない試作、月一回未満で人が全文を容易に確認できる用途では、ここまでの配備基盤が過剰になる場合があります。反対に、医療・法務・与信など重大判断では、プロンプト版管理だけでは不十分で、権限分離、決定的ルール、専門家承認、監査、事故対応を追加する必要があります。

また、所有者がいない、正解データを作れない、実行ログを取得できない、手動へ戻せないという条件では、本番変更を始めません。画面上の履歴が便利でも、エクスポート不能で終了期限も不明なら正本には適しません。まず現行文面と評価データを持ち運べる形へ確保し、停止権限を整えてから候補版を作ります。

次に取る行動

稼働中のプロンプト一つを選び、prompt_key、所有者、利用場所、入力、出力、依存先、現行版、復旧担当を棚卸し票へ記入してください。次に現行文面を変更せずbaselineタグとして固定し、通常・境界・入力欠落・禁止の各一件を使って、版と結果を同じ実行IDから追えるか確認します。

baselineを固定する際は、prompt.mdだけでなく、例示、Schema、参照規程、モデル識別子、実行設定のハッシュをmanifestへ記録します。タグから検証環境を再構築し、四件の出力が保存済み結果と対応するかを品質担当者が確かめます。再現できない部品が一つでもあれば、新しい文面の作成を止め、正本と配備値の差を先に解消します。

再現性を確認できた後、直近の訂正一件を変更申請へ起票します。原因、期待する差、影響ケース、版区分、合格条件、復旧タグを記入し、一要因だけを変えたpre-releaseを作ります。72件の評価へ広げる前に、通常、境界、禁止の代表ケースで候補版が狙った差を生むことを確認してください。この小さな往復試験が、以後の段階公開とロールバック訓練の出発点になります。

参考文献・出典

1. OpenAI「Prompting」（公式ドキュメント、版・更新日表記なし、参照日：2026年7月30日）
2. OpenAI「Migrate from prompt objects」（公式移行ガイド、非推奨化開始日：2026年6月3日、v1/prompts終了予定日：2026年11月30日、参照日：2026年7月30日）
3. OpenAI「Deprecations」（公式更新情報、Reusable promptsおよびEvals platform告知日：2026年6月3日、掲載終了予定日：2026年11月30日、参照日：2026年7月30日）
4. Git Project「git-tag Documentation」（公式ドキュメント、Git 2.55.0版、更新日：2026年6月29日、参照日：2026年7月30日）
5. Tom Preston-Werner「Semantic Versioning 2.0.0」（公式仕様Version 2.0.0、更新日表記なし、参照日：2026年7月30日）
6. National Institute of Standards and Technology「Artificial Intelligence Risk Management Framework: Generative Artificial Intelligence Profile」（公的文書NIST AI 600-1、公開日：2024年7月26日、掲載ページ更新日：2026年4月8日、参照日：2026年7月30日）