deploy-to-vercel

Vercel へのデプロイ

任意のプロジェクトを Vercel にデプロイします。ユーザーが明示的に本番環境へのデプロイを求めない限り、常にプレビューとしてデプロイしてください（本番環境にはデプロイしない）。

目標は、ユーザーを最適な長期的構成に導くことです。つまり、プロジェクトを Vercel にリンクし、git push によるデプロイを行える状態にすることです。以下のどの方法も、ユーザーをその状態に近づけるものです。

ステップ 1: プロジェクトの状態を確認する

デプロイ方法を決める前に、4 つのチェックをすべて実行してください:

# 1. Check for a git remote
git remote get-url origin 2>/dev/null

# 2. Check if locally linked to a Vercel project (either file means linked)
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null

# 3. Check if the Vercel CLI is installed and authenticated
vercel whoami 2>/dev/null

# 4. List available teams (if authenticated)
vercel teams list --format json 2>/dev/null

チームの選択

ユーザーが複数のチームに所属している場合は、利用可能なすべてのチームのスラグを箇条書きで提示し、どのチームにデプロイするかを尋ねてください。ユーザーがチームを選んだら、追加の確認をせずにすぐ次のステップに進んでください。

以降のすべての CLI コマンド（vercel deploy、vercel link、vercel inspect など）には、--scope でチームスラグを渡してください:

vercel deploy [path] -y --no-wait --scope <team-slug>

プロジェクトがすでにリンクされている場合（.vercel/project.json または .vercel/repo.json が存在する場合）、それらのファイル内の orgId によってチームが決まるため、再度尋ねる必要はありません。チームが 1 つだけの場合（または個人アカウントのみの場合）は、確認を省略してそのまま使用してください。

.vercel/ ディレクトリについて: リンク済みのプロジェクトには、次のいずれかがあります:

• .vercel/project.json — vercel link によって作成されます（単一プロジェクトのリンク）。projectId と orgId を含みます。
• .vercel/repo.json — vercel link --repo によって作成されます（リポジトリベースのリンク）。orgId、remoteName、およびディレクトリを Vercel プロジェクト ID に対応付ける projects 配列を含みます。

どちらのファイルがあっても、プロジェクトはリンク済みです。両方を確認してください。

実行しないこと: リンクされていないディレクトリで状態を検出するために vercel project inspect、vercel ls、vercel link を使わないでください。.vercel/ の設定がないと、これらのコマンドは対話形式で確認を求めるか（--yes を付けると、副作用として黙ってリンクしてしまいます）。どこでも実行して安全なのは vercel whoami だけです。

ステップ 2: デプロイ方法を選ぶ

リンク済み（.vercel/ あり）かつ git リモートあり → Git Push

これは理想的な状態です。プロジェクトはリンクされており、git 連携も設定されています。

1. push する前にユーザーに確認してください。 明示的な承認なしに push しないでください:

   This project is connected to Vercel via git. I can commit and push to
   trigger a deployment. Want me to proceed?
   

2. コミットして push します:

   git add .
   git commit -m "deploy: <description of changes>"
   git push
   

   Vercel は push を契機に自動でビルドします。本番ブランチ以外のブランチはプレビューデプロイとなり、本番ブランチ（通常は main）は本番デプロイとなります。

3. プレビュー URL を取得します。 CLI が認証済みの場合:

   sleep 5
   vercel ls --format json
   

   JSON 出力には deployments 配列が含まれます。最新のエントリを見つけてください。その url フィールドがプレビュー URL です。

   CLI が認証されていない場合は、Vercel ダッシュボード、または git プロバイダー上のコミットのステータスチェックでプレビュー URL を確認するよう、ユーザーに伝えてください。

---

リンク済み（.vercel/ あり）かつ git リモートなし → vercel deploy

プロジェクトはリンクされていますが、git リポジトリはありません。CLI で直接デプロイします。

vercel deploy [path] -y --no-wait

--no-wait を使うと、ビルドが完了するまでブロックされず、CLI がデプロイ URL をすぐに返します（ビルドには時間がかかることがあるためです）。その後、次のコマンドでデプロイの状態を確認します:

vercel inspect <deployment-url>

