How Next.js supports AI coding agents

AI coding agents may rely on training data that predates the Next.js version installed in a project. To help agents use current APIs and verify their work, Next.js provides and evaluates version-matched documentation, managed project instructions, agent-guided upgrades, runtime tools, structured errors, reusable Skills, and optional agent feedback. See the results in the Next.js agent evaluations.
For more background, read about the AI tooling introduced in Next.js 16.2 and Next.js 16.3.
Next.js 16.2 and later include documentation that matches the installed framework version. The documentation is available at node_modules/next/dist/docs/ and mirrors the structure of the Next.js documentation site:
The bundled copy gives coding agents access to the APIs and patterns supported by the project without a network request or external lookup. Upgrading Next.js also updates the bundled documentation.
Next.js makes the bundled documentation discoverable through managed instructions in AGENTS.md at the project root. Coding agents such as Claude Code, Codex, Cursor, and GitHub Copilot read this file when they start a session.
create-next-app creates the agent files for new projects. When next dev detects a coding agent, it creates or updates the managed instructions for existing projects. The block directs the agent to the documentation installed with the project:
Next.js updates only the content between the agent rules markers and preserves the rest of AGENTS.md.
Research comparing AGENTS.md with knowledge Skills found a 100% pass rate with bundled documentation, compared with up to 79% for Skill-based approaches. See the current Next.js agent evaluation results.
Managed documentation instructions are enabled by default in Next.js 16.3 and later. See the agentRules API reference to configure or disable them.
Next.js 16.3 and later include bundled documentation and support managed agent instructions. Next.js 16.2 includes the bundled documentation but does not generate instructions automatically.
Next.js 16.1 and earlier do not include the bundled documentation. The legacy agents-md command downloads a version-matched copy to .next-docs/ and indexes it in AGENTS.md:
The Next.js documentation is also available as Markdown over the network for agents that fetch pages instead of reading node_modules. Every page on nextjs.org/docs has a plain Markdown version at its .md URL, and clients that send an Accept: text/markdown header receive Markdown. This includes the per-error pages under /docs/messages, which are not bundled.
The index at /docs/llms.txt and the single-file /docs/llms-full.txt follow the llms.txt convention, so agents that already read llms.txt for other tools can discover the Next.js docs the same way.
Automatic agent feedback lets coding agents keep track of potential Next.js issues without interrupting the current user request. Before the final response, the agent evaluates those issues and opens each qualifying report in a separate review form in your default browser.
Before opening a form, the agent attempts to anonymize the report by replacing customer and project details with generic descriptions and omitting source code, logs, paths, URLs, secrets, and personal information. Review the draft and remove anything you don't want to include. Nothing is sent until you select Send feedback.
With the option enabled, next dev adds the following managed feedback instructions to the agent file when it detects an AI coding agent:
Next.js updates only the content between the agent feedback markers and preserves the rest of the file.
Automatic agent feedback is experimental, disabled by default, and available only when Next.js Telemetry is enabled. It does not run in CI. See the agentFeedback API reference to enable it.
next upgrade --agent checks for an available upgrade, gathers the version-matched migration guides, and hands the task to a coding agent. The agent applies the changes and verifies the app:
The experimental agentUpgrade option shows security upgrade reminders during next dev and next build by default. See Upgrade with a coding agent for the available policies and workflow.
Agents need both framework and browser state to verify a running application. Next.js and its supporting tools expose these complementary views as structured text.
First, next dev forwards browser console errors and warnings to the terminal (the logging.browserToTerminal config), so the output agents already read carries the client-side failures they're asked to fix.
next dev also writes its PID, port, and URL to .next/dev/lock. If you run next dev while another development server is already running for the project, the command prints the existing server's URL and PID, along with a command to stop it. Continue with the existing server when possible to avoid interrupting the active development session.
The framework's view comes from the Next.js MCP server at /_next/mcp, which exposes the running dev server's routes, server logs, and compilation issues. Its get_compilation_issues and compile_route tools report whether the code compiles straight from the dev server, so an agent doesn't have to run a full next build to find out.
The next-dev-loop skill adds the browser's view through agent-browser, a CLI that exposes the DOM, console, network, and Web Vitals as structured text. The Skill opens agent-browser with React DevTools enabled, which also exposes the component tree and pending Suspense boundaries. An agent can run a command such as react tree and use the structured output to decide what to inspect next.
Together with the Next.js MCP server, next-dev-loop combines the framework's and the browser's perspectives into one edit-and-verify loop.
With Cache Components enabled, a blocking error presents labeled fixes, each making a different trade-off. The dev overlay adds a Copy prompt button that packages the chosen fix into a paste-ready prompt. The prompt walks the agent through reading the matching error page