デプロイ済みの本番が git より新しいプロジェクトを、壊さずに触る

これは何の指示書か

Vercel（同型の問題は Netlify / Cloud Run / Lambda でも起きる）で動いている既存プロジェクトに 機能を1つ足したいとき、そのリポジトリを clone して push / deploy すると本番が壊れることがある。 原因は「本番が git から作られていない」こと。この指示書は、触る前に本番の実体を回収して git と突き合わせる手順と、回収に使う API 呼び出しを書いたもの。

AI エージェントに作業させる場合、この判定を先にやらせないと「テストも通ったしCIも緑」のまま 本番機能を消す。実際に、全端末の認証が落ちる寸前まで行った（下記「実例」）。

先に結論（チェックリスト）

既存の本番プロジェクトを触る前に、次の3つを必ず順に実行する。1つでも該当したら手を止める。

1. git rev-list --count HEAD … コミット数が不自然に少ない（1〜数本）
2. ホスティング側の履歴 … デプロイ回数がコミット数より明らかに多い
3. git ホスティング側の deployment / check 記録が 0件 … CI/CD 連携が存在しない

3が0件なら、本番は「誰かがローカルから直接上げたコード」で動いている。git は本番ではない。

なぜ危険か

• git 連携が無いプロジェクトへ push しても何も起きない（デプロイされない）ので、 「push したのに反映されない」で気づくならまだ良い。
• 本当に危ないのはローカルから deploy した瞬間。手元の（＝古い）コードで本番が上書きされ、 本番にだけ存在した機能が消える。テストは手元のコードに対して緑のままなので、誰も気づかない。
• さらに悪いのは、後から git 連携を有効にしたときで、次の push が同じ巻き戻しを引き起こす。 時限爆弾になる。

判定コマンド

# 1) コミット数
git rev-list --count HEAD

# 2) ホスティング側のデプロイ履歴（Vercel の例）
vercel ls <project-name>

# 3) git ホスティング側に CI/CD 連携の記録があるか（GitHub の例）
gh api repos/<owner>/<repo>/deployments --jq 'length'
gh api repos/<owner>/<repo>/commits/<sha>/check-runs --jq '.check_runs | length'

3 が両方 0 なら連携なし。デプロイ主体（vercel ls の Username 列）が常に個人アカウントなのも傍証。

本番ソースの回収（Vercel）

Vercel はデプロイ済みのソースを API で取り出せる。ダッシュボードを人が開く必要はない。

認証トークンの場所

CLI がログイン済みなら、トークンはローカルにある。よくある場所:

• Windows: %APPDATA%\xdg.data\com.vercel.cli\auth.json
• macOS/Linux: ~/.local/share/com.vercel.cli/auth.json または ~/.vercel/auth.json

見つからないときは auth.json をホーム以下で名前検索する（深さ4程度で足りる）。 トークンの値をログ・標準出力・コミットに出さないこと。 読むのはプロセス内だけにする。

手順

GET https://api.vercel.com/v2/teams
  → 対象チームの id を取る（個人アカウントなら不要）

GET https://api.vercel.com/v6/deployments?app=<project>&target=production&limit=5&teamId=<id>
  → 最新の本番デプロイの id

GET https://api.vercel.com/v6/deployments/<id>/files?teamId=<id>
  → ファイル木（type:"directory" は children を持つので再帰する）

GET https://api.vercel.com/v7/deployments/<id>/files/<fileId>?teamId=<id>
  → 中身。応答が {data:"<base64>"} の場合と生テキストの場合があるので両方に対応する

Authorization: Bearer <token> を付ける。node_modules と .vercel は回収から除外。

回収したら必ず差分を出す

「git に無いファイル」「git と中身が違うファイル」「同じファイル」の3つに分類して件数と一覧を出す。 特に認証・認可・秘密の検証を行っているファイルは、本番版がどの環境変数を参照しているかを 変数名レベルで比較する。ここが減っていたら、それが「消えかけた機能」。

回収したものの扱い

