プロンプトライフサイクル運用ガイド（新規追加 / バージョンアップ / 緊急ロールバック / KV 乖離復旧）

対象: prompts/production/ 配下の Type 1 プロンプト（ADR-0042 で定義）
SSoT: git（prompts/production/）→ Cloudflare KV（ランタイムキャッシュ）
ADR: ADR-0042

1. 現在管理対象の Type 1 プロンプト一覧

2. 新規 Type 1 プロンプト追加フロー（draft → production）

2.1 ステップ概要

draft → experiment → candidate → production

2.2 手順

Step 1: ディレクトリ作成

mkdir -p prompts/production/<gate-id>
mkdir -p prompts-eval/datasets/<gate-id>

Step 2: 必須ファイル作成

Step 3: prompt.meta.yaml の必須フィールド

id: <kebab-case 一意識別子>
owner: [email protected]
status: draft           # 初期状態は draft
semver: 0.1.0
model_pin: <具体的なモデル名（例: claude-sonnet-4-6）>
inputs:
  - name: <変数名>
    type: string
    description: "<説明>"
output_schema: output_schema.json
eval_suite: ../../../prompts-eval/datasets/<gate-id>/golden.jsonl
eval_pass_threshold: 0.85   # global_min_threshold 0.70 以上
kv_key: bizlp:prompts:<gate-id>
deprecation_at: null

Step 4: golden.jsonl の整備

# prompts-eval/datasets/<gate-id>/golden.jsonl に最低 20 件追加
# フォーマット: 各行が独立した JSON オブジェクト
{"vars": {"input_var": "..."}, "assert": [{"type": "javascript", "value": "output.pass === true"}]}

Step 5: status を candidate → production に昇格させる PR を作成

• status: draft → experiment → candidate は実装者がローカルで確認
• status: candidate → production への変更は PR 必須
• PR マージ時に eval CI が自動実行され、KV が自動更新される

3. バージョンアップ手順（SemVer 判定）

3.1 バンプ基準

3.2 バージョンアップの手順

# 1. prompt.md を編集
# 2. prompt.meta.yaml の semver を更新
# 3. PR を作成
# 4. eval CI が自動実行（eval_pass_threshold を下回ればマージブロック）
# 5. PATCH で閾値割れの場合: マージブロック。PATCH のままリトライ可。
#    意味的破壊を伴う場合は MAJOR に手動昇格して再 PR。

3.3 eval CI の動作

# .github/workflows/prompt_eval.yml が自動実行
# - prompts/production/** への PR が対象
# - meta.yaml lint（必須フィールド・eval_pass_threshold ≥ 0.70 チェック）
# - Promptfoo による eval 実行（temperature=0, 3 サンプル多数決）
# - 閾値割れ → マージブロック
# - --retries 2 で再実行し、2 回連続失敗のみ block 扱い

4. 緊急ロールバック手順

4.1 KV ポインタ切り替えによる 5 分以内ロールバック

本番障害（Gate が誤判定を連発・パイプライン停止）を検知したら以下の手順で対応する。

時間予算（KV の Eventually Consistent 特性を考慮）:

手順:

# Step 1: 現在の KV ポインタを確認
wrangler kv:key get --binding=PROMPTS_KV "bizlp:prompts:<gate-id>:active"

# Step 2: 前バージョンのキーを確認
# キー命名規則: bizlp:prompts:<gate-id>:<semver>
wrangler kv:key list --binding=PROMPTS_KV --prefix="bizlp:prompts:<gate-id>"

# Step 3: ポインタを前バージョンに切り替え
wrangler kv:key put --binding=PROMPTS_KV "bizlp:prompts:<gate-id>:active" "<前バージョンの semver>"

# Step 4: 伝播待ち（最大 60 秒）後に動作確認
# 混在期間（最大 60 秒）中は新旧プロンプトが混在しうるが、Gate の冪等性により許容

# Step 5: Git に手動変更を記録（次の §4.2 参照）

4.2 KV 手動変更後の Git 同期フロー

KV を直接手動編集した場合（緊急時のみ許容）は、必ず git と同期する。

# Step 1: prompt.meta.yaml に緊急ロールバックの記録を追加
# semver を前バージョンに戻し、コメントを追記
vim prompts/production/<gate-id>/prompt.meta.yaml

# Step 2: prompt.md も前バージョンの内容に戻す
# (git show でロールバック先のコミットから取得)
git show <rollback-commit>:prompts/production/<gate-id>/prompt.md > prompts/production/<gate-id>/prompt.md

# Step 3: コミット（緊急フラグを明記）
git add prompts/production/<gate-id>/
git commit -m "fix(prompts): [EMERGENCY-ROLLBACK] gate<N>-<id> を <semver> に緊急切戻し

