Next.js 16.3で入ったAGENTS.md自動生成を実際に検証する

はじめに

Next.js 16.3で、next devがAIコーディングエージェント向けにAGENTS.md/CLAUDE.mdを自動生成・自動更新する仕組みが入りました。公式ドキュメントを読むと、これは16.2で入った「バージョン対応ドキュメントの同梱」の上に乗っている機能だと分かります。せっかくなので手元でプロジェクトを作り、next devを実際に動かして挙動を確認してみます。

16.2と16.3、何が違うのか

ドキュメントを読む限り、バージョンごとの対応は以下のように整理できます。

バージョン	バンドルされたドキュメント（node_modules/next/dist/docs/）	AGENTS.mdの自動生成・自動更新
16.1以前	なし（npx @next/codemod@canary agents-mdで別途取得）	なし
16.2	あり	なし（自分でAGENTS.mdに「バンドル済みドキュメントを読んでください」と書く必要がある）
16.3〜	あり	あり（next devがAIエージェントの存在を検知し、管理用ブロックを自動生成・更新する）

つまり「コメントが自動で付く」動きが入ったのは16.3からです。16.2はあくまで「インストールしたNext.jsのバージョンに対応するドキュメントがnode_modules直下に同梱されるようになった」というステップで、AGENTS.mdへの書き込みはまだ自動化されていません。

執筆時点（2026年8月）でnpm view next dist-tagsを見るとlatestはすでに16.3.0なので、この機能はcanary限定ではなく安定版に入っています。

$ npm view next dist-tags
{
  ...
  latest: '16.3.0',
  canary: '16.3.1-canary.11'
}

実際に手を動かして確認する

1. create-next-appで新規プロジェクトを作る

npx create-next-app@canary . --typescript --eslint --app --no-src-dir --use-npm --no-tailwind

実行すると、オプションを省略した項目のデフォルト値が表示されます。--agents-mdがデフォルトで有効になっていることが分かります。

Using defaults for unprovided options:

  --ts                    TypeScript (use --js for JavaScript)
  --no-react-compiler     No React Compiler (use --react-compiler for React Compiler)
  --no-src-dir            No src/ directory (use --src-dir for src/ directory)
  --agents-md             AGENTS.md (use --no-agents-md for No AGENTS.md)

インストール後、プロジェクト直下にAGENTS.mdとCLAUDE.mdが生成されていました。

$ ls
AGENTS.md  CLAUDE.md  README.md  app  next-env.d.ts  next.config.ts  node_modules  package-lock.json  package.json  public  tsconfig.json

2. 生成された中身

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

CLAUDE.mdは1行だけで、Claude Code独自の@ファイル参照記法でAGENTS.mdを読み込ませているだけでした。

CLAUDE.md

@AGENTS.md

内容自体は「このバージョンは学習データと違うから、コードを書く前にnode_modules/next/dist/docs/を読んでくださいね」という指示で、目新しいことは書かれていません。ポイントは中身より <!-- BEGIN:nextjs-agent-rules -->〜<!-- END:nextjs-agent-rules -->というマーカーで囲まれている
ことで、ここが自動更新の対象になります。

3. 仕組みを覗く

コメントに書かれている通り、node_modules/next/dist/server/lib/generate-agent-files.jsが生成ロジック本体でした。読んでみると、動作はシンプルで、

• AGENTS.md・CLAUDE.mdのどちらかに<!-- BEGIN:nextjs-agent-rules -->が含まれているかを見て、あればupsertFile()でブロックだけを最新の内容に置き換えます
• どちらのファイルも存在しなければ、両方を新規作成します
• 呼び出し元（app-info-log.js）では、まず@vercel/detect-agentというパッケージで実行環境がAIコーディングエージェント（CLAUDECODEなどの環境変数で判定していると思われる）かどうかを調べ、エージェントでなければ何もしません
• 既に最新のブロックが入っていれば（hasCurrentAgentRules()）、これもスキップします

