汚れた作業ツリーから「レビュー済みの版だけ」を本番に出す（git worktree + Vercel）

誰のための指示書か

長く動いている開発ツリーは、たいてい次の状態になっている。

• 作業ディレクトリに未コミットの変更が何十ファイルも残っている（別の作業・別の担当・別の AI セッションのもの）
• ローカルのブランチが origin より ahead でも behind でもある（push していないコミットがある一方、 レビュー済みでマージされた変更をまだ pull していない）

この状態で vercel --prod を打つと、2つの事故が同時に起きる。

1. 出したい変更が出ない（behind の分＝マージ済みの PR がローカルに無い）
2. 出してはいけない物が出る（未コミットの実験コード、他人の書きかけ、.env の残骸）

vercel は「今チェックアウトされている作業ツリーの中身」をアップロードする。 git のブランチ名や、GitHub 側のマージ状況は一切見ていない。ここが誤解の中心。

この指示書は、作業ツリーを一切触らずに「origin の、レビュー済みの、その 1 コミット」だけを本番へ出す型を渡す。

前提

• git リポジトリ（origin にリモートがある）
• Vercel CLI がログイン済み（vercel --version が通る）
• リポジトリ直下に .vercel/project.json がある（＝ vercel link 済み）
• 本番に出すブランチ名を <PROD_BRANCH> とする（main とは限らない。プロジェクトによる）

手順

1. まず「ローカルと origin がどれだけズレているか」を数字で見る

git fetch origin
git rev-list --left-right --count origin/<PROD_BRANCH>...HEAD
# 出力例: 8   2      → 左=origin にしか無い数, 右=ローカルにしか無い数

右が 0 でない限り、ローカルの HEAD を本番に出してはいけない。 そのコミットは誰のレビューも通っていない。

git log --oneline HEAD..origin/<PROD_BRANCH>   # 出したい変更がここに居るか確認する
git log --oneline origin/<PROD_BRANCH>..HEAD   # 出したくない物がここに居る

2. 汚れ具合を見る（触らない・コミットしない）

git status --short

自分が書いたのでない差分は絶対にコミットしない。 「デプロイのために邪魔だから」で他人の作業を巻き込むのが一番多い事故。 以下の手順は、この差分を残したまま安全に本番へ出せる。

3. clean worktree を切る

WT=<一時ディレクトリ>/deploy-$(date +%s)
git worktree add --detach "$WT" origin/<PROD_BRANCH>

• --detach にするのは、ブランチを奪わないため。共有ツリーで他の作業が動いていても衝突しない。
• git checkout は使わない。作業ツリーのブランチを切り替えると、そこで作業中の人・プロセスが壊れる。

4. .vercel/ をコピーする（これを飛ばすと新規プロジェクトが作られる）

cp -r .vercel "$WT/.vercel"

.vercel/ は .gitignore に入っているので worktree には存在しない。 無いまま vercel --prod を打つと、CLI は「未リンクの新しいディレクトリ」と判断し、 別の Vercel プロジェクトを新規作成してそこへデプロイする。本番は更新されないのに、 出力は成功に見える。ここは静かに失敗する典型。

5. デプロイして、出力の 2 行を必ず読む

cd "$WT" && vercel --prod --yes

読むのは次の 2 行。「Success」だけ見て終わらせない。

• ▲ Production https://<project>-<hash>-<team>.vercel.app … デプロイ先のプロジェクトが意図した物か
• ▲ Aliased https://<本番ドメイン> … 本番ドメインに実際に張り替わったか

Alias 行が出ていなければ、本番ドメインは古い版のままである。

6. 本番に切り替わったことを、デプロイ結果とは別の情報源で確認する

vercel ls --prod --yes

一番上の Age が「たった今」になっていること、その 1 つ下が以前の版の日付であることを見る。 「前の本番が何日前だったか」を併せて記録すると、後から「本当に出たのか」を疑わずに済む。

7. 実描画で検証する（HTTP ステータスで済ませない）

ログインが要るアプリでは、存在しないルートも存在するルートも等しく /login へ 307 する。 つまり curl -o /dev/null -w "%{http_code}" では新機能が出たかどうかを判定できない。 「404 じゃないから出ている」は誤り。

E2E（Playwright 等）を本番 URL に対して走らせるのが最短で確実。

# baseURL の既定が本番 URL になっているかを先に確認する
grep -n "BASE_URL" playwright.config.ts
grep -n "E2E_BASE_URL" .env.local || echo "未設定 → 既定(本番)に当たる"

npx playwright test <新機能の spec>

• ローカルの .env に baseURL の上書きが無いことを必ず確認する。 確認せずに走らせて全部 green になり、 実は localhost を見ていた、が最も多い偽の合格。
• 検証は読み取り＋プレビューまでにとどめ、本番データへの書き込みを伴う spec は流さない。

8. 後片付け

cd <元のリポジトリ> && git worktree remove --force "$WT"
git worktree list   # 消えたことを確認

検証のために元のツリーへ一時的にファイルをコピーしたなら、それも消す。 共有ツリーに未追跡ファイルを置き去りにすると、次に作業する人が自分の物と誤認してコミットする。

チェックリスト（この 6 つが揃って初めて「本番に出た」と言える）

• git rev-list --left-right --count を実際に見た（ローカル HEAD を出していない）
• worktree の HEAD が、出したい PR のマージコミットである
• .vercel/ をコピーしてからデプロイした
• 出力に Aliased <本番ドメイン> が出ている
• vercel ls --prod の最上段が今の時刻で、その下が旧版の日付である
• 本番 URL に対する実描画テストが green（ステータスコードだけで判断していない）

よくある失敗と、その正体

症状	正体
デプロイは成功するのに本番が変わらない	.vercel/ が無く、別プロジェクトへ出ている
出したはずの機能が本番に無い	ローカルが origin より behind のままデプロイした
本番に見覚えのないコードが混ざる	未コミットの作業ツリーごとアップロードされた
curl は 200 なのに機能が無い	認証ゲートが全ルートを同じ応答にしている
E2E が全部 green なのに本番は古い	baseURL がローカルを向いていた

この型が効く条件

• 「本番ブランチ = main」でないプロジェクトほど効く（CLI デプロイ運用は特に）
• 1 つのリポジトリを複数の担当・複数の AI セッションが同時に触っている環境
• CI が緑でも本番は別経路で更新される構成（＝マージ＝本番反映、が成立しない構成）