AGENTS.md in Next.js 16.3: Teach AI Agents Your Codebase

Ask an AI coding agent to add caching to a Next.js 16 page and watch what it writes. There's a good chance it reaches for patterns from older versions, because the model learned Next.js before 'use cache', proxy.ts or updateTag existed. The code looks confident. It just targets a framework you're no longer running.

Next.js 16.3 attacks this problem at the source. Run next dev in a project where a coding agent is working, and Next.js writes an AGENTS.md file. That file tells the agent to read documentation matching your installed version (Next.js 16.3 release post). That covers the framework. It doesn't cover your project: your scripts, your folders, your rules about the database.

This post explains what Next.js now generates, why a plain Markdown file works better than smarter tooling, and how to write the part only you can write. You'll leave with a complete AGENTS.md for a Next.js, Prisma and Tailwind app that you can adapt in ten minutes.

Key takeaways

• On Next.js 16.3, next dev writes and maintains a block in AGENTS.md that points agents to docs bundled in node_modules/next/dist/docs/.

• In Vercel's evals, an always-loaded AGENTS.md docs index passed 100% of tasks. A docs skill reached 79%, and only with explicit instructions.

• Anything you write outside the Next.js markers is preserved, so that's where your commands, project map, conventions and boundaries go.

• Short, specific, checkable rules beat long, vague ones. Define what "done" means.

• Pair the file with the dev server's MCP endpoint so the agent can check its own work.

What Next.js 16.3 writes into AGENTS.md

AGENTS.md is a Markdown file at your project root that coding agents read at the start of a session (agents.md). According to the Next.js guide, Claude Code, Codex, Cursor and GitHub Copilot all pick it up automatically (Next.js AI coding agents guide).

Since version 16.2, the next package ships its full documentation as Markdown inside node_modules/next/dist/docs/ (Next.js 16.2 AI improvements). In 16.3, when next dev detects a coding agent and finds no managed block, it creates AGENTS.md and CLAUDE.md for you. If the files already exist, it inserts its block and leaves the rest untouched. The managed block is the section between two HTML comment markers that Next.js owns and rewrites. It looks like this:

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

# This is NOT the Next.js you know

(shortened) Read the relevant guide in `node_modules/next/dist/docs/`
before writing any code. Heed deprecation notices.

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

The real block is a little longer. It also warns that APIs and file structure may differ from the model's training data, and explains how to find the docs in a monorepo. You can read the full text in the Next.js AI coding agents guide.

The CLAUDE.md file contains a single line, @AGENTS.md, which tells Claude Code to load the same instructions. One file, every agent.

How you get the file depends on your version:

• Next.js 16.3 and later: run next dev. New apps from create-next-app get both files from the start.

• Next.js 16.2: the docs are bundled, but you write AGENTS.md yourself with an instruction to read node_modules/next/dist/docs/ first.

• Next.js 16.1 and earlier: run npx @next/codemod@canary agents-md, which downloads version-matched docs into .next-docs/ and indexes them in AGENTS.md.

If you really don't want the file, set agentRules: false in next.config.ts. The Next.js team recommends leaving it on, and the next section shows why.

Why a plain Markdown file beats smarter tooling

In January 2026, Vercel tested two ways of teaching agents about Next.js 16 APIs that models hadn't seen in training, such as 'use cache', connection() and forbidden() (Vercel agent evals). One was a skill. A skill is a package of instructions and docs, defined by an open standard, that an agent loads only when it decides it needs them. The other was a small docs index placed directly in AGENTS.md, present on every turn.

The results were lopsided. With no docs, agents passed 53% of the tasks. Adding the skill changed nothing, because in 56% of cases the agent never invoked it. Explicit instructions to use the skill raised the pass rate to 79%, but small changes in wording swung the results. The AGENTS.md index passed 100% across build, lint and test.

Vercel's explanation is simple. An always-loaded file removes the decision. The agent never has to ask itself whether to look something up, and it never has to choose between reading docs first or exploring the project first.

One caveat keeps this honest. That eval tested the codemod's compressed docs index, which is the approach 16.1 users still get. The 16.3 managed block is shorter and points at the bundled docs instead, and the Next.js team has since retired its docs skills in favor of it (Next.js 16.3 AI improvements). The principle carried over: framework knowledge belongs in context that's always there.

The half Next.js can't write for you

The managed block solves one problem: the agent's knowledge of Next.js is out of date. It says nothing about your codebase. The agent still doesn't know your package manager, where database code lives, which folder holds shared components, or which files it must never touch.

The Next.js guide is explicit that anything you write outside the BEGIN and END markers is preserved when Next.js updates its block. So the file has two owners. Next.js keeps the framework section current, and you own everything below it. I use five sections:

1. Commands. Exact scripts for install, dev, checks, tests and build.

2. Stack. One line naming the main tools and versions.

3. Project map. Where things live, and where they must not.

4. Conventions. The patterns a reviewer would flag.

5. Boundaries and done. What needs permission, what's forbidden, and how the agent proves it finished.

A complete AGENTS.md for a Next.js, Prisma and Tailwind app

Here's what that looks like for an e-commerce app. Swap in your own scripts and paths. The managed block stays at the top, exactly as next dev wrote it.

<!-- BEGIN:nextjs-agent-rules -->
(written by next dev, leave as is)
<!-- END:nextjs-agent-rules -->

