Next.js 16.3 and AI Agents: Getting AGENTS.md Right

Next.js 16.3 directly addresses AI coding agents' biggest complaint: agents now read documentation matching the Next.js version actually installed in your project. Running next dev automatically writes and maintains an AGENTS.md block that points to this documentation — no setup, no extra tooling. This post covers how the mechanism actually works, how to verify it with tools like Claude Code and Cursor, and where it stops.

💡 Pro Tip: The only requirement for AGENTS.md to be written automatically in an existing project is having Next.js 16.3+ installed and running next dev in a terminal/environment an AI coding agent has started — if no agent is detected, the file is left untouched.

Table of Contents

• The Problem: Why Agents Write Outdated Next.js APIs
• 16.3's Solution: Version-Matched, Bundled Docs
• The AGENTS.md Block next dev Generates and Maintains
• Practical Setup and Verification in Claude Code / Cursor
• Tying the Agent's Suggested Code to Evidence
• Limits: Does Correct Docs Mean No More Hallucination
• How to Measure the Difference in Your Own Project
• FAQ
• What is AGENTS.md and what is it for?
• Why does the AI agent suggest outdated Next.js APIs?
• How do you get Next.js docs delivered to an AI agent in a version-matched way?
• Does version-matched documentation end hallucination?
• Is agentRules: false the same as --no-agents-md?
• Which agents does this automation work with?
• Conclusion
• Sources

The Problem: Why Agents Write Outdated Next.js APIs

AI coding agents' code suggestions rely on knowledge frozen at their training cutoff. In a fast-moving framework like Next.js, this means an agent can confidently suggest an API removed six months ago, a deprecated prop, or a behavior no longer the default. If a project has turned on cacheComponents in next.config.ts or migrated from Edge Runtime to Node.js, the agent may reproduce old patterns without knowing any better — breaking changes like Next.js 16.3's Cache Components and Instant Navigations and the removal of the Edge Runtime amplify exactly this risk.

The Next.js team's solution comes from a simple observation: instead of giving the agent access to current docs over the internet, put the docs directly inside the installed package. Even if the agent doesn't know which version is installed, the docs it reads already match that version.

What sets this apart from earlier solutions is that it shifts responsibility for keeping the docs "alive" from you onto the package manager. Previously this fell either to a manually updated project note or a general-purpose, version-agnostic "knowledge" Skill — both tended to drift out of sync over time. Update the next package with npm install next@latest, and the bundled docs come along automatically — no separate sync step needed.

16.3's Solution: Version-Matched, Bundled Docs

As of Next.js 16.3, installing the next package ships the documentation embedded under node_modules/next/dist/docs/ — a folder tree mirroring the nextjs.org site one-to-one. The agent can access docs matching the installed version without a single network request.

This is the feature Next.js highlighted in its 16.3 announcement under "Versioned docs for AI agents": "AI coding agents now automatically read documentation that matches your project's version of Next.js." This step also retired previously existing Skills whose sole job was fetching current docs for agents — no need to install a separate Skill anymore; the mechanism is built into the framework.

For new projects this is automatic: running create-next-app produces both AGENTS.md and CLAUDE.md files with no extra setup. If you don't want it, you can turn it off with the --no-agents-md flag. The official docs give examples using the @canary tag:

1npx create-next-app@canary
2# AGENTS.md and CLAUDE.md are created automatically
3 
4npx create-next-app@canary --no-agents-md
5# agent files are not created

The AGENTS.md Block next dev Generates and Maintains

In an existing project (without creating a new one), what triggers this automation is next dev itself. When it runs on Next.js 16.3 or later, if an AI coding agent is detected in the environment and there's no managed block yet, Next.js automatically creates or updates AGENTS.md and CLAUDE.md at the project root.

Critical detail: this is an "upsert." The block Next.js manages sits between the markers <!-- BEGIN:nextjs-agent-rules --> and <!-- END:nextjs-agent-rules -->; if the file already exists, only the content between these markers is updated, and everything outside is preserved. So you can keep your own project rules (test commands, folder conventions, deploy notes) in the same file, and Next.js won't overwrite them. The block next dev writes is:

1<!-- BEGIN:nextjs-agent-rules -->
2 
3 # This is NOT the Next.js you know
4 
5This 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.
6 
7This 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.
8 
9<!-- END:nextjs-agent-rules -->

