CLAUDE.md for a Next.js project

A CLAUDE.md for a Next.js app: the stack, the exact pnpm commands, the App Router rules agents keep getting wrong, and the files they should never touch. Copy it into your repo root, fill in the bracketed parts, and commit it so every Claude Code session reads it first.

By Makki · Updated

When to use this

Use it on any Next.js app on the App Router. It stops the two mistakes agents make most here: writing a client component when a server one would do, and guessing at your build and test commands. Fill in the project name and swap the package manager if you use npm or yarn.

The template CLAUDE.md

# [Project] — agent guide

## Stack
Next.js 15 (App Router), React 19, TypeScript, Tailwind CSS. Package manager: pnpm.

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`
- Lint and types: `pnpm lint` then `pnpm typecheck`

## Conventions
- Server Components by default. Add "use client" only for state or effects.
- Fetch data in Server Components or route handlers, never in a client component.
- Components in `components/`, routes in `app/`. One component per file.
- Reach for the existing UI primitives before adding a dependency.

## How to work here
- Run lint, typecheck and test before you call a task done.
- Make the smallest change that solves the task.

## Do not
- Do not edit `.next/`, generated types or lockfiles by hand.
- Do not add a client component where a server one works.
- Do not commit secrets; keep them in `.env.local`.

Why each section is there

  • Stack names the versions, so the agent writes React 19 and App Router code, not an older pattern.
  • Commands give the real install, dev, build, test and lint lines. No guessing.
  • Conventions carry the server-versus-client rule that Next.js apps live and die by.
  • Do not fences off generated output and secrets, the two things an agent should never change.

Want to fill it in from a form instead? Use the CLAUDE.md generator. For how an agent uses a file like this, see working with agents.

FAQ

Where does this file go?

In the project root as CLAUDE.md. Claude Code reads it at the start of every session. Commit it so the whole team and every session gets the same rules.

Does this work for the Pages Router?

Mostly. Swap the App Router lines for your routing, drop the Server Component note, and keep the commands and the do-not list. The structure is the same.