Next.js CLAUDE.md and AGENTS.md: A Production Setup

A strong Next.js setup gives Claude Code two kinds of truth. AGENTS.md points it to documentation that matches the installed Next.js version. CLAUDE.md explains your architecture, commands, and non-negotiable conventions. The Next.js DevTools MCP then gives the agent live evidence from the running application.

Together, those three pieces solve different failures: stale framework knowledge, missing project context, and code that looks correct without surviving the runtime.

Why Next.js needs version-matched agent context

Next.js moves quickly enough that a coding model can know the framework and still use yesterday's API. App Router conventions, caching behavior, request APIs, and upgrade steps change between releases.

Next.js now ships its own documentation inside the installed next package at:

node_modules/next/dist/docs/

The official Next.js guide for AI coding agents recommends a small AGENTS.md instruction that makes those local docs the source of truth. Because the documentation comes from the installed package, it matches the version in your lockfile instead of the newest website or a model's training data.

That is better than pasting dozens of framework rules into a prompt. Rules copied by hand go stale. Versioned docs update with the dependency.

Create the framework-level AGENTS.md

Recent create-next-app can generate the agent files for new projects. For an existing project, create AGENTS.md in the repository root:

<!-- BEGIN:nextjs-agent-rules -->

# Next.js: ALWAYS read docs before coding

Before any Next.js work, find and read the relevant doc in
`node_modules/next/dist/docs/`.
Your training data is outdated. The installed docs are the source of truth.

<!-- END:nextjs-agent-rules -->

Keep the managed block intact. The markers allow framework tooling to recognize and update that section later.

Add your own cross-agent rules below it:

## Repository checks

- Run `pnpm typecheck` after TypeScript changes.
- Run targeted tests before the full suite.
- Run `pnpm build` before declaring a route complete.
- Preserve Server Components unless interactivity requires a client boundary.
- Never expose server-only environment variables to client modules.

AGENTS.md is the shared contract. Claude Code, Cursor, and other compatible agents can all consume it.

Import AGENTS.md from CLAUDE.md

Create CLAUDE.md beside it:

@AGENTS.md

# Project context

This is a subscription application built with:

- Next.js App Router and TypeScript
- PostgreSQL through Supabase
- Stripe Billing
- Tailwind CSS and shadcn/ui

## Architecture

- Server Components fetch data.
- Client Components own browser state and event handlers.
- Mutations go through Server Actions in `app/**/actions.ts`.
- Shared domain logic lives in `lib/domain/`.
- Database access stays in `lib/data/`.

## Commands

- Development: `pnpm dev`
- Type check: `pnpm typecheck`
- Tests: `pnpm test`
- Production build: `pnpm build`

## Definition of done

- The happy path works in the browser.
- Loading, empty, and error states are handled.
- Authorization is enforced on the server.
- Typecheck, relevant tests, and build pass.

The @AGENTS.md line imports the framework and repository instructions without duplication. This is the division to keep:

Do not turn either file into a wiki. Every permanent instruction competes for attention. Keep the facts that change implementation choices and remove advice that any competent developer already knows.

For a deeper comparison, read AGENTS.md vs CLAUDE.md.

Add runtime evidence separately

AGENTS.md and CLAUDE.md explain what the project expects. They do not prove that a page works.

Next.js 16 and later can expose live development errors, logs, route metadata, Server Action information, and framework tooling through next-devtools-mcp. Keep that runtime integration in .mcp.json, not in either instruction file.

The dedicated Next.js DevTools MCP with Claude Code guide covers installation, live error diagnosis, browser verification, and upgrade workflows. The separation is useful:

• Agent files define durable instructions.
• The task prompt defines the current outcome.
• MCP supplies live runtime evidence.

Make the files specific to your stack

The best project instructions prevent recurring mistakes.

Authentication

## Authentication

- Read the session on the server.
- Treat middleware or proxy checks as navigation convenience, not authorization.
- Every mutation verifies the authenticated user and resource ownership.
- Never trust a user ID sent by the browser.