The leading space before the heading line in the block above is only an artifact of this page; there's no space in the actual file.

The block speaks directly to the agent: "this isn't the Next.js you know"; per the official docs, deleting it from a diff doesn't help — next dev adds it right back. On the CLAUDE.md side, the generated content is a single line: @AGENTS.md.

To turn this off entirely, use the agentRules: false setting in next.config.ts — a separate mechanism from create-next-app's --no-agents-md flag, so don't confuse the two: one controls new-project setup, the other controls next dev's automatic writing in an existing project.

1// next.config.ts
2import type { NextConfig } from "next";
3 
4const nextConfig: NextConfig = {
5  agentRules: false, // turns off next dev writing AGENTS.md/CLAUDE.md
6};
7 
8export default nextConfig;

Practical Setup and Verification in Claude Code / Cursor

Per Next.js's official docs, most AI coding agents — including Claude Code, Codex, Cursor, and GitHub Copilot — automatically read the project's AGENTS.md file at the start of a session. No extra "read this file" instruction is needed — the agent finds AGENTS.md on its own and pulls it into context.

In practice, the flow works like this:

1. New project: run create-next-app, and AGENTS.md+CLAUDE.md come automatically.
2. Existing project: upgrade Next.js to 16.3+, then run next dev in a terminal opened by Claude Code or Cursor — the files are added automatically once the agent is detected.
3. Verification: cat AGENTS.md confirms the block arrived; ls node_modules/next/dist/docs/ confirms the bundled docs are installed.

16.3 also introduces a first-party Skill called next-dev-loop, giving the agent live browser access via the framework MCP server (/_next/mcp) and the agent-browser CLI (0.27+) — it can read the console, follow network requests, and inspect the React tree. next-browser, shipped experimentally in 16.2, merged into the general-purpose agent-browser CLI; version 0.27 added React DevTools introspection. In practice the agent can use commands like:

These react commands only work while React DevTools is open — you need to pass --enable react-devtools to the agent-browser open call; the next-dev-loop Skill does this for you.

These commands let the agent answer questions like "why is this component re-rendering" or "which Suspense boundary is stuck pending" without you having to manually open React DevTools. Stable 16.3 ships four first-party Skills in total:

Tying the Agent's Suggested Code to Evidence

Bundled docs raise the odds the agent's suggestion is _correct_, but proving it actually compiles is a separate step. 16.3 adds two new compilation tools to the framework MCP server that shipped with Next.js 16: get_compilation_issues and compile_route. Both report whether the code compiles via the dev server, without a full next build — so a proposed change can be verified much faster than waiting for a complete build.

get_compilation_issues targets the whole project; compile_route targets a single route.

There are two ways to access it. Per the official announcement, Skills like next-dev-loop call the /_next/mcp endpoints directly with no extra setup. In your own agent client, add next-devtools-mcp to .mcp.json; the client finds the running next dev server on its own. Installing the Skill is one command:

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

The official docs' recommended prompt pattern is one sentence:

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

On error, 16.3's error pages kick in: with Cache Components on, a blocking error shows tagged fixes ([stream], [cache], [block]), each a different trade-off, and the dev overlay's "Copy prompt" button packages the fix you pick into a ready-to-paste prompt. The same menu also prints to the next dev terminal and next build output.

The real verification chain is still three steps: the agent writes the suggestion → it passes the MCP/compilation check → you (or CI) confirm it works live. Bundled docs and MCP tools speed up the first two steps; they don't eliminate the third. In practice this means verifying much more often within the dev loop without rerunning next build for every small change — in a large monorepo especially, a single-route check comes back far faster than a full build.

Limits: Does Correct Docs Mean No More Hallucination

Let's be clear here: Next.js's official sources don't claim "hallucination stops entirely." What the official docs actually say is: "Benchmark results on nextjs.org/evals show agents do better when they read the bundled docs" — that's a claim of measurable improvement, not a claim of zero errors.

In practice this means AGENTS.md and bundled docs make it easier for the agent to correctly read the API surface (function names, config keys, default behavior). But it can still get it wrong on architectural decisions, business-logic interpretation, or choosing between valid approaches — fresh docs don't solve that. A step like architectural planning with Plan Mode shouldn't be skipped no matter how fresh the docs are.

In short: bundled docs raise the odds the agent answers "which API exists" correctly; they don't fix reasoning errors around "how should I use this API here."

