Next.jsのAGENTS.md自動生成とマネージドブロックの仕組み

Next.jsはnextパッケージの中にバージョンに対応したドキュメント一式を同梱しており、AIコーディングエージェントが訓練データではなくこの同梱ドキュメントを読むように、プロジェクトルートのAGENTS.mdがその入口として機能します。インストール済みのバージョンに一致するドキュメントをネットワークアクセスなしにそのまま参照でき、Next.js自体をアップグレードすれば同梱ドキュメントも一緒に更新されます。Claude Code・Codex・Cursor・GitHub Copilotなど主要なAIコーディングエージェントの多くは、セッション開始時にAGENTS.mdを自動的に読み込みます。

16.3以降では、このAGENTS.mdとCLAUDE.mdがnext devの起動時に自動生成されます。手動でファイルを作る手順ではなく、開発サーバー起動時に動くマネージドブロックという仕組みが本体です。16.2以前と16.3以降では、自動化される範囲がはっきり分かれます。

next dev実行時に何が起きるか

Next.js 16.3以降のnext devは、AIコーディングエージェントが実行環境にいると判定し、かつマネージドブロックがまだ存在しないときに、プロジェクトルートへAGENTS.mdとCLAUDE.mdを自動生成します。既にAGENTS.mdやCLAUDE.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/` 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`.
 
<!-- END:nextjs-agent-rules -->

CLAUDE.md側の生成内容はもっと単純で、@AGENTS.mdという1行だけが書き込まれます。中身を複製せず、AGENTS.mdを読み込むインポート文にする設計です。マーカーの外に自分の指示を書き足せば、Next.jsのアップデートで管理ブロックが更新されても、その部分は消えずに残ります。

バージョンによって自動化の範囲が変わる

AGENTS.mdまわりの挙動は、同梱ドキュメントの有無と自動生成の有無という2つの軸でバージョンごとに違います。

16.2で作った既存プロジェクトを16.3以降にアップグレードした場合、次にnext devを起動した時点でマネージドブロックが挿入されます。手動でcodemodを再実行する必要はありません。

新規プロジェクトと既存プロジェクトでトリガーが違う

新規プロジェクトではcreate-next-app自体がAGENTS.mdとCLAUDE.mdを生成します。

npx create-next-app@canary

生成そのものを止めたい場合は--no-agents-mdフラグを渡します。既存プロジェクトではcreate-next-appを経由しないため、トリガーはnext devの起動そのものになります。この違いから、CIやビルド専用の環境でnext buildだけを流している場合はファイルが作られません。生成はnext devの開発サーバー起動という、エージェントが実際にコードを書く場面に紐づいています。

既存のAGENTS.mdやCLAUDE.mdに指示があるとどうなるか

アップサートの実際の挙動は、既存ファイルの中身次第で変わりません。マネージドブロックの外側にあるテキストは行単位でそのまま保持され、ブロック自体だけが挿入または置き換わります。たとえば、プロジェクト固有のセットアップ手順をすでに書いていたAGENTS.mdがあるとします。

# セットアップ
- 依存関係のインストール: `pnpm install`
- 開発サーバー: `pnpm dev`

このファイルがあるリポジトリで16.3以降のnext devを起動すると、既存の2行はそのまま残り、マネージドブロックが末尾に追記される形になります。逆に、先にマネージドブロックだけが挿入された状態から自分の指示を書き足すこともできます。<!-- BEGIN:nextjs-agent-rules -->と<!-- END:nextjs-agent-rules -->の外側に書けば、次回のnext dev起動やNext.jsのアップグレードでも消えません。ブロックの中身を直接書き換えた場合は、次の起動時にマネージドブロックの定義側で上書きされる可能性があります。編集するなら常にマーカーの外、という原則を崩さないことが安全な運用です。

オプトアウトとモノレポでの注意点

自動生成そのものを止めたいときは、next.config.tsでagentRulesをfalseにします。

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  agentRules: false,
}
 
export default nextConfig

マネージドブロックの文面には、モノレポ特有の注意も含まれています。「node_modules/next/dist/docs/はこのファイルのディレクトリから解決される経路であり、モノレポではリポジトリルートからnextパッケージが見えないことがある」という一文です。パッケージごとにnextをインストールする構成では、ルート直下のAGENTS.mdが指す相対パスと、実際にエージェントが読めるnode_modulesの位置がずれる可能性があります。複数のCLAUDE.md階層をモノレポで使い分ける設定はclaudeMdExcludesの設定手順で扱っています。

生成されたCLAUDE.mdをClaude Codeはどう読むか

Claude CodeはCLAUDE.md内で@path/to/importという記法を使うと、そのファイルをインポートして起動時のコンテキストに展開します。相対パスは参照元ファイルの位置を基準に解決され、作業ディレクトリの外を指す場合だけ「外部インポート」として承認ダイアログが出ます。Next.jsが生成する@AGENTS.mdはプロジェクトルート内の相対パスなので、この承認ダイアログは発生しません。

