Claude CodeでNext.js SaaS MVPを作る — CLAUDE.md連携の始め方

create-next-appが生成する2つのファイル

create-next-appの--agents-mdオプションは、プロジェクト作成時にAGENTS.mdとCLAUDE.mdを既定で生成します。Next.jsとClaude CodeでSaaSのMVPを作るなら、この2ファイルが最初の土台になります。AGENTS.mdにはNext.jsのバージョン固有の注意点が入り、CLAUDE.mdはその内容を@AGENTS.mdという1行のインポートで取り込む構成です。

create-next-appのCLIリファレンスは、このオプションを「AGENTS.mdとCLAUDE.mdを含めてコーディングエージェントを導く(既定で有効)」と説明しています。対話プロンプトで「recommended defaults」を選ぶと、TypeScript・ESLint・Tailwind CSS・App Router・Turbopackに加え、AGENTS.mdの生成も一括で有効になります。個別に選びたいときは--no-agents-mdを付けるか、customize settingsの最後の質問に「No」と答えれば生成をスキップできます。

前提条件を確認する

Next.js 16はNode.js 20.9以上で動作し、macOS・Windows(WSL含む)・Linuxに対応します。対応ブラウザはChrome 111以降、Edge 111以降、Firefox 111以降、Safari 16.4以降です。SaaSのMVPは管理画面やダッシュボードなどクライアント側の描画に依存する画面が多くなりがちなので、対象ブラウザの範囲は早い段階で確認しておくと手戻りが減ります。

Claude Code側は、後述するAGENTS.mdのネイティブ読み込みにv2.1.277以降が必要です。手元のバージョンを次のコマンドで確認しておきます。

claude --version

ステップ1: プロジェクトを作成する

npx create-next-app@latestでプロジェクトを作ります。プロジェクト名を指定し、--yesを付ければ保存済みの設定か既定値でプロンプトをスキップできます。

npx create-next-app@latest my-saas-app --yes
cd my-saas-app
npm run dev

対話プロンプトを1つずつ決めたい場合は--yesを外して実行します。SaaS MVPでよく関わる主要オプションは次のとおりです。

ステップ2: 生成されたファイルの中身を見る

--agents-mdを有効にしたまま作成すると、プロジェクト直下にAGENTS.mdとCLAUDE.mdが生成されます。CLAUDE.mdの中身は次の1行だけです。

@AGENTS.md

これは、CLAUDE.mdファイルが@path/to/importという構文で別のファイルを取り込める仕組みを使ったものです。Claude Codeはセッション開始時にCLAUDE.mdを読み、そこに書かれた@AGENTS.mdを展開してAGENTS.mdの内容もあわせて読み込みます。プロジェクト固有の指示を足すときは、このインポート行の下に書き足します。書き方の型はCLAUDE.mdを実用に引き上げる10のパターンにまとまっています。

生成されるAGENTS.mdは、node_modules/next/dist/docs/に同梱されたバージョン別ドキュメントを読んでからコードを書くよう指示する内容です。このブロックはnext dev実行時に書き込まれるため、diffから消してもコミットしていない変更として再生成されるだけです。コミットしておけば、ツリーはきれいなまま保たれます。

ドキュメントはURL越しにも取得できます。nextjs.org/docsの各ページURLに.mdを付けるとMarkdown版が返り、Accept: text/markdownヘッダーを送るクライアントにも同じものが返ります。コンテナ実行環境などでnode_modulesが見えない場合、AGENTS.mdの指示をこの経路で補えます。

ステップ3: AGENTS.mdを読む条件を確認する

Claude CodeがAGENTS.mdを直接読めるようになったのは、v2.1.277からです。それより前のバージョンでは、AGENTS.mdを単独では読み込みません。

AGENTS.mdとCLAUDE.mdの両方が存在するとき、Claude Codeが実際に何を読むかはファイルの組み合わせで変わります。

create-next-appが生成するCLAUDE.mdが@AGENTS.mdのインポート1行だけになっているのは、2番目の既定挙動を避けて3番目の状態を作るためです。両方のファイルを単に並べただけでは、AGENTS.mdの内容がClaude Codeに届きません。

この既定は、Claude CodeのProject instructions設定で変更できます。設定をclaude-md-and-agents-mdにすると、CLAUDE.mdとAGENTS.mdの両方を読みに行きます。ただしAmazon Bedrock経由のセッションやtelemetryを無効化したセッション、インストール・アップグレード直後の最初のセッションでは、設定にかかわらずAGENTS.mdを直接読めません。これらの環境では、CLAUDE.mdから@AGENTS.mdでインポートする構成が引き続き必要です。ツールをまたいだ運用パターンはAGENTS.mdとCLAUDE.mdで設定を統合する運用パターンで詳しく扱っています。

