I stopped caring about the "400% faster startup" line somewhere around the third blog post that led with it. Cool if your cold start is nicer. That is not what keeps breaking my PRs when an agent touches a Next.js app.
What breaks is quieter: the model invents an App Router API that existed two majors ago, migrates caching with last year's mental model, or "fixes" a client error it never saw because the stack only lived in Chrome DevTools. Next.js 16.2 is interesting because it finally treats that failure mode as a product problem, not a prompt-engineering hobby.
The boring file that actually matters
`create-next-app` now drops an `AGENTS.md` that points coding agents at docs bundled inside the installed `next` package — plain Markdown under `node_modules/next/dist/docs/`. Short file. Aggressive instruction: before writing Next.js code, read the docs that match this install. Your training data is wrong; the package is the source of truth.
That sounds almost too small. It is not. Agents fail less when always-available, version-matched docs beat on-demand "skills" that the model forgets to fetch. Vercel's own evals put the AGENTS.md approach at a full pass on their Next.js suite versus roughly four-fifths for the best skill setup. I do not treat vendor evals as gospel, but the direction matches what I see in repos: the agent that reads the local docs invents fewer ghost APIs.
For existing apps on 16.2+, you add the managed block yourself (or let newer tooling upsert it). Older lines still use the `agents-md` codemod that materializes a `.next-docs` tree. The important invariant is the same: docs travel with the dependency pin, so upgrading `next` upgrades the agent's reference material.
Terminal truth over browser folklore
Two other pieces help agents that live in a shell.
Browser errors now forward to the terminal in dev by default. Agents that cannot open a console finally see the client exception next to the server log. You can widen that to warnings or all console output in `next.config`, or turn it off if the noise starts eating the signal.
There is also a lock file under `.next/dev/lock` with PID, port, and URL. When a second `next dev` starts — something agents love to do — the error is structured enough to kill the right process or attach to the existing one. Less "why is the port busy" flailing in the session transcript.
Experimental `@vercel/next-browser` goes further: shell commands that return component trees, network activity, console logs, PPR shell analysis, screenshots. An LLM cannot stare at a DevTools panel. It can parse `next-browser tree` and decide the next probe. I would treat this as useful when you already trust the agent on a branch, not as a license to skip review.
1// next.config.ts — keep agent-visible signal high, noise low2const nextConfig = {3 logging: {4 browserToTerminal: 'error', // default; try 'warn' during hard UI bugs5 },6}78export default nextConfig
Tradeoffs I would not ignore
Stale agent habits do not vanish because you added a Markdown file. Models still pattern-match on old tutorials in the conversation, still cargo-cult `getServerSideProps` into App Router apps, still "optimize" by deleting the Suspense boundary that made the static shell work. AGENTS.md raises the floor. It does not replace a human reading the migration diff.
Over-trusting AGENTS.md is the next failure. The managed block is a pointer, not a policy engine. If your repo's real rules live only in a Slack thread — how you do auth, which env vars are sacred, when ISR revalidation is allowed — the agent will invent a clean Next.js answer that is wrong for your deploy. Put project constraints outside the managed markers, and keep them short enough that they get read.
Generated migrations still need human review. Caching, route handlers, middleware, and draft/preview paths are where "docs-correct" code can still be production-wrong. The agent can now cite the right page. You still own the blast radius.
What I would do in a real repo this week
Upgrade to a line that bundles the docs, commit `AGENTS.md` / `CLAUDE.md` with the Next.js markers intact, and leave one paragraph of team rules outside them. Turn on browser-to-terminal at error level if you run agents against `next dev`. Try `next-browser` on one UI bug where the agent keeps guessing, then decide if the ceremony is worth it.
Skip rewriting your whole agent stack around the startup headline. The durable win in 16.2 is narrower and more honest: fewer wrong framework APIs in the PR, fewer invisible client errors, slightly less chaos when the agent starts a second dev server. That is enough to matter on a busy repo. It is not enough to stop reviewing the diff.