というだけの、わりと素直な作りでした。人間だけで開発している環境では発火しない設計になっています。

4. マネージドブロックの外に書いた内容は保持されるか

一番気になったのは「独自のプロジェクトルールをAGENTS.mdに書き足していたら、next devのたびに上書きされて消えるのでは」という点です。これを実際に確かめてみます。

まず、ブロックの中身を古い内容に書き換え、マーカーの外に自分用のルールを追記した状態を作ります。

AGENTS.md（next dev実行前）

<!-- BEGIN:nextjs-agent-rules -->

# This is NOT the Next.js you know

This version has breaking changes.

<!-- END:nextjs-agent-rules -->

# プロジェクト固有のルール
- コミットメッセージは日本語で書くこと
- テストは必ず `npm test` で通すこと

この状態でnext devを起動すると、ターミナルに以下が出力されました。

✓ Generated AGENTS.md for AI agents. Set `agentRules: false` in next.config to disable.

起動後、AGENTS.mdを確認すると次のようになっていました。

AGENTS.md（next dev実行後）

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

# プロジェクト固有のルール
- コミットメッセージは日本語で書くこと
- テストは必ず `npm test` で通すこと

マーカーの中身だけが最新のテキストに更新され、マーカーの外に書いた「プロジェクト固有のルール」はそのまま残っていました。実装（upsertAgentRulesBlock）を見ると、既存ファイルの中からマーカー区間だけを文字列置換しているだけなので、この挙動は狙って作られたものだと分かります。

5. 無効化したい場合

自動生成が不要なら、next.config.tsでagentRules: falseを指定すればよいです。

next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  agentRules: false,
};

export default nextConfig;

実際にこの設定を入れた状態でAGENTS.mdを削除してからnext devを実行したところ、ファイルは生成されませんでした。

この機能が解決したい問題

Next.jsはApp Router移行やCache Componentsなど、短いスパンでAPIや推奨パターンが変わります。LLMの学習データは基本的に古い時点のスナップショットなので、エージェントに実装を任せると「もう非推奨になったAPI」を平気で書いてくることがあります。

この機能は、

• インストール済みのNext.jsバージョンに一致するドキュメントをnode_modulesに同梱します（ネットワークアクセス不要）
• そのドキュメントを読むよう、エージェントが自動で読み込むファイル（AGENTS.md / CLAUDE.md）に指示を書いておきます

という2段構えで、「学習データではなく手元のバージョンのドキュメントを読ませる」ことを狙っています。公式はnextjs.org/evalsでベンチマーク結果も公開しており、これを根拠に「基本はオンのままにしておくのがおすすめ」というスタンスを取っています。

実務で気をつけたいポイント

• コミットするかどうか: コメント内に「diffから消してもnext devがまた作るだけなので、コミットしてツリーをきれいに保て」と明記されています。中身は毎回同じなので気にせずコミットしてよさそうです。
• モノレポでの注意: コメントにも書かれている通り、モノレポ構成だとリポジトリルートからnextパッケージが見えないことがあります。node_modules/next/dist/docs/への相対パスは「このファイルのディレクトリを起点に解決する」前提になっているので、AGENTS.mdの配置場所には注意が必要です。
• 勝手にファイルが増える心配は薄い: 生成トリガーがAIエージェント検知とセットになっているので、人間だけで作業している分には発火しません。

さいごに

AGENTS.mdの自動生成は、16.2の「バージョン対応ドキュメントの同梱」があってはじめて成立する機能で、16.3でnext devがそれを指すAGENTS.md/CLAUDE.mdを自動生成・自動更新するようになった、という2段階の変更でした。

実際に動かしてみると、マネージドブロックとユーザー独自の記述をきれいに分離する設計になっていて、上書き等は発生しないようになっていました。フレームワークのアップデートが速く、学習データとのズレが大きくなりがちなNext.jsだからこそ効いてくる仕組みだと感じました。