AGENTS.md for Next.js: Stop AI Agents From Writing Outdated Code

The Problem Every Next.js Dev Hits With AI

You ask Cursor or Claude to add a Server Action, a cache boundary, or an App Router page. The suggestion looks confident and uses an API that was deprecated two major versions ago. That’s not the model being “dumb.” It’s the model guessing from training data that doesn’t match your installed Next.js version. That’s exactly what AGENTS.md is for. It’s a short Markdown file at the root of your repo that tells AI coding agents: before you write Next.js code, read the docs that ship with this project’s next package. Those docs live under node_modules/next/dist/docs/ and match the version you actually installed. No scrape. No “I think App Router worked like this in 2023.” Source of truth first.

AGENTS.md is a project-level instruction file for AI coding agents (Cursor, Claude Code, Codex, GitHub Copilot, and others that respect the convention). In Next.js, it’s especially powerful because:

Next.js bundles version-matched docs inside the next package.
AGENTS.md points agents at those docs before they generate code.
Vercel’s agent evals showed always-on AGENTS.md context beating skill-based / on-demand doc lookup agents often don’t know when they should search, so a permanent rule wins.

In short: AGENTS.md isn’t a skill or a plugin. It’s always-on repo rules for agents.

Catchy Mental Model

Think of it this way:

Without AGENTS.md	With AGENTS.md
Agent recalls “Next.js” from memory	Agent reads your Next.js docs
Wrong caching / routing APIs	APIs match package.json
You spend time correcting	You spend time reviewing intent

If you’ve already written about not trusting AI blindly, this is the repo-level half of that story: don’t just review suggestions constrain the context so fewer bad suggestions show up.

How to Add AGENTS.md to a Next.js Repo

New projects

create-next-app can generate AGENTS.md (and often CLAUDE.md) by default on recent Next.js versions. You’re set from day one.

Existing projects

1. Add a root AGENTS.md that directs agents to the bundled docs. A solid baseline looks like this:

AGENTS.md

<!-- BEGIN:nextjs-agent-rules -->
# Next.js: ALWAYS read docs before coding

Before any Next.js work, find and read the relevant docs in `node_modules/next/dist/docs/`.
Your training data is outdated the docs bundled with this project's `next` version are the source of truth.
<!-- END:nextjs-agent-rules -->

# Project rules (keep these outside the managed block)

- Prefer App Router patterns that match the installed Next.js docs.
- Do not invent deprecated `pages/` or old caching APIs unless the docs say otherwise.
- Ask before large refactors; keep changes scoped to the task.

2. Optional: CLAUDE.md for Claude Code Claude Code often loads CLAUDE.md. Point it at your agents file:

CLAUDE.md

@AGENTS.md

3. Respect the managed block If Next.js auto-generates or upserts agent rules, it typically updates content between BEGIN:nextjs-agent-rules and END:nextjs-agent-rules. Put your project rules outside that block so upgrades don’t wipe them. 4. Confirm docs exist After install/upgrade, check that node_modules/next/dist/docs/ is present. When you upgrade Next.js, those docs upgrade with it that’s the whole point.

AGENTS.md Alone Isn’t Enough: Add Project Rules

Next.js docs stop the agent from inventing wrong framework APIs. They don’t know your design system, folder layout, or “never do this” list. I pair AGENTS.md with project-specific rules for example Once UI layout rules, TypeScript preferences, and component conventions. That can live in:

Extra sections in AGENTS.md (outside the managed block)
Cursor rules / .agents / skill files your team already uses
Short “do / don’t” lists for blog MDX, API routes, and env vars

What to put in project rules (high leverage)

Stack truth: “We use App Router, Once UI (Column / Row), no Tailwind utility soup.”
Boundaries: “Don’t commit secrets. Don’t invent API routes that bypass existing /api/* handlers.”
Review habit: “Prefer small diffs. Explain tradeoffs when changing caching or auth.”
Content conventions: “Blog posts live in src/app/blog/posts/*.mdx with publishedAt, summary, tag.”

The goal isn’t a 10-page novel. Agents follow short, enforceable rules better than essays.

A Practical Workflow That Works

Open the task with a clear goal (“Add CTA to work MDX,” not “improve the site”).
Rely on AGENTS.md so Next.js API choices come from bundled docs.
Rely on project rules so UI and structure match your portfolio.
Review like production code same habit as in my post on not trusting AI assistants blindly: read it, lint it, run it, understand it.

AGENTS.md reduces outdated mistakes. Your judgment still catches wrong product decisions.

SEO-Friendly Takeaways (For Readers and Crawlers)

If you’re skimming for the answer:

AGENTS.md = root instructions for AI coding agents in a Next.js (or any) repo.
Next.js ships version-matched docs under node_modules/next/dist/docs/.
Point agents there before they write Next.js code.
Keep custom project rules outside managed Next.js blocks.
Pair with Cursor/Claude rules for design system and architecture.
Still review every change rules improve odds, they don’t replace ownership.

Common Mistakes

Empty AGENTS.md “be careful” without pointing at docs does almost nothing.
Only global Cursor rules great for style; weak for version-accurate Next.js APIs.
Editing inside the managed block Next.js may overwrite your custom notes on upsert.
Huge rule dumps agents lose the signal; keep rules scannable.
Ignoring upgrades after bumping next, re-check that agents still read the new bundled docs.

Conclusion

AI coding agents aren’t going away. The teams that move faster aren’t the ones that accept every suggestion—they’re the ones that give agents the right source of truth. AGENTS.md is the catchy, practical fix for Next.js: one file that says “read our docs, not your memory.” Add your project rules on top, and Cursor/Claude stop inventing last year’s App Router while you keep shipping this year’s product. If you’re setting up agent rules for a Next.js portfolio or a production App Router app and want a second pair of eyes on the structure, I’m happy to help.

Want cleaner AI-assisted Next.js workflows?

I can help you set up AGENTS.md, project rules, and review habits that match your stack.

Get in Touch