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行のインポートで取り込みます。

CLIリファレンスの説明は「AGENTS.mdとCLAUDE.mdを含めてコーディングエージェントを導く(既定で有効)」です。対話プロンプトで「recommended defaults」を選ぶと、TypeScript・ESLint・Tailwind CSS・App Router・AGENTS.mdがまとめて有効になります。個別に選びたいときは--no-agents-mdを付けるか、customize settingsの最後の質問に「No」と答えます。既存のTailwind v3プロジェクトを上げる場合は、Tailwind v4への移行手順が参考になります。

前提条件

Next.js 16はNode.js 20.9以上で動作し、macOS・Windows(WSL含む)・Linuxに対応します。対応ブラウザはChrome 111以降、Edge 111以降、Firefox 111以降、Safari 16.4以降です。

Claude Code側は、AGENTS.mdを直接読む機能にv2.1.277以降が必要です。バージョンは次のコマンドで見られます。

claude --version

作成から読み込み確認までの流れ

プロジェクトの作成はnpx create-next-app@latestです。プロジェクト名と--yesを付ければ、保存済みの設定か既定値でプロンプトを飛ばせます。

対話プロンプトを1つずつ決めたいときは--yesを外します。SaaS MVPで関わりやすいオプションは次のとおりです。

実際に生成されるAGENTS.mdとCLAUDE.md

create-next-app 16.3.8で--yes --skip-install --disable-gitを付けて生成すると、直下は.gitignore・AGENTS.md・CLAUDE.md・app/・eslint.config.mjs・next.config.ts・package.jsonなどの構成になります。package.jsonの依存はnextが16.3.8、reactが19.2.8でした。next.config.tsは設定が空のままです。

CLAUDE.mdの中身は次の1行だけです。

@AGENTS.md

AGENTS.mdの全文は次のとおりです。

<!-- BEGIN:nextjs-agent-rules -->
 
# This is NOT the Next.js you know
 
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
 
This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
 
<!-- END:nextjs-agent-rules -->

BEGINとENDのコメントに挟まれた部分が、next devの管理するブロックです。プロジェクト固有の指示はこの外側に書くと、Next.jsがブロックを更新しても残ります。diffから消してもコミットしていない変更として再生成されるだけなので、最初のコミットに含めておくとツリーがきれいに保たれます。

@path/to/importは、CLAUDE.mdが別のファイルを取り込む構文です。Claude Codeは起動時にインポート先を展開し、同じ文脈に載せます。Claude固有の指示を足すなら、インポート行の下に書きます。書き方の型はCLAUDE.mdを実用に引き上げる10のパターンにあります。

AGENTS.mdが指すnode_modules/next/dist/docs/には、インストールしたバージョンのドキュメントが入っています。訓練データではなく手元のバージョンを基準に書かせるための仕組みです。コンテナ環境などでnode_modulesが見えないときは、nextjs.org/docsの各ページURLに.mdを付けるとMarkdown版が返ります。Accept: text/markdownヘッダーを送るクライアントにも同じものが返ります。

AGENTS.mdはいつClaude Codeに届くか

Claude CodeがAGENTS.mdを直接読めるようになったのはv2.1.277からです。それ以前のバージョンはCLAUDE.mdだけを読みます。ファイルの組み合わせごとの既定の挙動は、次の対比のとおりです。

create-next-appのCLAUDE.mdは@AGENTS.mdの1行を含むので、このプロジェクトは右側の状態になりません。

2つの公式ページの記述が食い違う箇所

Next.jsのAI agents向けガイドは、Claude Code・Codex・Cursor・GitHub Copilotを挙げ、これらがセッション開始時にAGENTS.mdを自動で読むと書いています。一方、Claude Codeのメモリのページでは、既定ではCLAUDE.mdがあるとAGENTS.mdを読みません。create-next-appで作ったプロジェクトでAGENTS.mdが届くのは、この@AGENTS.mdの1行があるからです。

この食い違いが実害になるのは、CLAUDE.mdを自分で作り直したときです。@AGENTS.mdの行を消すと、Next.js側の注意書きは届かなくなります。CLAUDE.mdが.claude/CLAUDE.mdにあっても、「CLAUDE.mdがある」状態として数えられます。CLAUDE.local.mdだけがある場合も同じで、AGENTS.mdだけに頼るプロジェクトでCLAUDE.local.mdを足すと、直接読み込みが止まります。

個人用の指示をCLAUDE.local.mdに置きつつ両方を読ませるには、Project instructionsをclaude-md-and-agents-mdにします。この設定は、Claude Codeの/configで開く設定画面にあるProject instructionsです。claude-md-and-agents-mdにすると、各ディレクトリのCLAUDE.mdの後にAGENTS.mdが読まれます。すでにインポートで読み込んだAGENTS.mdは、重複して読まれません。設定ファイルに書く場合は、~/.claude/settings.jsonに次のように書きます。プロジェクト用・ローカル用の設定ファイルに書いても無視されます。

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

AGENTS.mdを直接読めないセッションもあります。v2.1.277より前のバージョンのほか、組み込みのagents-mdプラグインを/pluginで無効にした場合や、v2.1.276以前からアップグレードした直後の最初のセッションが該当します。v2.1.281より前は、Amazon Bedrock経由やtelemetryを無効にしたセッションでも同じでした。こうしたセッションがチームに混ざるなら、CLAUDE.mdの@AGENTS.mdインポートを残しておけば、読み込みの経路が1本にそろいます。ツールをまたいだ運用はAGENTS.mdとCLAUDE.mdで設定を統合する運用パターンにまとめています。

