How to configure CLAUDE.md for a Next.js project

CLAUDE.md is the file Claude Code reads at the start of every session. It is your chance to tell the AI exactly how your project is structured, what conventions you follow, and what mistakes to avoid. A well-written CLAUDE.md turns Claude Code from a generic assistant into a teammate who already knows your codebase.

This guide covers what to put in a CLAUDE.md for a Next.js App Router project.

What CLAUDE.md actually does

When you run claude inside a project directory, Claude Code reads every CLAUDE.md it finds -- in the repo root, in subdirectories, and in your global ~/.claude/ folder. The contents are injected into every conversation as persistent context.

That means anything you write there is always available, without you having to re-explain it each session.

Start with the tech stack

List every major dependency with its version. Claude Code uses this to pick the right APIs and avoid suggesting deprecated patterns.

# Tech Stack
 
- Next.js 15 (App Router, no src/ folder)
- React 19
- TypeScript
- Tailwind CSS v4
- Shadcn UI
- Drizzle ORM + Neon DB
- Zod v4 (validation)
- React Hook Form
- JWT (auth, no NextAuth)

Version numbers matter. Zod v4 has a different API from v3. Tailwind v4 uses a different config format. Specifying versions prevents Claude Code from generating code that does not match your installed packages.

Document your folder structure

Next.js projects vary a lot -- some use src/, some do not; some co-locate components with pages, others keep a top-level components/ folder. Make the layout explicit.

# Structure
 
app/
  (main)/
    layout.tsx   -- main layout with header + footer
    page.tsx
  api/           -- thin route handlers only
  layout.tsx     -- root layout (html, body, providers)
components/
  ui/            -- shadcn, never modify directly
  layout/        -- header, footer
modules/         -- feature modules (user, post, comment)
lib/
  auth.ts        -- getUserFromRequest(), JWT helpers
  errors/        -- HttpError + handleError()
  fetcher.ts     -- client-side fetch utility
hooks/           -- custom React hooks
types/           -- shared TypeScript types

This single section eliminates a huge class of path errors and misplaced files.

List your CLI commands

Include every command a developer (or Claude Code) might need to run.

# Commands
 
- `npm run dev` -- start dev server
- `npm run build` -- production build
- `npm run lint` -- run eslint
- `npx tsc --noEmit` -- type check without building
- `npm run db:generate` -- generate SQL migration from schema changes
- `npm run db:migrate` -- apply pending migrations
- `npm run db:studio` -- open Drizzle Studio

Claude Code will run these when it needs to verify its own work -- type-checking after edits, running tests, checking lint errors.

Write your conventions explicitly

This is the highest-value section. Every project has implicit rules that live only in developers heads. Write them down.

# Conventions
 
## React and Next.js
 
- Use server components by default
- Add "use client" only for event handlers, hooks, or browser APIs
- Fetch data in server components, pass down as props
- Page files only compose imported components -- no inline markup in page.tsx
 
## TypeScript
 
- Never use `any` -- use `unknown` and narrow the type
- Always type component props with an interface
- Use `type` for unions and primitives, `interface` for object shapes
 
## Forms
 
- Always use React Hook Form + Zod
- Define the Zod schema first, infer the type from it
 
## API routes
 
- Routes must be thin: validate -> call service -> return response
- Never put business logic inside a route handler
- Use `getUserFromRequest(req)` from `lib/auth.ts` for auth

Add an anti-patterns section

Telling Claude Code what NOT to do is just as important as telling it what to do.

# Anti-Patterns (DO NOT DO)
 
- Business logic in route handlers
- DB queries inside components
- Using `any`
- Returning `passwordHash` in API responses
- Manual validation instead of Zod
- Calling `getUserFromRequest` in service layer (services must not import Request/Response)
- Setting Content-Type manually when using FormData

These read like obvious rules, but without them Claude Code will occasionally do all of them -- especially in longer sessions where early context fades.

Reference skills and modules

If your project uses Claude Code skills (custom slash commands), list them so Claude Code knows they exist.

# Skills
 
- `/generate-post` -- generate and publish a blog post
- `/drizzle-module` -- scaffold a new Drizzle module (schema, repo, service, index)
- `/nextjs-api-route` -- add a new API route following project conventions

This prevents Claude Code from writing new scaffolding code by hand when a skill already does it correctly.

Keep CLAUDE.md close to the code

A few practices that keep CLAUDE.md accurate over time:

• Update it when you add a dependency -- one line in the tech stack section takes 10 seconds and prevents hours of wrong suggestions later.
• Add anti-patterns after every bug caused by AI-generated code -- if Claude Code does something wrong once, add it to the list so it never happens again.
• Use subdirectory CLAUDE.md files for complex modules -- a modules/payment/CLAUDE.md can document Stripe-specific rules without cluttering the root file.
• Commit CLAUDE.md to the repo -- every developer and every AI session benefits from the same context.

Full minimal example

Here is a starting template for a Next.js App Router project:

# Project
 
Next.js 15 App Router with Drizzle ORM and Neon DB.
 
# Tech Stack
 
- Next.js 15 (App Router)
- TypeScript
- Tailwind CSS v4
- Drizzle ORM + Neon DB
- Zod v4
- JWT auth
 
# Structure
 
app/ -- pages and API routes
components/ -- shared UI components
modules/ -- feature modules (schema, repo, service)
lib/ -- utilities (auth, errors, fetcher)
hooks/ -- custom React hooks
types/ -- shared TypeScript types
 
# Commands
 
- `npm run dev`
- `npm run db:generate && npm run db:migrate`
- `npx tsc --noEmit`
 
# Conventions
 
- Server components by default, "use client" only when needed
- Validate all input with Zod before calling services
- API routes: validate -> service -> respond, no business logic in routes
- Never use `any`
 
# Anti-Patterns
 
- Business logic in routes
- DB access in components
- Returning passwordHash

Takeaway

CLAUDE.md is a force multiplier. The 30 minutes you spend writing it will be repaid in the first coding session -- fewer corrections, less re-explaining conventions, and code that fits your project from the start. Treat it as living documentation and update it whenever the project evolves.