Next.jsのAGENTS.mdが自動生成される仕組みとブロックの意味

Next.jsはnextパッケージの中にバージョンに対応したドキュメント一式を同梱しており、プロジェクトルートのAGENTS.mdがその入口として機能します。AIコーディングエージェントは訓練データではなく、この同梱ドキュメントを読みに行きます。

インストール済みのバージョンに一致するドキュメントをネットワークアクセスなしに参照でき、Next.jsをアップグレードすれば同梱ドキュメントも一緒に更新されます。Claude Code・Codex・Cursor・GitHub Copilotなど主要なエージェントの多くは、セッション開始時にAGENTS.mdを自動で読み込みます。

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

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

next devが書き込むのは、次の4段階を経た結果です。

挿入されるブロックの全文は、公式ガイドで次のとおり示されています。見出しの階層は、公式ブログでは#、ガイドと生成コードでは##と食い違っており、実際に書き込まれるのは##です。

<!-- 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 -->

「This is NOT the Next.js you know」のブロックは何を指示しているか

この見出しは、AGENTS.mdを新しく作った場合はファイルの先頭に、既存のAGENTS.mdではマーカーが無ければ末尾に追記されます。読み手は人間ではなくAIコーディングエージェントで、ブロックは4つの指示でできています。

• 訓練データと違う前提で書く: APIや規約、ファイル構成が学習時点から変わっていると警告しています
• 読む場所を示す: コードを書く前にnode_modules/next/dist/docs/の該当ガイドを読ませます
• モノレポに触れる: 場所はAGENTS.mdのあるディレクトリから解決され、ルートからnextが見えない構成もあると断っています
• コミットを促す: 差分から消してもnext devが書き戻すので、作業と一緒にコミットする前提です

BEGIN:nextjs-agent-rulesとEND:nextjs-agent-rulesの2つのコメントが境界で、nextjs-agent-rulesが識別子です。この間はnext devが書き直す領域になり、手で編集しても次の起動で戻ります。

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

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

16.2で作った既存プロジェクトを16.3以降にアップグレードした場合は、エージェントがいる環境でnext devを起動した時点でマネージドブロックが挿入されます。手動でcodemodを再実行する必要はありません。16.2のまま手書きでAGENTS.mdを用意する場合は、node_modules/next/dist/docs/を書く前に読む指示を自分で入れます。

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

新規プロジェクトでは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 devが書き、必要なら再び加えます。編集はマーカーの外で行うのが前提です。

オプトアウトとモノレポ

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

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

モノレポについては、ブロック自体が注意を含んでいます。node_modules/next/dist/docs/はAGENTS.mdのあるディレクトリから解決される経路で、リポジトリのルートからnextパッケージが見えないことがある、という内容です。パッケージごとにnextを入れる構成では、ルートのAGENTS.mdが指す相対パスと、エージェントが実際に読めるnode_modulesの位置がずれることがあります。複数のCLAUDE.md階層を使い分ける設定はclaudeMdExcludesの設定手順が扱っています。

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

Claude Codeは、CLAUDE.mdに書いた@path/to/importの記法でファイルを読み込みます。作業ディレクトリの外を指すインポートだけが外部インポートとして扱われ、最初に承認ダイアログが出ます。Next.jsが生成する@AGENTS.mdは同じディレクトリのファイルなので、ダイアログは出ません。

AGENTS.mdを直接読む機能は、Claude Code v2.1.277で入りました。既定の挙動は、リポジトリにあるファイルの組み合わせで決まります。

Next.js 16.3以降のプロジェクトは3行目に当たります。next devがCLAUDE.mdごと生成するので、「CLAUDE.mdが無いときだけAGENTS.mdを読む」経路は使われず、通常のCLAUDE.md読み込みでAGENTS.mdの中身が届きます。

v2.1.281より前は、Amazon Bedrockやテレメトリー無効のセッションなどでCLAUDE.mdしか読まれませんでした。Next.jsの生成物は@AGENTS.mdのインポート経由で届くので、この差の影響を受けません。

