Agent Friendly Code

What to put in an AGENTS.md for Next.js

Agents learned Next.js from older versions, so the most useful lines say which version and router you use and what changed. Since 16.3, next dev writes a block into AGENTS.md that points agents at the docs bundled in node_modules/next/dist/docs/; keep it, and add your own rules around it.

Which commands should it list?

  • next devdev server; Turbopack by default since 16
  • next buildproduction build; no longer runs the linter
  • next typegen && tsc --noEmittype check without a full build
  • eslint .lint with ESLint: next lint was removed in 16
  • biome check .or Biome; name the one you run

Write them as your repo runs them, with its package manager and flags, plus how to run one test.

What layout should it explain?

  • App Router (app/) or Pages Router (pages/), and which one new routes go in.
  • Which files are Client Components: everything a "use client" file imports ships to the browser.
  • In a monorepo, which package holds the Next.js app, and where its own AGENTS.md is.

What do agents get wrong?

  • params, searchParams, cookies() and headers() are async in 16; synchronous access is gone.
  • middleware.ts is now proxy.ts, and proxy doesn't support the edge runtime.
  • Only NEXT_PUBLIC_ variables reach the browser, inlined at build time; .env*.local stays out of git.
  • revalidateTag needs a second argument, a cacheLife profile.

From the official docs: nextjs.org/ai-agents · nextjs.org/next · nextjs.org/version-16 · nextjs.org/environment-variables . The rest of the file is the same for any project: what goes in an AGENTS.md.

Next.js repos with an AGENTS.md or CLAUDE.md (8)

Built on Next.js; 8 pass the AGENTS.md check in full. vercel/next.js has one too, for contributors to Next.js itself.

Next.js repos with an AGENTS.md or CLAUDE.md
RepoFileLength
supabase/supabaseAGENTS.md 6,972
cline/clineAGENTS.md 5,432
calcom/cal.diyAGENTS.md 9,222
payloadcms/payloadAGENTS.md 22,724
simstudioai/simAGENTS.md 23,351
TheOrcDev/8bitcn-uiAGENTS.md 9,197
hsnice16/agent-friendly-code(this site's own repo)AGENTS.md 13,340
Significant-Gravitas/AutoGPTAGENTS.md 12,045

More examples: FastAPI · Django · Rails · all examples