Claude Code v2.1.277では、CLAUDE.mdが存在しないプロジェクトに限りAGENTS.mdを代わりに読み込む機能が追加されました。ただしNext.js 16.3以降のプロジェクトでは、next devがCLAUDE.md自体を生成してしまうため、この「CLAUDE.mdが無いときだけAGENTS.mdを読む」というフォールバック経路はそもそも使われません。生成されたCLAUDE.mdが@AGENTS.mdを指し、そちらを起動時にインポートする形で読み込まれます。結果として読み込まれる内容は同じでも、経路としては通常のCLAUDE.md読み込みになります。

Cursor・Cline・Windsurfなど複数のAIコーディングツールを併用していてAGENTS.mdを共通の一次情報源にしたいチームには、別の運用の型があります。AGENTS.mdとCLAUDE.mdで設定を統合する運用パターンにまとまっています。

ドキュメントをネットワーク経由で読む経路もある

node_modulesを直接読めないエージェント向けに、Next.jsは同じドキュメントをMarkdown配信でも公開しています。nextjs.org/docs配下の任意のページURLに.mdを付けるか、リクエストヘッダーにAccept: text/markdownを送ると、Markdown版が返ります。索引は/docs/llms.txt、全文は/docs/llms-full.txtで、いずれもllms.txtという規約に沿った形式です。AGENTS.mdのマネージドブロック自体はローカルのnode_modulesを指す前提で書かれており、このネットワーク経路はそれを補う位置づけです。

既定でオンにしている理由と旧Skillsの廃止

自動生成を既定でオンにしている根拠として、Next.jsはnextjs.org/evalsのベンチマーク結果を挙げています。同梱ドキュメントを読ませたエージェントのほうが良い成績を出すという実測があり、それを踏まえてオプトインではなくオプトアウト方式を選んだという説明です。

この方針転換には前史があります。Next.jsは以前、App Routerの規約やキャッシュAPIを解説する専用のSkill群(vercel-labs/next-skills)をskills.sh経由で配布していました。16.3のブログはこれらの旧Skillsを廃止すると告知しており、理由として「同梱ドキュメントがマネージドブロック経由でエージェントに届くようになったため」と説明しています。すでに導入していた場合はnpx skills updateで取り除く案内が添えられています。フレームワークの知識を渡す経路が、個別のSkillというオプトイン機構から、AGENTS.mdという既定オンの機構に一本化された変化です。

利用形態別に見る影響

next dev実行時の自動生成は、プロジェクトの構成によって効き方が変わります。

CI環境では自動生成そのものが起きないため、agentRules: falseによるオプトアウトを意識する必要は基本的にありません。むしろ気にする価値があるのは、開発者のローカル環境でマネージドブロックが挿入された結果を、CIで検証する側のAGENTS.mdと食い違わせないことです。ローカルで生成されたファイルをコミットに含めておけば、CI環境でも同じAGENTS.mdをエージェントが参照できます。

隣接するMCPサーバーとの役割分担

AGENTS.mdの自動生成はコード規約とAPIの静的な知識を渡す仕組みですが、実行中の開発サーバーの状態(ビルドエラー・ルート情報・コンパイル結果)は別の経路で渡されます。next-devtools-mcpというMCPサーバー(Next.js 16以上が必要)をプロジェクトの.mcp.jsonに登録すると、この経路が開きます。next dev起動中のアプリケーションから、ビルドエラーの検出・ページのルート情報・Server Actionsの実行結果をエージェントが直接取得できます。AGENTS.mdが「何を知っておくべきか」という静的な知識を担い、MCPサーバーが「今何が起きているか」という実行時の状態を担う、という役割分担です。両者は同じnext dev起動を前提にしていますが、設定ファイルも取得経路も別で、片方を有効にしてももう片方は自動的には動きません。

まとめ

Next.js 16.3以降は、next devの起動時にAIエージェントの存在を検知すると、AGENTS.mdとCLAUDE.mdをマネージドブロックとして自動生成・アップサートします。AGENTS.mdには同梱ドキュメントへの案内とモノレポでの注意が書かれ、CLAUDE.mdは@AGENTS.mdを読み込むだけの1行になります。16.2以前のプロジェクトはcodemodや手動生成が必要ですが、16.3以降にアップグレードすれば次回のnext dev起動で追随します。自動化自体を止めたいときはagentRules: falseで明示的にオプトアウトできます。Claude Codeを使う開発者にとっては、生成されたCLAUDE.mdがそのまま起動時のコンテキストに載る形になるため、AGENTS.mdのマネージドブロックの外側に何を書き足すかが、実質的なチューニングの余地になります。