AGENTS.md for Next.js Projects: A Production Template

A Next.js AGENTS.md should answer the questions an agent cannot resolve safely from source code: which router is in use, where server boundaries live, how the repository proves a change, and what must never be exposed to the browser.

The broader AGENTS.md guide covers instruction design and nesting. This guide supplies a web-project template for Next.js, React, Tailwind, forms, metadata, and deployment checks.

Kill the default approach: repository encyclopedias

The default instruction file grows by accumulation. It repeats the README, lists every folder, records old incidents, and tells the agent to "follow best practices." Long context is not the same as useful context.

Keep only instructions that change a decision. Put tutorials in docs, repeated procedures in skills or scripts, and enforceable rules in code or CI.

By the end you will have

1. A short root AGENTS.md for a Next.js application
2. A rule for nested instructions in sensitive areas
3. A verified command ladder
4. The Next.js AGENTS.md Starter
5. A monthly pruning test

Derive instructions from the repository

Before writing prose, inspect the actual project:

sed -n '1,220p' package.json
find src -maxdepth 3 -type d | sort
find . -name 'AGENTS.md' -o -name 'CLAUDE.md'
rg -n '"use client"|use server|generateMetadata|export const metadata' src

Confirm:

• App Router or Pages Router
• Next.js, React, and Tailwind versions
• Package manager and lockfile
• Test runner and real scripts
• Import alias and source layout
• Authentication and data clients
• Hosting platform and environment naming

Do not write commands you did not run. An instruction that says npm test in a pnpm repository creates failure before the agent edits a line.

Put architecture boundaries before style

Agents can infer semicolons from nearby code. They are less likely to infer why authentication must stay server-side or why one route is dynamic.

A useful file states:

• Server Components are the default
• "use client" belongs on the smallest interactive leaf
• Secrets and privileged clients never enter client bundles
• Mutations validate input and derive identity on the server
• Existing design tokens and components take precedence
• Metadata uses the repository's current helper or route pattern
• The narrow verification command runs before the full build

These rules protect architecture. Formatting belongs to Prettier and ESLint.

Scope nested files by risk

GitHub documents that the nearest AGENTS.md in the directory tree takes precedence for its area. GitHub's repository instruction guide also distinguishes repository-wide, path-specific, and agent instructions.

Use a nested file only when a subtree has a different contract:

AGENTS.md
src/
  app/
    api/
      billing/
        AGENTS.md
  components/
  lib/
    db/
      AGENTS.md

The billing file may require idempotency tests and forbid live provider calls. The database file may require tenant-policy checks. Do not copy the root file into each folder.

Magnet: Next.js AGENTS.md Starter

Replace every bracketed value with repository truth:

# Repository guidance
 
## Stack and structure
 
- Next.js [version], React [version], [App/Pages] Router.
- Source lives in [src/]. Import alias: [@/].
- Package manager: [pnpm/npm/bun]. Do not change lockfile tooling.
 
## Architecture
 
- Prefer Server Components. Add "use client" only to the smallest interactive leaf.
- Keep secrets, privileged clients, and authorization checks on the server.
- Validate mutation input at the server boundary and derive identity there.
- Reuse existing components and design tokens before adding new patterns.
 
## Commands
 
- Focused check: [exact command]
- Typecheck: [exact command]
- Lint: [exact command]
- Tests: [exact command]
- Production build: [exact command]
 
## Working rules
 
- Preserve unrelated dirty changes.
- Keep the diff inside the requested user outcome.
- Read the nearest nested AGENTS.md before editing a scoped directory.
- Do not add dependencies, migrations, or external services unless the task requires them.
 
## Verification
 
- Run the narrowest relevant check after editing.
- Before handoff, run typecheck, lint, affected tests, and the production build.
- Browser-test changed user journeys at mobile and desktop widths.
- Report commands run, results, and any unverified risk.
 
## Security
 
- Never print or commit secrets.
- Do not trust client-supplied identity, roles, prices, or ownership.
- Ask before destructive data operations or production mutations.

You should see: project-specific nouns and commands. If the file works unchanged in any repository, it is too generic.

Add a verified command ladder

Order commands by feedback cost:

1. Formatter or file-level lint
2. Focused unit or component test
3. Typecheck
4. Repository lint
5. Integration or browser test
6. Production build

The agent should run the cheapest command that can disprove its current change, then broaden before handoff. This keeps fast iterations without replacing the release gate.

Keep prompts out of enforceable policy

An instruction can request a test. CI can require it. Use the right layer:

The instruction file points to enforcement; it should not imitate enforcement.

Failure modes

When not to add another instruction

• The behavior can be enforced by a formatter, type, test, or permission
• The guidance applies to one issue only
• The text duplicates official framework documentation
• No observed mistake or repeated decision supports the rule

For a one-off incident, write a receipt. Promote it only when recurrence shows the repository needs persistent guidance.

Prune the file monthly

For every line, ask:

1. Does it change a real decision?
2. Is it still true in the current stack?
3. Can a tool enforce it instead?
4. Does a closer nested file own it?

Delete stale lines. Then give an agent a small task and check whether it selects the correct files and verification commands without extra prompting.

Your next action: paste the Next.js AGENTS.md Starter, replace every placeholder with verified repository truth, and delete any line that does not change a decision.