# デプロイ済みの本番が 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 が同じ巻き戻しを引き起こす**。 時限爆弾になる。 ## 判定コマンド ```bash # 1) コミット数 git rev-list --count HEAD # 2) ホスティング側のデプロイ履歴（Vercel の例） vercel ls # 3) git ホスティング側に CI/CD 連携の記録があるか（GitHub の例） gh api repos///deployments --jq 'length' gh api repos///commits//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=&target=production&limit=5&teamId= → 最新の本番デプロイの id GET https://api.vercel.com/v6/deployments//files?teamId= → ファイル木（type:"directory" は children を持つので再帰する） GET https://api.vercel.com/v7/deployments//files/?teamId= → 中身。応答が {data:""} の場合と生テキストの場合があるので両方に対応する ``` `Authorization: Bearer ` を付ける。`node_modules` と `.vercel` は回収から除外。 ### 回収したら必ず差分を出す 「git に無いファイル」「git と中身が違うファイル」「同じファイル」の3つに分類して**件数と一覧を出す**。 特に**認証・認可・秘密の検証を行っているファイル**は、本番版がどの環境変数を参照しているかを 変数名レベルで比較する。ここが減っていたら、それが「消えかけた機能」。 ## 回収したものの扱い - **本番の実体を1コミットとして git へ入れる**（「本番を復元」というコミットメッセージにする）。 これで初めて git が本番の正本になり、以後の変更が安全になる。 - **秘密ファイルを git に入れない。** デプロイ済みバンドルには、環境変数のダンプ（`.env` 系）が 混入していることがある。実例では**共有シークレットと全社APIキーが平文で同梱**されていた。 `.gitignore` に `.env*` と `*.bak-*` を足し、次のデプロイからは同梱されないようにする （実行時に読まれていないことをコード検索で確認してから外す）。 - 機能追加は**復元コミットの後**に積む。復元前に足すと、足した瞬間に既存機能が消える。 ## 本番に触る直前の保険 1. **戻り先を控える**: 現在の本番デプロイ URL を1行メモする。 2. **基準値を測る**: 本番の代表的なエンドポイントを実際に叩き、 ステータスと**返ってくる要素の一覧（件数だけでなく名前）**を記録する。 3. デプロイ後に同じ測定をして**完全一致**を確認する。一致しなければ即座に前のデプロイへ戻す。 「デプロイが成功した」は検証ではない。**変えていない機能が変わっていないこと**を測って初めて検証。 ## 既存の認証コードに手を入れないという判断 新しいエンドポイントを足すとき、既存の認証ロジックを共通モジュールに切り出したくなる。 **本番の認証コードには触らないほうがよい場合がある**。判断基準: - そのコードが落ちると**全端末が一斉に締め出される**ならリファクタしない - 新しい側に**同じ挙動を忠実に移植**し、重複を許容する - 代わりに**回帰テストで固定する**: 既存ファイルが新モジュールを参照していないこと、 ファイルのバイト数が想定どおりであること（うっかり整形されたら落ちる） 「重複は悪」は一般には正しいが、**巻き添えの範囲が全端末なら重複のほうが安い**。 この判断は必ず理由ごとコミットメッセージに残す。次に読む人が「DRY でない」と戻すのを防ぐ。 ## データファイルを関数バンドルに確実に含める サーバーレス関数から**データファイルを実行時に読む設計は避ける**。 バンドラは依存を辿るので、`require` された JS モジュールは確実に同梱されるが、 **ディレクトリを走査して読むデータファイルは同梱されないことがある**（設定で明示同梱が必要）。 安全な形は「データを JS モジュールとして生成する」: ```js // 自動生成。編集しない。 module.exports = { version: 1, generatedAt: "2026-01-01T00:00:00.000Z", files: { "a.md": "…本文…" } }; ``` 生成時の埋め込みは**必ず `JSON.stringify`**。本文にバッククォート・`${}`・改行・`` が 入っていても壊れない。自前のエスケープを書かないこと。 ## 実例（この指示書が生まれた事故） 社内の全端末へ 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 もしないこと。 特に認証・認可のファイルは、本番版が参照している環境変数名を列挙して比較すること。 ``` ---