本番デプロイの場合（ユーザーが明示的に求めた場合のみ）:

vercel deploy [path] --prod -y --no-wait

---

未リンク + CLI は認証済み → 先にリンクし、その後デプロイ

CLI は動作しているものの、プロジェクトはまだリンクされていません。これは、ユーザーを最適な状態にする機会です。

1. ユーザーにデプロイ先のチームを尋ねます。 ステップ 1 で取得したチームのスラッグを箇条書きで提示します。チームが 1 つだけの場合（または個人アカウントのみの場合）、この手順は省略します。

2. チームが選択されたら、そのままリンク処理に進みます。 何が行われるかをユーザーに伝えますが、別途確認は求めないでください:

   Linking this project to <team name> on Vercel. This will create a Vercel
   project to deploy to and enable automatic deployments on future git pushes.
   

3. Git リモートが存在する場合は、選択したチームスコープを指定してリポジトリベースのリンクを使用します:

   vercel link --repo --scope <team-slug>
   

   これは Git リモートの URL を読み取り、そのリポジトリからデプロイしている既存の Vercel プロジェクトと照合します。.vercel/repo.json を作成します。--repo を付けない vercel link は、ディレクトリ名で照合しようとするため、ローカルフォルダと Vercel プロジェクトの名前が異なると失敗することが多く、こちらの方がはるかに確実です。

   Git リモートが存在しない場合は、標準のリンクにフォールバックします:

   vercel link --scope <team-slug>
   

   これはユーザーにプロジェクトの選択または作成を求めます。.vercel/project.json を作成します。

4. 次に、利用可能な最適な方法でデプロイします:

   • Git リモートが存在する場合 → コミットしてプッシュします（上記の git push 方式を参照）
   • Git リモートが存在しない場合 → vercel deploy [path] -y --no-wait --scope <team-slug> を実行し、その後 vercel inspect <url> でステータスを確認します

---

未リンク + CLI 未認証 → インストール、認証、リンク、デプロイ

Vercel CLI がまったくセットアップされていない場合です。

1. CLI をインストールします（未インストールの場合）:

   npm install -g vercel
   

2. 認証します:

   vercel login
   

   ユーザーはブラウザで認証を完了します。ログインができない非対話型の環境で実行している場合は、下記の 認証なしフォールバック に進みます。

3. デプロイ先のチームを尋ねます — vercel teams list --format json から取得したチームのスラッグを箇条書きで提示します。チームが 1 つだけ、または個人アカウントのみの場合は省略します。選択されたら、すぐに進みます。

4. 選択したチームスコープを指定してプロジェクトをリンクします（Git リモートが存在する場合は --repo を使用し、それ以外は通常の vercel link を使用します）:

   vercel link --repo --scope <team-slug>   # if git remote exists
   vercel link --scope <team-slug>          # if no git remote
   

5. 利用可能な最適な方法でデプロイします（リモートが存在する場合は git push、それ以外は vercel deploy -y --no-wait --scope <team-slug> を実行し、その後 vercel inspect <url> でステータスを確認します）。

---

認証なしフォールバック — claude.ai サンドボックス

使用するタイミング: claude.ai サンドボックスで CLI をインストールまたは認証できない場合の最後の手段です。認証は不要で、プレビュー URL（公開サイト）と クレーム URL（Vercel アカウントへの移管）が返されます。

bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]

引数:

• path - デプロイするディレクトリ、または .tgz ファイル（デフォルトは現在のディレクトリ）

例:

# Deploy current directory
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh

# Deploy specific project
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project

# Deploy existing tarball
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz

スクリプトは package.json からフレームワークを自動検出し、プロジェクトをパッケージ化（node_modules、.git、.env を除外）してアップロードし、ビルドの完了を待機します。

ユーザーに伝える内容: 「デプロイが完了しました。プレビュー URL は [previewUrl] です。デプロイを管理するには [claimUrl] でクレームしてください。」

---

認証なしフォールバック — Codex サンドボックス

使用するタイミング: CLI が認証されていない可能性がある Codex サンドボックスでの利用時です。Codex はデフォルトでサンドボックス環境内で実行されます。まず CLI を試し、認証に失敗した場合はデプロイスクリプトにフォールバックしてください。

