AGENTS.md Tips: Working with Coding Agents in Next.js (2026)

Next.js now ships version-matched docs inside the package and tells coding agents to read them. The official AI agents guide (still current in August 2026) is simple: put an AGENTS.md at the root, point the agent at those bundled docs, and stop letting it invent last year’s APIs from training data. That is the highest-leverage developer tip I have used this year.

I am Vishvajeet Shukla. I use agents on client Next.js repos. When the instruction file is vague, the model writes getServerSideProps into an App Router project. When the file is specific, it opens the right doc first. Same model. Different leash.

Related: AI backends · Vercel vs Firebase.

Tip 1: One AGENTS.md, not five essays

Next.js 16.2+ already bundles docs. The official snippet tells the agent: your training data is outdated; read the packaged docs before you write Next code. Keep your own rules outside the managed comment markers so an upgrade does not wipe your house style.

Write constraints the GitHub research kept seeing as useful: never commit secrets; name the exact stack; name the commands that must pass. “React project” is not a spec. “Next.js 16, React 19, Tailwind 4, Firestore, no Pages Router” is a spec.

Tip 2: Give the agent a running app

The same Next.js guide says to run the dev server so the agent can see runtime errors. A model that only reads files will “fix” a type and miss a hydration warning. I paste the browser error, not just the terminal. If you use a browser-connected workflow, even better — but a copied stack trace is enough to start.

Tip 3: Specs beat vibes

Addy Osmani’s 2026 note on specs for agents is the same lesson in another hat: objective, stack, commands, then tasks. I keep a /specs file or a GitHub issue template with: what done looks like, what not to touch, and which test must go green. Agents are good at turning an OpenAPI file into a client. They are bad at guessing which folder is sacred.

Tip 4: One task, one PR

Ask for the forgot-password flow, not “improve auth.” Large prompts create large, unreviewable diffs. I reject PRs that mix a feature with a drive-by reformat of 40 files. Tell the agent the formatter command and let CI format. Humans review behaviour.

Tip 5: Keep a deny list

Put these in AGENTS.md in plain words:

• Do not add new dependencies without asking.
• Do not edit public/ binaries.
• Do not weaken auth to make a test pass.
• Do not write to production env files.
• Do not introduce Pages Router APIs in app/.

Models follow negative rules more reliably when they sit next to the stack list, not in a Slack thread from March.

A file I actually use

Short version of what lives at the top of my client repos:

• Product: marketing site + admin, India SME, WhatsApp CTAs.
• Stack: Next.js App Router, TypeScript, Tailwind, Firestore.
• Commands: lint, typecheck, build.
• Voice: no “delve,” no fake testimonials.
• Never commit .env or service accounts.

That is enough to stop 80% of silly patches. The other 20% is still a human reading the diff — same as the hiring checklist for freelancers: look at the work, not the pitch.

Working with the agent day to day

I start the session by pasting the issue number and the test I expect to go green. I do not paste the entire codebase. I name the two files I think should change. If the agent needs a third file, it should say why. When it opens twelve files, I stop the run and shrink the task.

At the end of a session I ask for a summary of commands it ran. If it ran a destructive migrate or a rm, I want that in the first line, not buried. I also ask it to list secrets it touched. “None” is the only good answer. Anything else is a rotate.

For Next.js specifically, I keep a short “do not” for deprecated data APIs. Agents still remember Pages Router. The bundled docs exist so you can tell the model to stop remembering. If your app is on 16.2, say so in the first paragraph of AGENTS.md. Version drift is how you get tutorials from 2024 applied to a 2026 repo.

What I put in the repo root besides AGENTS.md

A .nvmrc or Volta pin so the agent does not “helpfully” upgrade Node. An .editorconfig so it does not fight your tabs. A short CONTRIBUTING that says “one feature per PR.” These files are not bureaucracy. They are ballast. Without them the model invents a second style guide in every folder.

If two teammates use two tools, they still share AGENTS.md. The tool-specific file only points at it. That is how you avoid a Cursor-flavoured folder and a Claude-flavoured folder in the same week.

FAQ

Do I need CLAUDE.md and AGENTS.md and Copilot instructions?

Start with AGENTS.md. Point other tools at it. Three conflicting files are how you get three styles in one PR.

Should the agent browse the live Next.js website?

Prefer the bundled docs in the package. The public site moves. The packaged docs match the version you installed.

Can an agent maintain AGENTS.md itself?

It can draft. You approve. An agent that rewrites its own leash is a joke until it is an incident.

Is this only for Next.js?

The idea is general. Next.js just documented it clearly in 2026. Django, Go, and mobile repos need the same “read our docs, here are commands.”

Will this replace senior review?

No. It replaces the senior repeating “we don’t use getServerSideProps here” for the fifth time this week.

Next step

If you want a starter AGENTS.md for a Next.js marketing site, say what you use for CMS and hosting. I will send a one-pager you can paste, then you delete the lines that are not true.

Contact · [email protected] · More guides