読み込まれる対象にも範囲があります。AGENTS.local.md・AGENTS.override.md・.agents/配下のファイルは読まれません。設定経由でAGENTS.mdを読んだ場合、InstructionsLoaded hookは発火しません。CLAUDE.mdが@AGENTS.mdで取り込んだ場合は、通常どおり発火します。

これまでの回避策が残っている既存プロジェクトでは、AGENTS.mdの中身を出力するSessionStart hookを外します。Claudeが直接読むようになると、hookが同じ内容を文脈にもう1部足してしまうためです。

読み込みの確認は/contextです。Memory filesにCLAUDE.mdが並んでいれば、そこから@AGENTS.mdが展開されます。AGENTS.mdだけの構成なら、対話セッションの開始時にno CLAUDE.md found; AGENTS.md loaded: <パス>という形の1行が表示されます。

Claude固有の指示を足す

AGENTS.mdはNext.jsが管理する部分を含むので、Claude Code専用の運用はCLAUDE.mdのインポート行の下に足します。SaaSのMVPなら、課金まわりのコードだけ慎重に進めさせる、といった指示がこの置き場所に向いています。

@AGENTS.md
 
## Claude Code
 
課金処理(app/billing/)を変えるときは、先にプランモードで方針を出す。

CLAUDE.mdをAGENTS.mdへのシンボリックリンクにする方法もあります。ただしClaudeのEditツールとWriteツールはシンボリックリンク越しの書き込みを拒み、リンク先のAGENTS.mdを編集するよう促されます。Windowsでは、リンクの作成に管理者権限か開発者モードが要ります。core.symlinksを無効にしたGitクライアントでは、コミット済みのリンクが1行のテキストファイルとしてチェックアウトされ、指示が失われます。create-next-appが生成する構成はインポート方式なので、この問題は起きません。

実行時の状態をClaude Codeに見せる

next devを起動すると、ブラウザのコンソールエラーや警告がターミナルへ転送されます。エージェントが普段読むターミナル出力に、クライアント側の失敗も載ります。転送はlogging.browserToTerminalの設定で制御されています。

next devは起動時にPID・ポート・URLを.next/dev/lockへ書きます。同じプロジェクトで2つ目のnext devを起動すると、動いているサーバーのURLと停止用のPIDが表示されます。エージェントは重複して立ち上げずに、既存のサーバーへつなげます。

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

両方を組み合わせたnext-dev-loopというSkillがNext.jsのリポジトリで配布されています。

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

入れたあとは、次のように指示すると編集のたびに実行時の動作を見ながら進みます。

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

Next.jsのガイドは、フレームワークの知識そのものはSkillではなく同梱ドキュメントに持たせる設計だと説明しています。Skillが担うのは、Cache Componentsへの移行のような複数手順の作業です。移行用のnext-cache-components-adoption、ナビゲーションを即時にするnext-cache-components-optimizer、next-partial-prefetching-adoptionの3つが同じ形式で配布されています。

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

本番ビルドではサーバーコードが圧縮されてスタックが読みづらくなります。next build --debug-prerenderを使うと、サーバーのソースマップが有効になり、最初の失敗の先までビルドが続きます。

よくあるつまずき

• 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コーディングエージェントが検出され、管理ブロックがなければ2ファイルが生成されます。既存のAGENTS.mdやCLAUDE.mdがあっても、ブロックの外側は保たれます。
• 16.2以前のプロジェクト: 16.2はドキュメントが同梱されるだけで、AGENTS.mdは自動生成されません。自分でファイルを作り、node_modules/next/dist/docs/を読むよう書きます。16.1以前はドキュメントも同梱されないので、npx @next/codemod@canary agents-mdでバージョン別のコピーを.next-docs/に取得します。
• 自動生成そのものを止めたい: next.config.tsでagentRulesをfalseにします。

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

Next.jsをアップグレードすると、node_modules/next/dist/docs/のドキュメントも入れ替わります。AGENTS.mdが指す先が新しいバージョンに変わるので、Claude Codeは訓練データではなく手元のバージョンを基準にコードを書けます。

npx next upgrade

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

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

CLAUDE.mdやAGENTS.mdが古くなっていないかを見直したいときは、セッションで/doctor prompt-auditを実行します。CLAUDE.md・CLAUDE.local.md・AGENTS.mdと.claude/配下のルールやSkillを対象に、古い記述や矛盾、存在しないファイルへの参照を探し、修正案つきのレポートを返します。ユーザーが頼むまでファイルは変わりません。v2.1.283以降で使えます。同梱の/claude-api Skillを経由して動くため、skillOverridesやdisableBundledSkillsでそのSkillを無効にしていると使えません。

まとめ

create-next-appの既定で生成される2ファイルを、そのまま使うのが出発点です。CLAUDE.mdを作り直すときは@AGENTS.mdの行を残すと、Next.jsのバージョン固有ドキュメントへの指示がClaude Codeに届き続けます。AGENTS.mdだけに頼る構成でCLAUDE.local.mdを足すときは、Project instructionsの設定が必要です。土台ができたあとの画像まわりの改修は、next/image置換の差分レビューで扱っています。