# Storefront

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`. If a dev server is already running, use it.
- Check: `pnpm typecheck && pnpm lint`
- Test: `pnpm test` (Vitest) and `pnpm test:e2e` (Playwright)
- Build: `pnpm build`

## Stack
Next.js 16.3 App Router, React 19, TypeScript (strict), Prisma with
PostgreSQL, Tailwind CSS v4.

## Project map
- `app/`: routes. Pages stay thin: load data from `lib/data`, render components.
- `lib/data/*.ts`: all database access. Nothing else imports `@/lib/prisma`.
- `components/ui/`: shared primitives. Check here before creating a new one.
- `app/globals.css`: Tailwind theme tokens. No raw hex colors in components.

## Conventions
- Server Components by default. Add 'use client' only for state, effects
  or browser APIs.
- Every 'use cache' function sets cacheLife and cacheTag.
- Mutations are Server Actions in `actions.ts` beside the route, and call
  updateTag for every tag they affect.
- Prices are stored as integers in kobo. Format with `formatNaira()`
  from `lib/format.ts`.

## Boundaries
- Never edit files in `prisma/migrations/`. Create a new migration.
- Never read or write `.env*` files.
- Ask before adding a dependency or changing `next.config.ts`.

## Done means
- `pnpm typecheck`, `pnpm lint` and `pnpm build` all pass.
- The changed route renders in `next dev` with no errors in the terminal.

A few lines deserve a comment. The caching rule encodes the pattern from my guide to use cache in Next.js 16, so the agent doesn't cache a query and forget to tag it. The kobo rule is the kind of thing no model can guess, and getting it wrong means showing prices 100 times too high. And the Done means section turns "make sure it works" into commands the agent can actually run.

How to write rules an agent will follow

An agent treats AGENTS.md as instructions, so the writing matters as much as the content. These rules come from the Vercel eval findings and the Next.js guide.

INSERT IMAGE: agents-md-specific-1600x900.png | alt: A comparison of vague AGENTS.md rules, such as write clean code, with specific ones the agent can check, such as run pnpm typecheck and lint before finishing.

Keep it short. Vercel compressed its docs index from about 40KB to 8KB and kept the 100% pass rate. Everything in this file is read on every turn, so every line should earn its place.

Point, don't paste. Don't copy framework docs into the file. Point to where the answer lives, whether that's the bundled docs, a folder in your repo or an internal guide. The agent reads the file when it needs it.

Make every rule checkable. "Write clean code" gives the agent nothing to test against. "Run pnpm typecheck && pnpm lint before finishing" does. If you can't tell whether a rule was followed by looking at the diff or running a command, rewrite it.

Write boundaries as never and ask first. Agents follow clear prohibitions better than soft preferences. Separate the things that are forbidden from the things that just need your approval.

Add a line every time the agent repeats a mistake. Treat the file like a change log of lessons. If you correct the same thing twice, it belongs in AGENTS.md.

Give the agent a way to check its own work

Docs tell an agent what to write. They don't tell it whether the code worked, because runtime errors, hydration warnings and rendered output live in a browser the agent can't see. Next.js 16.3 closes that gap with tools an agent reads from the terminal (Next.js AI coding agents guide):

• Browser errors in the terminal. next dev forwards browser console errors and warnings to the terminal output the agent already reads.

• The dev server's MCP endpoint. The Next.js MCP server at /_next/mcp exposes routes, server logs and compilation issues, so the agent can confirm the code compiles without running a full build.

• Errors with labeled fixes. With Cache Components on, blocking errors list options like [stream], [cache] and [block], each linking to an error page written for agents.

The next-dev-loop skill ties these into one edit-and-verify cycle. This is the case where skills do make sense: a multi-step workflow, not a knowledge lookup.

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

Then add one line to your Done means section: "After every edit, verify the page at runtime using the next-dev-loop skill."

The labeled fixes also map directly to the choices in my post on instant navigations in Next.js 16.3, so an agent working on those routes has the same options you would.

Test whether your AGENTS.md works

You don't need Vercel's eval suite to know if your file helps. Run a small version of the same experiment:

1. Pick three tasks that touch your conventions, such as adding a cached data function, a Server Action that updates a price, and a new component.

2. Run each task on a clean branch with your AGENTS.md, then again with it temporarily renamed.

3. Score each run the way Vercel did: does it build, does it lint, do the tests pass. Then add one check of your own: did it follow your conventions?

If both runs score the same, your rules aren't specific enough or they're buried. Move the most important ones to the top and make them checkable.

Frequently asked questions

Should I commit the block that next dev writes?

Yes. The generated block itself says so: next dev re-adds it if you remove it, so deleting it from a diff only brings the change back. Committing it keeps your working tree clean, and your whole team's agents get the same instructions.

Should I use AGENTS.md or CLAUDE.md?

Write your instructions in AGENTS.md, which most agents read. Keep CLAUDE.md as the one-line @AGENTS.md import that Next.js generates, so Claude Code loads the same file. That way you maintain one set of rules.

Does this work with Cursor, Copilot and Codex?

Yes. The Next.js guide lists Claude Code, Codex, Cursor and GitHub Copilot as agents that read AGENTS.md automatically when a session starts. For agents that fetch pages instead of reading node_modules, every Next.js docs page is also available as Markdown by adding .md to its URL.

Ten minutes that pay off on every task

Next.js now handles the hardest part, keeping the agent current on the framework. What's left is the part that makes your codebase yours. Upgrade to 16.3, run next dev, and write your five sections under the managed block: commands, stack, project map, conventions, and boundaries with a clear definition of done.

Then give your agent a real task and see how it does. If you want something to try it on, ask it to add page transitions with React's ViewTransition and check whether it follows your rules.