つまずきやすいのはCLAUDE.local.mdです。個人用の未コミット指示を置こうとCLAUDE.local.mdを足すと、AGENTS.mdだけに頼るプロジェクトではAGENTS.mdが読まれなくなります。Next.jsの生成物ならCLAUDE.mdが@AGENTS.mdを取り込むのでこの影響を受けませんが、CLAUDE.mdを消した状態でCLAUDE.local.mdだけを置くと同じ状態になります。両方を読ませたいときは、/configのProject instructionsをclaude-md-and-agents-mdにします。

v2.1.287のclaude --helpにある--agentsは、カスタムエージェントをJSONで定義するオプションで、AGENTS.mdとは別物です。読み込むファイルの切り替えは/configか、pluginConfigsで行います。pluginConfigsが有効なのはユーザー設定・--settings・管理設定で、プロジェクトとローカルの設定ファイルに書いても無視されます。

読み込まれたAGENTS.mdは、対話セッションならno CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.mdのような1行が会話に出て分かります。この表示は、CLAUDE.mdが無くAGENTS.mdを直接読んだときのものです。

AGENTS.mdを複数のAIコーディングツールの共通の一次情報源にしたいチームには、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の規約に沿っています。エラーごとのページ(/docs/messages配下)は同梱されないので、この経路でしか読めません。

既定でオンにしている理由とSkillsの扱い

自動生成を既定でオンにしている根拠は、nextjs.org/evalsのベンチマークです。同梱ドキュメントを読ませたエージェントのほうが良い成績を出す、という結果が挙げられています。

Skillsとの関係も変わりました。16.3のブログによれば、App Routerの規約やキャッシュAPIを扱っていた旧来の知識系Skillsは、マネージドブロックで同梱ドキュメントが届くようになったため廃止されます。導入済みならnpx skills updateで取り除く案内です。

その一方で、手順を踏む仕事向けのSkillsは残り、16.3で3つ追加されています。公式ガイドの区分では、フレームワークの知識は同梱ドキュメントから、検索ではなく常に手元にある文脈として渡し、Skillsは「調べる」ではなく「進める」仕事を担当します。知識の入口がAGENTS.mdの既定オン機構に一本化され、Skillsは作業の段取りに絞られた形です。

AGENTS.mdと開発サーバーの情報の役割分担

静的な知識と、実行中のアプリの状態は、別の経路で渡されます。

エージェントがnext buildを回して確かめていたコンパイルの可否を、動いている開発サーバーに直接尋ねる形です。MCPを自前のクライアントから使うときは、next-devtools-mcpを.mcp.jsonに追加します。クライアントは動作中のnext devを自動で見つけます。next-dev-loopのようなSkillsは同じエンドポイントを直接呼ぶので、追加の設定がいりません。Claude CodeからこのMCPを使う手順はNext.js MCPサーバーとClaude Codeの連携にあります。

next devは自分のPID・ポート・URLを.next/dev/lockにも書きます。2つ目のnext devを起動すると、動作中のサーバーのURLと止めるべきPIDが表示されます。

next devは、ブラウザーのコンソールのエラーと警告も端末に転送します(logging.browserToTerminal)。エージェントが普段読む出力に、クライアント側の失敗が混ざる仕組みです。

利用形態別に見る影響

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

この構成ではagentRules: falseを気にする場面は多くありません。ローカルで生成されたブロックをそのままコミットしておけば、チーム全員が同じAGENTS.mdを使えます。

まとめ

Next.js 16.3以降は、エージェントのいる環境でnext devを起動するとAGENTS.mdとCLAUDE.mdが自動で整います。Claude CodeではCLAUDE.mdが@AGENTS.mdを取り込むので、自分の指示はマーカーの外に書けば更新で消えません。個人用にCLAUDE.local.mdを足すときと、モノレポでnextが見えない構成のときは、読み込み経路を一度見直す価値があります。