Data fetching

## Data

- Fetch in Server Components when possible.
- Parallelize independent reads.
- Do not add a client-side data library for server-owned state.
- Invalidate the narrowest cache tag after a mutation.

UI boundaries

## UI

- Keep pages and layouts as Server Components.
- Put "use client" at the smallest interactive boundary.
- Use the existing components and tokens before adding variants.
- Every asynchronous view needs loading, empty, error, and success states.

Billing

## Billing

- Stripe webhooks are the source of truth.
- Verify webhook signatures before parsing event data.
- Make handlers idempotent.
- Never grant entitlements from a browser redirect.

These instructions are concrete enough to alter implementation. "Use best practices" is not.

Avoid the two common extremes

A CLAUDE.md that is too thin

A file containing only the stack list forces Claude to rediscover architecture on every task. Add the paths, commands, boundaries, and checks that determine a correct change.

A CLAUDE.md that is too long

Do not paste your entire handbook into session memory. Link to focused documents when the agent needs them:

## Conditional references

- For billing work, read `docs/billing.md`.
- For database migrations, read `docs/migrations.md`.
- For design changes, read `docs/design-system.md`.

The root file should route attention, not absorb every detail.

A production-ready starter template

@AGENTS.md

# Product

[One sentence explaining what the app does and for whom.]

## Stack

- Next.js App Router, TypeScript
- [database and ORM]
- [authentication]
- [billing]
- [UI system]

## Architecture

- Server Components by default.
- Client Components only for browser APIs and interaction.
- Reads live in `[path]`.
- Mutations live in `[path]`.
- Domain logic lives in `[path]`.

## Security

- Authorize every server mutation.
- Validate untrusted input at the boundary.
- Never expose server secrets to client code.
- Treat webhooks as untrusted until signatures pass.

## Commands

- Dev: `[command]`
- Typecheck: `[command]`
- Test: `[command]`
- Build: `[command]`

## Workflow

1. Read the relevant installed framework docs.
2. Inspect existing patterns before creating a new abstraction.
3. Plan changes that cross data, auth, billing, or public APIs.
4. Implement the smallest coherent change.
5. Run checks and inspect runtime errors through Next.js DevTools MCP.
6. Verify the user flow in a browser.

## Definition of done

- Acceptance criteria are demonstrably met.
- No new runtime, console, type, or build errors.
- Error and empty states are covered.
- The diff contains no unrelated changes.

Replace every bracket. Generic placeholders left in permanent instructions create false confidence.

Next.js agent setup FAQs

Does Next.js automatically create AGENTS.md?

Newer create-next-app can generate AGENTS.md and CLAUDE.md. Existing apps can add them manually. Check the current Next.js agent guide for the required version because the canary threshold changes over time.

Is the Next.js DevTools MCP required?

No. Claude Code can build a Next.js app without it. The MCP server improves the feedback loop by exposing live errors, logs, metadata, migration tools, and framework knowledge.

Should I copy the entire Next.js documentation into CLAUDE.md?

No. Point the agent to node_modules/next/dist/docs/. The installed documentation is version-matched and avoids bloating permanent project memory.

Can other coding agents use the same setup?

Yes. Put shared guidance in AGENTS.md. Keep Claude-specific imports and behavior in CLAUDE.md. MCP support depends on the client, but the repository instructions remain portable.

What if the MCP server does not connect?

Confirm the app uses Next.js 16 or later, verify .mcp.json, start the development server, and restart the coding agent. Then check that the agent loaded project-scoped MCP configuration.

Build This Now uses the same principle at product scale: one source of truth for architecture, explicit implementation boundaries, and checks that prove a feature works. The agent files are the local version of that discipline.

The winning setup is deliberately small. Version-matched framework truth in AGENTS.md, project truth in CLAUDE.md, and runtime truth through MCP.

Posted by @speedy_devv