vercel/next.js / docs / 01-app / 02-guides / ai-agents.mdx

---

title: How Next.js supports AI coding agents nav_title: AI Coding Agents description: Learn how Next.js helps AI coding agents use current framework guidance, inspect applications, verify changes, and report issues. related: title: Next Steps description: Learn more about the APIs and tools described in this guide. links: - app/guides/mcp - app/getting-started/upgrading - app/api-reference/config/next-config-js/agentRules - app/api-reference/config/next-config-js/agentFeedback - app/api-reference/config/next-config-js/agentUpgrade

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.

<span id="step-1-point-agents-at-the-bundled-docs" />

Version-matched documentation

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:

node_modules/next/dist/docs/
├── 01-app/
│   ├── 01-getting-started/
│   ├── 02-guides/
│   └── 03-api-reference/
├── 02-pages/
├── 03-architecture/
└── index.mdx

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.

Managed documentation instructions

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:

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

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.

Version support

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:

npx @next/codemod@canary agents-md

Docs over the network

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

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:

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

## Report Next.js feedback

The project owner enabled `experimental.agentFeedback`, authorizing this feedback pass. When enabled, `next dev` writes this block and restores it if removed. Commit `AGENTS.md` with your work to keep the tree clean.

During the current user request, retain anonymized facts as feedback candidates for meaningful or recurring Next.js issues:

- Crashes, hangs, OOMs, or unexpected slowness
- Incorrect behavior, output, errors, or diagnostics
- Missing, unclear, or conflicting documentation
- Unexpected CLI, codemod, Skill, or upgrade behavior and non-obvious workarounds

Continue the current user request without reporting immediately. Routine debugging is not feedback. Verify changes before retaining them as feedback candidates. Never retain code, logs, paths, URLs, secrets, personal information, or project-specific data.

Retain qualifying friction even if it is later fixed or worked around; record the final outcome during the reporting pass.

Before the final response, run one reporting pass. If candidates remain, from this file's directory run `npx --no-install next internal agent-feedback-instructions` once without piping or truncating its output. Follow its output or error guidance. If a network sandbox blocks it, retry with network access; if it still returns no output, continue normally.

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

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.

Agent-guided upgrades

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:

npx next@canary upgrade --agent=latest

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.

<span id="step-2-give-agents-runtime-visibility" />

Runtime visibility

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.

<span id="step-3-let-errors-drive-the-fixes" />

Built-in guidance for errors

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, applying the canonical pattern, and verifying the result at runtime.

The same menu prints in the next dev terminal and in next build output, so an agent reading CI logs sees it too:

Route "/products/[slug]": Next.js encountered uncached data during prerendering.

`fetch(...)` or `connection()` accessed outside of `<Suspense>` prevents the route
from being prerendered, blocking the page load and leading to a slower user experience.