ステップ4: next devでClaude Codeに実行時の状態を見せる

next devを起動すると、ブラウザのコンソールエラーや警告がターミナルへ転送されます。Claude Codeはこの出力を読むだけで、ブラウザを開かなくてもクライアント側のエラーを把握できます。

Next.js MCPサーバーは/_next/mcpでdev serverのルート・ログ・コンパイル状況を公開します。get_compilation_issuesやcompile_routeというツールを使えば、next buildを待たずにコードがコンパイルできているかを確認できます。ブラウザ側の状態はagent-browserというCLIがDOM・コンソール・ネットワーク・Web Vitalsを構造化テキストとして公開する仕組みです。

これらを組み合わせたnext-dev-loopというSkillが配布されており、次のコマンドでインストールできます。

npx skills add vercel/next.js --skill next-dev-loop

インストール後は、Claude Codeに次のような指示を渡すと、編集のたびに実行時の動作を確認しながら進みます。

After every edit, verify the page still works at runtime using the next-dev-loop Skill.

SaaS MVPではダッシュボードや設定画面など、リクエストごとに内容が変わる画面が増えます。Cache Componentsを有効にした状態でプリレンダリング中にブロッキングエラーが出ると、dev overlayにstream・cache・blockという3つの対処法がラベル付きで表示され、「Copy prompt」ボタンでその対処法をエージェント向けのプロンプトへ変換できます。同じ一覧はnext buildの出力にも表示されるため、CIログを読むエージェントも同じ情報を拾えます。

よくあるつまずき

• AGENTS.mdが読み込まれない(v2.1.277未満): 古いClaude Codeでは、CLAUDE.mdからの@AGENTS.mdインポートが無いとAGENTS.mdの中身が読まれません。バージョンをclaude --versionで確認し、上げられない場合はCLAUDE.md側にインポートを残しておきます。
• モノレポでnode_modules/next/dist/docs/が見つからない: AGENTS.mdの指示は「このファイルのディレクトリから解決する」前提で書かれており、モノレポ構成ではリポジトリのルートからnextパッケージが見えないことがあります。パッケージごとのCLAUDE.md階層をどう組むかはClaude Codeモノレポ設計を参照してください。
• --no-agents-mdを意図せず付けていた: customize settingsで最後の質問に「No」と答えると、AGENTS.mdもCLAUDE.mdも生成されません。既存プロジェクトに後付けする場合、Next.js 16.3以降ならnext devを実行すると、AIコーディングエージェントが検出されmanaged blockが無いときに自動生成されます。
• Windowsでシンボリックリンク方式を試して失敗する: CLAUDE.mdをAGENTS.mdへのシンボリックリンクにする代替策は、Windowsでは管理者権限か開発者モードが必要です。core.symlinksを有効にしていないGitクライアントでは、コミットしたシンボリックリンクがプレーンテキストのファイルとしてチェックアウトされます。create-next-appが生成する構成はシンボリックリンクではなく@AGENTS.mdインポートなので、この問題を避けられます。

アップグレードでドキュメントも一緒に更新される

Next.jsをアップグレードすると、node_modules/next/dist/docs/に同梱されたドキュメントも同時に更新されます。AGENTS.mdが指す先のドキュメント自体が最新版に置き換わるため、Claude Codeは訓練データではなく手元にインストールされたバージョンを基準にコードを書けます。SaaS MVPを継続的に育てていく前提では、このアップグレードの手軽さがAI支援開発の精度を左右します。

npx next upgrade

アップグレード後は、Claude Codeに次のように伝えると新しい変更点を踏まえた状態に追いつけます。

Let's get our Next.js knowledge up to speed, and give me a summary of what's new for you

まとめ

Next.jsでSaaSのMVPを作る最初の一歩は、npx create-next-app@latestでプロジェクトを作り、既定で生成されるAGENTS.mdとCLAUDE.mdをそのまま使うことです。Claude Codeはv2.1.277以降ならAGENTS.mdを直接読めますが、それより前のバージョンやBedrock経由のセッションではCLAUDE.mdからの@AGENTS.mdインポートが引き続き必要です。next devを起動してMCPサーバーとagent-browserによる実行時の可視性を確保しておけば、認証や決済などSaaS固有の機能を積み上げていく段階でも、Claude Codeは常にプロジェクトの現在の構成を踏まえてコードを書けます。