—— 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 ポリシー」を徹底すれば安定運用できる