AGENTS.md best practices for Next.js: what actually changes agent behavior

#programming #webdev #nextjs #ai

Next.js is the stack where agent configuration pays off fastest, because
it is also the stack where agents fail most specifically. The failure
modes are consistent enough that a good AGENTS.md can prevent most of
them. Here is what belongs in a Next.js agent config, and why.

1: The command table is the highest-value block

The single most useful thing in any agent config is exact, working
commands:

| Action | Command |
|---|---|
| Install | `pnpm install` |
| Dev server | `pnpm dev` |
| Tests (single file) | `pnpm vitest run path/to/file.test.ts` |
| All tests | `pnpm test` |
| Lint + types | `pnpm lint && pnpm exec tsc --noEmit` |
| Production build | `pnpm build` |

Agents act on these literally. Without them, the agent guesses: it may
reach for npm, invent a test runner, or run tsc without --noEmit
and start "fixing" your build output. Wrong commands are worse than
missing ones, audit yours quarterly.

2: State the server/client boundary rule explicitly

The most common Next.js agent failure is blanket-'use client'-ing a
layout to make a type error go away, killing streaming and server-side
data fetching for the whole tree. One sentence in your config prevents
it:

Server Components by default. 'use client' only at interaction
leaves. If a component needs state or effects, split it, do not
convert its parent.

3: Ban effect-based fetching

Agents trained on older tutorials will fetch in useEffect. Your
config should say where data comes from:

Data fetching happens in server components or route handlers, never
in effects. Client-side fetching exists only for optimistic UI after
a mutation.

4: The NEXT_PUBLIC_ trap deserves its own line

Client bundles silently inline NEXT_PUBLIC_-prefixed env vars. An
agent that "fixes" an undefined env read by adding the prefix has just
leaked a secret into your bundle. Make it a named safety rule:

Never read process.env in client code unless the variable is
NEXT_PUBLIC_-prefixed. If a server-only value appears undefined in
a client component, the fix is moving the read server-side, never
adding the prefix.

5: Validate at boundaries, name the library

If your repo uses zod, say so, and say where:

Route handlers and server actions validate input with zod before
touching data. Handlers receive parsed data, never raw requests.

Agents generalize well from one named example. "Validate input" is
vague; "zod at every route handler boundary" is executable.

6: Testing rules that match the framework's grain

Next.js testing has its own shape: route handlers tested directly (not
through HTTP), components asserted by role and accessible name,
server/client boundaries not smothered with mocks. Put your actual
conventions in, including the single-file test command, agents run
targeted tests far more often when the command is one copy-paste away.

7: Keep the whole file under ~100 lines

Everything above fits in under 100 lines. Past that, compliance drops
off: models follow short constraint lists well and long ones
selectively (we ran the numbers in the 300-line instruction budget).
Stack detail that only matters for some files belongs in
glob-scoped Cursor rules, not the always-on baseline. The budget
discipline matters more in Next.js than most stacks, because the file
also needs room for the safety rules every repo should have (secrets,
destructive commands, dependency pinning).

The full baseline

If you would rather start from a maintained baseline than write your
own, our Next.js + TypeScript kit ships exactly this structure. AGENTS.md plus a scoped Cursor rule set, a Claude Code layer, and a
condensed Copilot file, and the complete kit is free (MIT) so you can
judge it against your repo. The full pack covers twelve stacks with the
same discipline.

DEV Community