Next.js 16 Writes Your AGENTS.md Now. Here's What to Put Around It.

By VibeBoot · 2026-10-27

Short on time? The SaaS Starter already has this wired up: $49 one-time, 14-day money-back guarantee.

Start next dev on Next.js 16.3 or later with a coding agent running, and you may see a change to AGENTS.md that you didn't make. Next.js wrote it. This post covers what that block is, what Next.js will and won't touch, and what you should still write yourself.

Checked on Oct 27, 2026 against the Next.js AI agents guide, the agentRules reference, the Next.js 16.3 AI improvements post, and the source of generate-agent-files.js in Next.js 16.4.3.

What Next.js writes

When next dev detects an AI coding agent and the markers aren't already in the file, it adds this block to AGENTS.md at the project root. If there's no AGENTS.md, it creates one.

<!-- 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/
(...) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev (...)

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

(Lines wrapped and shortened here. The real block is a few long lines.) It points the agent at the docs that ship inside your installed next package, so it reads docs for your exact version instead of relying on its training data. According to the docs, Next.js 16.2 bundles the docs but doesn't write the block. Next.js 16.3 and later write it by default.

The rules of the block

Only the part between the markers is managed. Next.js updates the content between BEGIN:nextjs-agent-rules and END:nextjs-agent-rules and keeps the rest of the file. In 16.4.3, if the markers are missing, the block is added to the end of your existing file.
Commit it. The docs say to commit the block as-is. Delete it and next dev adds it back, so it just shows up as an uncommitted change again.
Opting out. Set agentRules: false in next.config.ts. Since 16.4.0, the next next dev run then removes the existing block.
Older versions. On 16.1 or earlier there's no bundled docs folder. The npx @next/codemod@canary agents-md codemod downloads a version-matched copy instead.
New projects. create-next-app writes the agent files unless you pass --no-agents-md.

What the block doesn't tell your agent

The block tells your agent how to find the Next.js docs. It says nothing about your project. An AGENTS.md that's only the managed block leaves the agent guessing at everything that actually breaks apps:

Your stack and versions. "Next.js 16.4.3, App Router, src/, TypeScript strict, Auth.js v5, Prisma, Stripe." Agents make version mistakes all the time: they write middleware.ts when the project uses proxy.ts, use next-auth v4 imports, or read params synchronously.
The commands that define done. The exact npm run typecheck, npm run lint, npm test and npm run build commands. Then say it outright: a task isn't done until they all pass.
Where things live. One Prisma client in src/lib/db.ts, Auth.js config in src/auth.ts, the billing sync in one file. Otherwise the agent creates a second copy.
Auth guardrails. Every page, route handler and server action calls await auth() itself. Proxy is not the security boundary. Scope every query to the session user's id.
Payment guardrails. Verify webhooks against the raw body. Never trust a price or plan sent from the client. Keep secret keys out of NEXT_PUBLIC_ variables.
What not to touch. Generated files, migrations already applied in production, and the managed block itself.

A layout that works

# AGENTS.md

## Stack
Next.js 16.4.3 (App Router, src/), TypeScript strict, Auth.js v5, Prisma, Stripe.
Request interception lives in src/proxy.ts. Do not create middleware.ts.

## Commands
- npm run typecheck
- npm run lint
- npm test
- npm run build
Done means all four pass.

## Rules
- Every page, route handler and server action calls await auth() itself.
- Scope every DB query to session.user.id.
- Stripe webhooks: verify the raw body (await req.text()), never JSON.stringify it.
- Secrets never get a NEXT_PUBLIC_ prefix.
- Use the single Prisma client from @/lib/db.

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

Put your own sections above the markers. Then the block that Next.js rewrites stays separate from the rules you own, and its diffs stay small.

Check yours

Paste your file into the free AGENTS.md checker. It runs in your browser and checks for the managed block, a stated stack and version, test/lint/build commands, and auth and payment guardrails. Each gap comes with a suggestion. Don't have a file yet? The AGENTS.md generator writes one. For scoped .cursor/rules to go with it, grab the free Cursor Rules Pack.

We wrote earlier about what we put in AGENTS.md for a Next.js starter. The VibeBoot SaaS Starter ships with an AGENTS.md, a CLAUDE.md and .cursor/rules that cover the stack, commands and guardrails above. If you use a coding agent, next dev adds the managed block to it the first time it runs.