Ways to fix this:
  - [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
  - [cache] Cache the data access with `"use cache"` (does not apply to `connection()`)
  - [block] Set `export const instant = false` to allow a blocking route

Learn more: https://nextjs.org/docs/messages/blocking-prerender-dynamic
    at ProductPage (app/products/[slug]/page.tsx:52:32)
    ...

next dev shows all validation errors with source-mapped stacks in the overlay and terminal. Production builds minify server code and stop after a route fails. Use next build --debug-prerender to enable server source maps and continue checking other routes.

The Learn more link resolves to a per-error page under /docs/messages written for agents to read. Each page follows the same shape, with the canonical patterns for every fix, the trade-offs against the other fixes, and the gotchas an agent is likely to miss on a first attempt. The Instant navigation guide walks through the full loop an agent runs on these errors, from reading the insight to writing an instant() test that fails before the fix and passes once it's in place.

<span id="step-4-hand-multi-step-workflows-to-skills" />

Skills for multi-step workflows

Framework knowledge comes from the bundled docs, not from Skills. Benchmark results show that always-available context outperforms on-demand retrieval. Skills cover the tasks that are workflows rather than lookups, such as adopting Cache Components or Partial Prefetching across an app. Next.js Skills package these as structured instructions an agent installs and follows, sequencing the work and pointing at the relevant docs and runtime tooling along the way.

You can browse the source for these Skills in the Next.js repository and find them on skills.sh.

The Skills serve three different workflow types:

• Runtime foundations such as next-dev-loop give any coding task a repeatable inspect, edit, and verify cycle.
• Interactive workflows make broader changes with user checkpoints, such as adopting Cache Components or Partial Prefetching across an app.
• Unattended loops work toward a verifiable goal and stop only for genuine decisions.

next-dev-loop

The next-dev-loop runtime foundation verifies changes against a running dev server using the MCP server and browser.

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

Then give the agent this prompt:

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

next-bundle-optimizer

The next-bundle-optimizer skill uses Turbopack's bundle analyzer to identify sources of large client-side bundles that impact your site's initial load performance.

npx skills add vercel/next.js --skill next-bundle-optimizer

In audit-only mode, it produces a report without making any changes:

Use the next-bundle-optimizer skill to produce a report of the initial load performance of this site.

You can also tell your agent to fix any issues, and it will optimize your site based on its findings. Or have it focus on a specific route by providing the route in the prompt.

next-cache-components-adoption

The next-cache-components-adoption Skill migrates an app to Cache Components:

1. Turns the flag on and finds the routes that can't prerender.
2. Fixes them one feature at a time, checking in with you before moving on.
3. Confirms a feature against next dev and next build before leaving it.

The Skill supports both a series of pull requests and a single-branch migration.

npx skills add vercel/next.js --skill next-cache-components-adoption

Then give the agent this prompt:

Adopt Cache Components in this project using the next-cache-components-adoption Skill.

next-cache-components-optimizer

The next-cache-components-optimizer Skill expands a target route's static shell to include the useful UI you want available on an initial load:

1. Writes a failing instant() test for the static-shell UI you named.
2. Refactors the route until it passes, often by moving a data read below a <Suspense> boundary.
3. Commits the passing test with the refactoring, so it catches future regressions.

Use it after adopting Cache Components to optimize an initial load or client navigation. To prefetch URL-specific content for an already-instant destination, use the next-partial-prefetching-optimizer instead.

npx skills add vercel/next.js --skill next-cache-components-optimizer

Then give the agent a prompt like:

Optimize the static shell for /dashboard using the next-cache-components-optimizer Skill. On an initial load, the header and project list should be available immediately.

next-partial-prefetching-adoption

The next-partial-prefetching-adoption Skill moves an app onto Partial Prefetching, where links share one App Shell:

1. Audits existing <Link prefetch={true}> navigations and identifies the prefetched UI to preserve.
2. Captures that UI in passing instant() tests before enabling Partial Prefetching, then migrates each destination until the same tests pass unchanged.
3. Enables the flag, resolves the URL-data insights it surfaces, and marks optional per-link prefetching candidates for later.

It needs Cache Components already adopted and a production-like build it can run for prefetch verification.

npx skills add vercel/next.js --skill next-partial-prefetching-adoption

Then give the agent this prompt:

Adopt Partial Prefetching in this project using the next-partial-prefetching-adoption Skill.

next-partial-prefetching-optimizer

The next-partial-prefetching-optimizer Skill takes a target navigation or set of navigations and works toward the UI you want ready before each click:

1. Turns the requested behavior for each navigation into a contract for what is prefetched, what waits for navigation, and when prefetching begins.
2. Captures each contract in an instant() test.
3. Applies the Optimizing prefetching patterns and keeps the passing tests as regression coverage.

It needs Cache Components and Partial Prefetching already adopted.

npx skills add vercel/next.js --skill next-partial-prefetching-optimizer

Then give the agent a prompt like:

Make the product title instant when navigating from /products to /products/[id]. Use the next-partial-prefetching-optimizer Skill.

Version History

Version	Changes
v16.4.0	next-bundle-optimizer skill added.