—— Claude Code / ChatGPT を使った開発で再発を防ぐための完全ガイド
はじめに
PHP から Vercel（Node.js） へ移行するプロジェクトでは、
途中でランタイム・バージョン・ディレクトリ構造が混在し、以下のような問題が高確率で発生します。
-
package.jsonの"engines"と Vercel の Node バージョンが不一致 - PHP 用のファイル構成や設定が残っている
- Vercel がどの runtime を使うべきか判定できず、ビルドエラー
- AI に依頼したコードが古い設定を参照してしまう
-
vercel.json齟齬、CI の Node バージョン mismatch
これらを防ぐためには 最初の1時間で「プロジェクト設計のルール」を明確化すること が最重要です。
本記事では、Claude Code / ChatGPT などの AI を使った開発でも再発しないよう、
最初に必ず決めるべき項目 と
AI に投げるべき「初期指示テンプレート」 を提供します。
1. 最初に必ず決めるべき 5 つの項目（超重要）
以下は プロジェクト開始 0〜1時間目に決め切るべき内容 です。
1-1. Runtime（言語）を固定する
例：
- Node.js (Vercel Runtime) を使用
- PHP は使わない（削除 or archive）
- Serverless Functions も Node.js で統一
これを曖昧にすると、本番ビルド時に「Vercel が自動判定して別の runtime を選ぶ」現象が起きます。
1-2. Node.js バージョンポリシーを固定する
例：
本プロジェクトは Node.js 22.x を標準とする
Vercel の Project Setting も Node.js 22.x
package.json の "engines" も 22.x で統一
一度決めたバージョンは途中で変えない のが鉄則です。
1-3. ディレクトリ構造を最初に確定し、AI にも共有する
例：
/Users/5dmgmt/プラグイン/foundersdirect/
├── index.html
├── js/
├── api/
├── DOCS/
├── package.json
└── vercel.json
AI（Claude Code / ChatGPT）は 古いパスを記憶しやすいため、
明確に「正しいプロジェクトルート」を初回指示で宣言する必要があります。
1-4. 使わない言語・設定を削除する（PHP など）
public/index.php.htaccess- PHP 用の設定ファイル
残っているだけで Vercel が runtime を誤判定します。
※移行時の典型トラブル。
1-5. 開発 AI 全員（Claude / ChatGPT / Copilot）の初期プロンプトを統一する
これが最も効果的です。
2. Claude Code / ChatGPT に投げるべき「初期指示テンプレート」
以下を そのまま毎回の最初のメッセージとして貼ることで、
誤判定・過去パス参照・ランタイム混在を完全防止します。
■ プロジェクト初期指示（テンプレート）
プロジェクト: Founders Direct Cockpit
ローカルパス: /Users/5dmgmt/プラグイン/foundersdirect
【重要ルール】
1. Runtime は Node.js のみ。PHP や他言語は一切使用しない。
2. 標準 Node.js バージョンは 22.x。
- package.json の "engines"
- vercel.json の NODE_VERSION
- GitHub Actions
- DOCS
全て 22.x に統一する。
3. プロジェクトルートは必ず上記パスのみを参照すること。
4. 過去のパス・古い設定は一切参照しないこと。
5. 修正提案は必ず diff ベースで提示すること。
6. 設定ファイルと DOCS の整合性も同時にチェックし、Node.js 22.x に統一すること。
7. Reset（セッション引き継ぎ）問題を避けるため、すべての依頼に対して
「現在の Node 22.x ポリシー」への整合性を維持すること。
3. PHP → Vercel(Node) への移行時に必ず発生するトラブル一覧と対策
| よくあるトラブル | 原因 | 再発防止策 |
|---|---|---|
| Vercel が PHP runtime を選んでしまう | index.php などが残っている | PHP を完全削除 |
| Node 20.x が勝手に使われる | package.json の "engines" が古い | "22.x" に統一 |
| AI が過去のパスを参照する | 初期指示が曖昧 | プロジェクトルートを毎回宣言 |
| ドキュメントと設定ファイルが矛盾 | 移行時に手作業で修正漏れ | AI に「全体整合性チェック」を毎回依頼 |
| ビルドは通るが API が動かない | runtime mismatch | vercel.json の NODE_VERSION 明示 |
4. 再発防止のための「月1メンテナンスチェック」
-
package.jsonの"engines" vercel.json- GitHub Actions
- DOCS に記載されている Node.js バージョン
- 不要ファイル（PHP等）が残っていないか
AI に下記のように依頼すれば自動で棚卸しできます：
Node.js バージョンに関する記述をすべて棚卸しし、22.x と整合しているか確認してください。
5. まとめ
- PHP から Vercel(Node.js) に移行すると 設定の混在 が必ず起きる
- 初期に Runtime / Node.js / ディレクトリ / 不要ファイル削除 を決めないと確実に詰む
- AI 開発では 初回メッセージのテンプレート化 が最重要
- 「Node.js 22.x ポリシー」を徹底すれば安定運用できる