There's another practical consequence: bundled docs only cover Next.js's own API surface. Third-party libraries, internal services, or team conventions fall outside it — you still need to introduce those separately, either outside your AGENTS.md block or via MCP servers. AGENTS.md alone doesn't guarantee an "agent that knows everything" — it only closes the gap at the framework layer.

How to Measure the Difference in Your Own Project

For a general improvement rate, the reference is the nextjs.org/evals benchmark results — the official docs base the decision to leave automatic generation on precisely on this. But those results come from Next.js's own test set; they don't directly tell you the difference in your codebase.

To measure it in your own project, the most practical method is a small A/B test: temporarily turn off the block with agentRules: false in next.config.ts, give the agent the same task (say, rewriting an API route with a specific cache strategy) with the block off and on, and count how many turns it takes to pass compilation without errors. Use the same prompt, commit, and model in both conditions — otherwise you're measuring a difference in prompts, not the block.

FAQ

What is AGENTS.md and what is it for?

AGENTS.md is an open format at a project's root that gives AI coding agents setup, test, and convention information — think "README for agents." It's used in over 60,000 open-source projects and emerged from a joint effort by tools like OpenAI Codex, Amp, Google Jules, and Cursor. On the Next.js side, 16.2 already had create-next-app point AGENTS.md to the bundled docs for new projects; automatic generation for existing projects arrived in 16.3 via next dev (in 16.2 you had to add the file by hand).

Why does the AI agent suggest outdated Next.js APIs?

Because the agent's training data is frozen at a specific point in time and can't capture the framework's latest APIs. Next.js solves this by embedding version-matched docs under node_modules/next/dist/docs/ alongside the next package, with AGENTS.md pointing the agent directly there — even if the agent doesn't know which version is installed, the docs it reads match that version.

How do you get Next.js docs delivered to an AI agent in a version-matched way?

There are three ways: in a new project, create-next-app generates it automatically; in an existing project, when next dev runs on 16.3+ and an agent is detected in the environment, it's added and updated automatically; and for tools that want to access it over the network, adding .md to any docs page or sending an Accept: text/markdown header returns the Markdown version.

Does version-matched documentation end hallucination?

Not entirely — it reduces it. Per Next.js's own measurements, agents perform "better" when they read the bundled docs, backed by benchmark results at nextjs.org/evals — but that's a claim of measurable improvement, not "zero errors." Architectural decisions and business-logic interpretation still depend on the agent's own reasoning.

Is agentRules: false the same as --no-agents-md?

No, they're two separate mechanisms. --no-agents-md is a flag that prevents the files from being created at all when setting up a new project with create-next-app. agentRules: false lives in next.config.ts and turns off next dev's automatic writing/updating of AGENTS.md/CLAUDE.md in an existing project.

Which agents does this automation work with?

According to Next.js's official docs, most AI coding agents — including Claude Code, Codex, Cursor, and GitHub Copilot — automatically read the project's AGENTS.md file at the start of a session, with no extra instruction needed from you.

Conclusion

Next.js 16.3's AGENTS.md automation shrinks the "agent suggests outdated APIs" problem — not at the root, but in a practical, measurable way: docs now ship with the installed version, next dev wires that to a file for you, and the agent already reads it automatically. Add Next.js 16.3's other major changes, like Cache Components and Instant Navigations and the migration from Edge Runtime to Node.js, and it gets that much easier for the agent to talk to your project's actual current state.

If you want to see the broader foundation this mechanism sits on, check out our MCP (Model Context Protocol) guide and MCP's place in general AI integration; I covered which Skill/MCP/hook combination to pick and when in this comparison. But remember: correct docs don't replace the right architectural decision — that step still needs a stop like Plan Mode.

Sources

• Next.js 16.3 — official announcement — the primary source for the "Versioned docs for AI agents" feature and for next dev writing the AGENTS.md block.
• Next.js 16.3 AI improvements — details on first-party Skills, Agent Browser, the trimmed-down MCP server, and docs-as-Markdown.
• Next.js — AI Agents guide — official documentation of the bundled docs path, create-next-app behavior, the agentRules opt-out, and the framework MCP tools.
• agents.md — official format spec — definition of the AGENTS.md format, the "nearest file wins" rule, and the ecosystem's origin.
• npm registry — next package — version/date verification (as of September 23, 2026, latest is 16.3.6; 16.4 is canary-only).