Vercel Codex CLI実践｜AGENTS.mdで半自動デプロイ

Vercel Codex CLIを触ってみたいけど、実装から本番反映まで毎回手順がぶれてしまう。Next.js 16.2 AGENTS.mdが良いと聞くけど、どこから整えればいいかわからない。そんな人に向けて、現場で回る形に落とした手順をまとめます。この記事を読むと、実装→Preview→本番の流れをCLI中心で半自動化できて、デプロイ直前の不安を減らせます。僕は福祉事業のIT全般を担当しながら、AI×SaaS開発を複業で回しているので、非エンジニアと一緒に運用できる粒度で解説します。

なぜ今Vercel Codex CLIとNext.js 16.2 AGENTS.mdなのか

2026年3月は、AIエージェント開発の導線が一気につながった月でした。2026年3月26日のVercel公式発表でCodex/Codex CLI対応が明確になり、2026年3月18日のNext.js 16.2ではAGENTS.mdの導線が強化されました。つまり、実装させるだけではなく、参照ルールとデプロイ運用を同時に設計しやすくなったということです。

本質は「新機能が増えた」より「手順の再現性が上がった」ことです。イメージとしては、料理レシピとキッチン動線が同時に整った状態です。以前は毎回置き場所を探していたのが、今はAGENTS.mdで参照先を固定し、Vercel CLIでPreviewから本番まで一本道にできます。ここが実務の強さです。

公開日で数値が変わる点も押さえたいです。Vercelプラグインのskills数は47+、34、39+と差がありますが、これは更新タイミング差です。日付付きで出典を併記するだけで、判断のズレをかなり減らせます。

事前準備：AGENTS.mdとCLAUDE.mdで参照順を固定する

ここが土台です。先に結論を言うと、AGENTS.mdは「エージェントの読む順番」を固定するファイルです。Next.js公式のAI Agentsガイドでは、node_modules/next/dist/docs/のローカル同梱ドキュメントを先に読む運用が示されています。つまり、検索より前に、今のバージョンに一致した一次情報を読むということです。

非エンジニア向けに言い換えると、「最新版の社内マニュアルを先に開いてから作業する」運用です。検索だけで進めると、古い記事と新仕様が混ざってミスしやすいですよね。AGENTS.mdはその混線を防ぎます。さらにCLAUDE.mdを@AGENTS.md参照にすれば、複数エージェントでも同じ前提を持てます。

# AGENTS.md
## First read
- Read local Next.js docs first: node_modules/next/dist/docs/
- Prefer version-specific docs before web search

## Development policy
- Keep diffs minimal and testable
- Use vercel CLI flow: deploy -> verify -> promote

# CLAUDE.md
@AGENTS.md

この準備だけで、実装中の迷いが目に見えて減ります。つまり「AIモデルの性能差」より先に「参照先のブレ」を潰すほうが成果につながりやすいです。

導入手順：VercelプラグインをCodex CLIへ組み込む

次は導入です。手順は短いですが、順番が大事です。公式ドキュメントではnpx plugins add vercel/vercel-pluginが基本です。Codex側はcodex起動後に/pluginsから有効化できます。ここは「動くまで触る」より「権限と対象プロジェクトを先に固定」がおすすめです。

1. Vercel認証 – vercel loginでアカウントを固定します
2. プラグイン導入 – npx plugins add vercel/vercel-pluginを実行します
3. Codex連携 – codexを開いて/pluginsからVercelを有効化します
4. 必要時のみProvider設定 – ~/.codex/config.tomlでVercel AI Gatewayを指定します

vercel login
npx plugins add vercel/vercel-plugin
codex
# in codex: /plugins

# optional
model_provider = "vercel"
model = "openai/gpt-5.2-codex"

運用メモとして、外部導線ではなく、実測ログ・設定差分・再現手順を同じ場所に残してチーム内で確認できる形にしてください。

実装→Preview→本番をつなぐCLI Runbook

Vercel Codex CLIの実務価値は、実装とデプロイを同じ文脈で回せることです。やることは単純で、deployしてPreviewを検証し、合格ならpromoteするだけです。イメージとしては、試食してから本購入する流れです。味見なしで本購入すると失敗しやすいですよね。デプロイも同じです。

1. Previewデプロイ – vercel deployでURLを取得します
2. 機械検証 – vercel curlで主要APIとページを確認します
3. ログ確認 – vercel logs --level errorで異常を確認します
4. 本番反映 – vercel promoteまたはvercel deploy --prodを実行します

# 1) preview deploy
vercel deploy > deployment-url.txt
PREVIEW_URL=$(cat deployment-url.txt)

# 2) verify
vercel curl "$PREVIEW_URL/api/health"
vercel logs --deployment "$PREVIEW_URL" --level error

# 3) promote
vercel promote "$PREVIEW_URL" --yes
vercel promote status

このRunbookをチームで共通化すると、レビューは感覚ではなくチェック項目になります。つまり、属人的なデプロイを減らせるということです。

事故を防ぐ運用設計と2026年版ベストプラクティス

実務で事故が出るのは、コマンド操作より環境差分です。Vercel公式のpromoteドキュメントにも、promote時はproduction環境変数で再ビルドされると明記されています。つまり、Previewで動いても本番だけ落ちることは普通に起こります。ここを知らないままだと、リリース直後に原因切り分けで時間を失いやすいです。

同時に、AGENTS.md運用の優位も数字で出ています。Vercelの評価記事では、Baseline 53%、Skill 53%、Skill+明示指示 79%、AGENTS.md docs index 100%という結果でした。つまり、モデル選定だけでなく参照導線設計が品質を左右するということです。

vercel env ls
vercel promote "$PREVIEW_URL" --yes --timeout 5m
vercel promote status
vercel logs --deployment "$PREVIEW_URL" --level error

運用メモとして、外部導線ではなく、実測ログ・設定差分・再現手順を同じ場所に残してチーム内で確認できる形にしてください。

この運用を知らないまま1年進めると起きること

Vercel Codex CLIとAGENTS.mdを入れずに進めると、見えないロスが積み上がります。Preview検証が人依存のままだと、担当者交代のたびに確認漏れが出やすいです。環境差分の管理が曖昧だと、同じ不具合を何度も繰り返す可能性があります。つまり、知らないまま進めるほど、技術負債より先に運用負債が増えていきます。早めに型を作っておくほうが、結果的に時間もコストも守れます。

この記事を書いている理由

僕はこれまでSES、教育、人材、そして福祉領域のIT運用まで、ITと非ITを横断してきました。結婚式Web招待状サービスを短サイクルで改善して90日以上のログイン継続率につながった経験もあり、そこで学んだのは「実装速度より検証と反映の再現性が成果を作る」ということでした。今はGhosttyとtmux中心でCodex/Claudeを日常運用しているので、机上の理想論ではなく、現場で回る形としてこの手順を共有したいんです。

次のアクション

まずはAGENTS.mdを1枚追加して、Preview検証コマンドを3つだけ固定してみてください。ここができるだけでデプロイ品質は安定しやすくなります。感想や詰まりポイントはコメントかDMで教えてください。