• 本番の実体を1コミットとして git へ入れる（「本番を復元」というコミットメッセージにする）。 これで初めて git が本番の正本になり、以後の変更が安全になる。
• 秘密ファイルを git に入れない。 デプロイ済みバンドルには、環境変数のダンプ（.env 系）が 混入していることがある。実例では共有シークレットと全社APIキーが平文で同梱されていた。 .gitignore に .env* と *.bak-* を足し、次のデプロイからは同梱されないようにする （実行時に読まれていないことをコード検索で確認してから外す）。
• 機能追加は復元コミットの後に積む。復元前に足すと、足した瞬間に既存機能が消える。

本番に触る直前の保険

1. 戻り先を控える: 現在の本番デプロイ URL を1行メモする。
2. 基準値を測る: 本番の代表的なエンドポイントを実際に叩き、 ステータスと**返ってくる要素の一覧（件数だけでなく名前）**を記録する。
3. デプロイ後に同じ測定をして完全一致を確認する。一致しなければ即座に前のデプロイへ戻す。

「デプロイが成功した」は検証ではない。変えていない機能が変わっていないことを測って初めて検証。

既存の認証コードに手を入れないという判断

新しいエンドポイントを足すとき、既存の認証ロジックを共通モジュールに切り出したくなる。 本番の認証コードには触らないほうがよい場合がある。判断基準:

• そのコードが落ちると全端末が一斉に締め出されるならリファクタしない
• 新しい側に同じ挙動を忠実に移植し、重複を許容する
• 代わりに回帰テストで固定する: 既存ファイルが新モジュールを参照していないこと、 ファイルのバイト数が想定どおりであること（うっかり整形されたら落ちる）

「重複は悪」は一般には正しいが、巻き添えの範囲が全端末なら重複のほうが安い。 この判断は必ず理由ごとコミットメッセージに残す。次に読む人が「DRY でない」と戻すのを防ぐ。

データファイルを関数バンドルに確実に含める

サーバーレス関数からデータファイルを実行時に読む設計は避ける。 バンドラは依存を辿るので、require された JS モジュールは確実に同梱されるが、 ディレクトリを走査して読むデータファイルは同梱されないことがある（設定で明示同梱が必要）。

安全な形は「データを JS モジュールとして生成する」:

// 自動生成。編集しない。
module.exports = {
  version: 1,
  generatedAt: "2026-01-01T00:00:00.000Z",
  files: { "a.md": "…本文…" }
};

生成時の埋め込みは必ず JSON.stringify。本文にバッククォート・${}・改行・</script> が 入っていても壊れない。自前のエスケープを書かないこと。

実例（この指示書が生まれた事故）

社内の全端末へ API キーを配る小さな配信サーバがあった。新しい配信口を1つ足すため clone したところ:

• git はコミット1本、しかし本番は8日で7回以上デプロイ、git ホスティング側の deployment 記録は0件
• clone 側の認証コードは共有シークレット1本しか検証しない版
• 回収した本番の実体は3,936バイトで、追加の秘密（ローテーション用・新規登録用）も受け付ける版だった

そのまま deploy していれば、旧シークレットで認証していた端末が一斉に 401 になり、 鍵配布が全滅していた（同じ事故は過去に2回起きていた）。 さらに本番バンドルには環境変数ダンプが混入し、共有シークレットと全社APIキーが平文で入っていた。

回収 → 復元 → 追加 の順にしたことで、どちらも起きずに済んだ。

AI エージェントに任せるときの指示文

このプロジェクトに機能を足す前に、次を必ず実行して報告すること:
1. git のコミット数
2. ホスティング側のデプロイ回数と、デプロイ主体（CI か個人か）
3. git ホスティング側の deployment / check 記録の件数

3 が 0 なら「本番は git から作られていない」と判断し、
本番ソースを API で回収して git と差分を出すまで、push も deploy もしないこと。
特に認証・認可のファイルは、本番版が参照している環境変数名を列挙して比較すること。