理由: <障害内容・Langfuse リンク>
KV ポインタ切替時刻: YYYY-MM-DD HH:MM JST
git-KV 乖離解消PR: <このコミットのPR番号>

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>"

# Step 4: PR を作成（通常フローで eval CI を通過させる）
# ロールバックは既知の良いバージョンへの戻りなので eval は pass するはず

4.3 ロールバック後の根本原因分析

1. Langfuse の eval トレースを確認し、どのケースで失敗したかを特定
2. prompts-eval/datasets/<gate-id>/golden.jsonl に失敗ケースを追加
3. 修正版プロンプトを作成し、通常の PR フローで再デプロイ

5. KV / git 乖離検知と復旧フロー

5.1 乖離検知（週次 cron で自動実行）

# .github/workflows/prompt_regression_cron.yml が週次で実行
# 以下の乖離チェックが含まれる:
# - KV の現在値 (wrangler kv:key get) vs git の HEAD 内容 (cat prompts/production/<id>/prompt.md) を diff
# - 乖離が検出された場合: GitHub Issue を自動起票

乖離が発生する主なケース:

• KV を直接手動編集し、git への反映を忘れた（緊急ロールバック後に多い）
• CI の KV プッシュステップが失敗し、git は更新されたが KV が古いまま

5.2 乖離発見後の復旧フロー

原則: git が正本。KV を git に合わせる。

# ケース A: KV が古い（CI の push が失敗した）
# → git の最新版を KV に強制プッシュ

# Step 1: git の現在のプロンプト内容を確認
cat prompts/production/<gate-id>/prompt.md

# Step 2: KV の現在値を確認
wrangler kv:key get --binding=PROMPTS_KV "bizlp:prompts:<gate-id>:active"
wrangler kv:key get --binding=PROMPTS_KV "bizlp:prompts:<gate-id>:<semver>"

# Step 3: git の内容で KV を上書き
cat prompts/production/<gate-id>/prompt.md | \
  wrangler kv:key put --binding=PROMPTS_KV "bizlp:prompts:<gate-id>:<semver>" --stdin
wrangler kv:key put --binding=PROMPTS_KV "bizlp:prompts:<gate-id>:active" "<semver>"

# Step 4: CI の失敗原因を調査・修正（再発防止）

# ケース B: KV が新しい（手動編集後 git 反映忘れ）
# → KV から内容を取得して git に反映する PR を作成

# Step 1: KV の現在値を取得してファイルに書き出す
wrangler kv:key get --binding=PROMPTS_KV "bizlp:prompts:<gate-id>:<最新semver>" \
  > prompts/production/<gate-id>/prompt.md

# Step 2: prompt.meta.yaml の semver を更新（手動編集した内容に応じて）

# Step 3: eval CI を通過させる PR を作成
# この PR がマージされれば KV も CI 経由で正式に更新され、乖離が解消する

5.3 乖離を防ぐための運用ルール

• KV の直接手動編集は緊急時のみ許容。通常は PR → CI 経由のみ。
• 緊急手動編集後は 24 時間以内に git 同期 PR を作成する。
• 週次 cron の GitHub Issue を放置しない（1 週間以内に解消）。

6. docs/_internal/ のパイプライン関連ドキュメントの位置づけ

6.1 SSoT の分離

docs/_internal/decision_pipeline/prompts/ の各ファイルは 人間可読の設計ドキュメント（Type 3）。
プロンプト本文の SSoT は prompts/production/ の prompt.md。両者の内容が乖離しないよう、プロンプト更新時には両方を同一 PR で更新すること。

6.2 ADR-0039 との関係

docs/_internal/ は ADR-0039（arc42+feature-folder 構造刷新）の対象外。
パイプライン・ワークフロー系の運用ドキュメントは現状 docs/_internal/ 配下に留め置く。
将来的に docs/_internal/ が肥大化し整理が必要になった場合は、別途 ADR を起こして対応する。

7. 週次 cron（Drift 監視）の運用

実行タイミング: 毎週月曜 0:00 JST（golden.jsonl が 20 件以上揃った後に有効化）
有効化条件: 全 Type 1 プロンプト × golden.jsonl 20 件以上（D+60: 2026-07-14 目安）
閾値割れ時: GitHub Issue を自動起票（担当: [email protected]）

cron で Issue が起票されたときの対応フロー:

1. Langfuse でどのケースが失敗したか確認
2. Prompt Drift（モデル更新による無編集の挙動変化）か Prompt Regression（編集ミス）かを判別
3. Drift の場合: model_pin を新しいモデルバージョンに更新 + 必要なら PATCH でプロンプト調整
4. Regression の場合: ロールバック（§4 参照）または修正 PR を作成
5. Issue をクローズ

8. 中間マイルストーン（ADR-0042 §5.3 より）