1. Vercel CLI がインストールされているか確認します（この確認にエスカレーションは不要です）:

   command -v vercel
   

2. vercel がインストールされている場合、CLI でのデプロイを試します:

   vercel deploy [path] -y --no-wait
   

3. vercel がインストールされていない場合、または CLI が "No existing credentials found" で失敗した場合は、フォールバックスクリプトを使用します:

   skill_dir="<path-to-skill>"
   
   # Deploy current directory
   bash "$skill_dir/resources/deploy-codex.sh"
   
   # Deploy specific project
   bash "$skill_dir/resources/deploy-codex.sh" /path/to/project
   
   # Deploy existing tarball
   bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz
   

スクリプトはフレームワークの検出、パッケージ化、デプロイを処理します。ビルドの完了を待機し、previewUrl と claimUrl を含む JSON を返します。

ユーザーに伝える内容: 「デプロイが完了しました。プレビュー URL は [previewUrl] です。デプロイを管理するには [claimUrl] でクレームしてください。」

エスカレーションされたネットワークアクセス: サンドボックスによってネットワーク呼び出しがブロックされた場合にのみ、実際のデプロイコマンドをエスカレーションしてください（sandbox_permissions=require_escalated）。command -v vercel の確認はエスカレーションしてはいけません。

---

エージェント固有の注意事項

Claude Code / ターミナルベースのエージェント

フルのシェルアクセスがあります。/mnt/skills/ パスは使用しないでください。上記の意思決定フローに従い、CLI を直接使用してください。

認証不要のフォールバックとして、スキルのインストール先からデプロイスクリプトを実行してください:

bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]

パスは、ユーザーがスキルをインストールした場所によって異なる場合があります。

サンドボックス環境 (claude.ai)

vercel login や git push は実行できない可能性が高いです。認証不要のフォールバック — claude.ai サンドボックス に直接進んでください。

Codex

Codex はサンドボックス内で実行されます。まず CLI が利用可能かどうかを確認し、利用できない場合はデプロイスクリプトにフォールバックしてください。認証不要のフォールバック — Codex サンドボックス に進んでください。

---

出力

デプロイ URL は必ずユーザーに表示してください。

• Git push: vercel ls --format json を使用してプレビュー URL を見つけてください。CLI が認証されていない場合は、Vercel ダッシュボードまたはコミットのステータスチェックを確認するようユーザーに伝えてください。
• CLI デプロイ: vercel deploy --no-wait が返す URL を表示してください。vercel inspect <url> を使用してビルドの状態を確認し、ユーザーに報告してください。
• 認証不要のフォールバック: プレビュー URL とクレーム URL の両方を表示してください:

  Deployment successful!
  
  Preview URL: https://my-app-abc123.vercel.app
  Claim URL:   https://vercel.com/claim-deployment?code=...
  
  View your site at the Preview URL.
  To transfer this deployment to your Vercel account, visit the Claim URL.
  

デプロイされた URL にアクセスして動作を確認するための curl や fetch は 行わないでください。リンクを返すだけにしてください。

---

トラブルシューティング

ネットワークのエグレスエラー (claude.ai)

claude.ai でネットワーク制限によりデプロイが失敗した場合は、ユーザーに次のように伝えてください:

Deployment failed due to network restrictions. To fix this:

1. Go to https://claude.ai/settings/capabilities
2. Add *.vercel.com to the allowed domains
3. Try deploying again

権限昇格によるネットワークアクセス (Codex / サンドボックス環境)

サンドボックス環境でネットワークの問題（タイムアウト、DNS エラー、接続リセットなど）によりデプロイが失敗した場合は、昇格された権限 (sandbox_permissions=require_escalated) を指定して再実行してください。CLI の利用可能性チェックは昇格させないでください。実際のデプロイコマンドのみ昇格させてください。

ユーザーへの案内例:

The deploy needs escalated network access to deploy to Vercel. I can rerun
the command with escalated permissions — want me to proceed?

CLI 認証の失敗

vercel login または vercel deploy が認証エラーで失敗した場合は、認証不要のデプロイスクリプトにフォールバックしてください（環境に応じて claude.ai 版または Codex 版）。