Skip to content

CLAUDE.md template for Next.js, with real examples

A CLAUDE.md template for Next.js you can copy, where the file goes, what belongs in it, and how a repo shared with other agents loads AGENTS.md instead.

Updated · 12 min read

CLAUDE.md is a markdown file Claude Code reads at the start of every session. Put it at the root of your repo. Fill it with what Claude needs every time: commands, conventions, where things live, and what never to do. Keep it under 200 lines and push the rest into scoped rules and skills.

One catch. If other agents work in the repo too (Codex, Cursor, GitHub Copilot), the shared instructions belong in AGENTS.md, and Claude Code should load that file instead.

Below: a template to copy, where the file goes, what belongs in it, and the real setup a generated Next.js repo uses, with 30 rules, 29 skills and 7 guard hooks behind it.

What is CLAUDE.md?

CLAUDE.md is persistent memory for Claude Code. You write it once. Claude reads it every session. You stop re-explaining the same things.

Three facts shape how you should write it:

  • It's plain markdown. No required fields. No schema. Headers and bullets.
  • It's context, not config. Anthropic's docs say Claude treats CLAUDE.md "as context, not enforced configuration." Claude tries to follow it. Nothing forces it to.
  • It costs context every session. Every line loads, whether the task needs it or not. Longer files get followed less.

So CLAUDE.md is guidance. If something must never happen, you need a hook. More on that in the hooks guide.

Where to put CLAUDE.md

Put the project file at the repo root, as ./CLAUDE.md or ./.claude/CLAUDE.md. Commit it. That's the one your team shares.

Claude Code reads CLAUDE.md from four scopes, broadest first:

ScopeLocationUse it for
Managed policy/Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux and WSL), C:\Program Files\ClaudeCode\CLAUDE.md (Windows)Company rules set by IT
User~/.claude/CLAUDE.mdYour preferences, in every project
Project./CLAUDE.md or ./.claude/CLAUDE.mdTeam rules, committed to git
Local./CLAUDE.local.mdYour notes for this one project. Add it to .gitignore

How they load:

  • Files in your working directory and every folder above it load at launch.
  • Files in subfolders load on demand, when Claude reads a file in that subfolder.
  • Nothing overrides anything. Every file found is concatenated, root first. The file closest to where you launched is read last.
  • In each folder, CLAUDE.local.md comes after CLAUDE.md.

To check what loaded, run /context and look under Memory files. /memory lists every location and opens the file in your editor.

What goes in a CLAUDE.md

Anthropic's rule of thumb: facts Claude should hold in every session. Build commands, conventions, project layout and "always do X" rules. Add a line when:

  • Claude makes the same mistake a second time.
  • A code review catches something Claude should have known.
  • You type the same correction you typed last session.
  • A new teammate would need the same context.

Not everything belongs in the file. Here's where each kind of instruction goes:

ContentWhere it goes
Install, dev, test, typecheck and lint commandsCLAUDE.md, or AGENTS.md if other agents need them too
Repo-wide conventions (exports, imports, naming)CLAUDE.md, or a rule with no paths
Rules for one part of the code (webhooks, schema, components).claude/rules/*.md with paths:
Multi-step procedures (add a table, ship a release)A skill in .claude/skills/. See the skills guide
Things that must never happen (rm -rf, secrets in output)A hook. See the hooks guide
Your personal preferences~/.claude/CLAUDE.md or CLAUDE.local.md
Directory trees, dependency lists, architecture toursNowhere. Claude can read the code

That last row matters. Claude Code's /doctor checkup proposes cutting exactly that: content Claude can work out from the codebase. It keeps pitfalls, the reasons behind decisions, and conventions that differ from tool defaults.

CLAUDE.md template (copy this)

A starting template for a Next.js App Router repo where Claude Code is the only agent. We wrote it as a skeleton for this page, not from a real project. Swap in your own commands, paths and rules.

# my-app

Next.js App Router on Vercel. TypeScript strict. Postgres through Drizzle.

## Commands

- `pnpm dev`: local dev server
- `pnpm typecheck`: run before you say a task is done
- `pnpm lint`: formatting is the linter's job. Accept its output.
- `pnpm test`: unit tests

## Where things live

- `src/app/`: routes. Server Components unless a file needs state or effects.
- `src/lib/`: server code. Never import it into a "use client" file.
- `src/db/schema.ts`: the schema. Every change ships with a generated migration.

## Always

- Branch before you commit: `feat/<slug>` or `fix/<slug>`.
- Read env vars through `src/lib/env.ts`, never `process.env` in feature code.
- Only `NEXT_PUBLIC_` variables in client code.
- Parse every request body with Zod before you use it.

## Never

- Never commit `.env.local` or print a secret.
- Never add a dependency without saying why.

## More context

- Setup and env vars: @SETUP.md
- Path-scoped rules live in `.claude/rules/`.

Two details in that last section:

  • @SETUP.md is an import. Claude Code expands it into context at launch.
  • The backticked .claude/rules/ is plain text. Import parsing skips code spans and code blocks.

Do you need a CLAUDE.md at all?

Only if Claude Code is the only agent in the repo. Codex, Cursor, GitHub Copilot, Antigravity and most other coding agents read AGENTS.md. Claude Code reads it too, since v2.1.277, with one condition:

  • It reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working folder or any folder above it.
  • "Above it" includes folders outside the repo. bun init can write a CLAUDE.md, for one. We measured it on Claude Code 2.1.285: one stray CLAUDE.md in a parent folder, and Claude stopped reading the repo's AGENTS.md.
  • Your user file (~/.claude/CLAUDE.md) and .claude/rules/ files don't count. They load next to AGENTS.md.

So a repo shared between agents shouldn't depend on that check. It should import AGENTS.md in a way Claude Code always follows.

How a generated repo loads AGENTS.md in Claude Code

The generator writes no root CLAUDE.md, on purpose. It writes AGENTS.md, and one Claude Code rule that imports it. This is that rule from a real generated repo:

@../../AGENTS.md

# Claude Code

- `AGENTS.md` at the repo root holds this repo's instructions. The line above imports it.
- Scoped rules load from `.claude/rules/` when you read a file they cover. The nested `AGENTS.md` files hold the same rules for other agents, so `.claude/settings.json` keeps Claude Code from loading them twice.
- Skills are in `.claude/skills/`: run one as `/name`. Subagents are in `.claude/agents/`.
- `.claude/settings.json` runs the guards in `.agents/hooks/` and turns on the Compound Engineering plugin once you trust this folder. If its commands are missing, run `/plugin install compound-engineering@compound-engineering-plugin`.
- Claude-only notes go in this file.
- MCP servers are in `.mcp.json`. Run `/mcp` to sign in to a remote one.

.claude/rules/agents-md.md, as generated.

How it works:

  • @../../AGENTS.md is an import. Paths resolve from the file that holds them, so two folders up is the repo root.
  • A rule with no paths loads at launch, with the same priority as .claude/CLAUDE.md. So AGENTS.md loads every session.
  • It loads once. We measured it: the rule loads the root AGENTS.md once in every version, with or without a CLAUDE.md somewhere above.
  • The rest of the file is for Claude Code. Where skills and subagents live, what runs the hooks, how to reach MCP.

And this is the top of the AGENTS.md it imports, from the Indie SaaS preset: Next.js on Vercel with Better Auth, Neon, Drizzle, Stripe, Resend, PostHog, Sentry, an admin panel and an MDX blog. It comes straight from a real generate run.

# my-app

Generated by [Agentic Boilerplate](https://github.com/agentic-studio/agentic-boilerplate) from [Agentic Studio](https://theagentic.studio). Same `agentic.config.json`, same repo: regenerate and diff any time.

- **Stack:** Next.js on Vercel (`nextjs-vercel`)
- **Services:** Drizzle ORM (`drizzle`), Neon (`neon`), Better Auth (`better-auth`), Stripe (`stripe`), Resend (`resend`), Sentry (`sentry`), PostHog (`posthog`), Admin panel (`admin-panel`), MDX blog (`blog-mdx`)
- **Design:** Daylight (`daylight`). Every UI change follows [DESIGN.md](DESIGN.md).
- **Package manager:** bun
- **Mode:** solo

## Start here

On a fresh clone, run the `setup` skill: `/setup` in most agents, `$setup` in Codex.
It reads [SETUP.md](SETUP.md), which lists every environment variable, where to get
it, and the order to set the services up.

```sh
bun install
bun run setup:env -- --check   # what .env.local still needs
bun run verify
bun run dev
```

## How this repo is set up for agents

This file is the instruction file every agent reads. It holds the rules for the whole repo.

- A folder with its own `AGENTS.md` adds the rules for the files under it. Before you edit a file, read every `AGENTS.md` from the repo root down to its folder. Most agents load them for you.
- `.agents/rules/`: all 30 rules in full, one file each.
- `.agents/skills/`: 29 skills, listed below.
- `.agents/agents/`: 7 subagents, listed below. Agents with their own folder get a copy: `.claude/agents/`, `.codex/agents/`, `.cursor/agents/`, `.github/agents/`, `.gemini/agents/`, `.opencode/agents/`.
- `.agents/hooks/`: 7 guard hooks. They block destructive commands and keep secrets out of the chat. Wired for Claude Code, Codex, Cursor, GitHub Copilot, Antigravity, Gemini CLI and Windsurf. `bun run verify:hooks` proves they still block.
- MCP servers: `better-auth`, `neon`, `posthog`, `sentry`, `stripe`. [SETUP.md](SETUP.md) says how to connect them in each agent.
- `docs/solutions/`: 74 solved problems. Read the relevant one before you re-solve anything.
- `docs/plans/`: one plan per unit of work.
- The `system-manager` subagent owns this agent setup: `AGENTS.md`, `.agents/` and each agent's own folder.

## Workflow

The Compound Engineering plugin adds the loop: `/ce-brainstorm`, `/ce-plan`, `/ce-work`, `/ce-code-review`, `/ce-compound`.
In Codex they start with `$`. [SETUP.md](SETUP.md) has the install line for each agent.

First 42 of 335 lines of AGENTS.md.

What it gets right:

  • The header is one line per fact. Stack, services, design, package manager, mode. The agent knows what it's working with before it opens a file.
  • "Start here" points at one skill and one doc. /setup ($setup in Codex) and SETUP.md, which holds every env var.
  • It's an index, not an encyclopedia. Rules, skills, subagents, hooks, MCP servers and solution docs are counted and pointed to, not pasted.
  • It names the guards. It says which agents run the hooks and how to prove they still block: bun run verify:hooks.

Below that, the file holds the repo-wide rules in full (code style, git, security), then an index of the folder rules.

Keep nested AGENTS.md files from loading twice

The same repo has 32 nested AGENTS.md files, one per folder with its own rules. Claude Code would load those too, as it reads files in each folder. But Claude already gets the same rules as path-scoped files in .claude/rules/.

So .claude/settings.json lists every nested file under claudeMdExcludes, one path each, like **/src/app/api/webhooks/stripe/AGENTS.md. Claude loads nothing twice. Don't shorten that list to **/AGENTS.md: in our test, that pattern dropped the root file too, import and all.

Move scoped rules into .claude/rules

A CLAUDE.md gets long when every rule lives in it. The fix is .claude/rules/.

  • Each .md file in .claude/rules/ is one rule. Subfolders work. Files are found recursively.
  • A rule with no paths loads at launch, with the same priority as .claude/CLAUDE.md.
  • A rule with paths: frontmatter loads only when Claude uses Read, Write or Edit on a matching file.
  • paths is the only frontmatter field Claude Code reads from a rule. Anything else is ignored.

The generated repo gives Claude Code one .claude/rules/<id>.md for every rule the root AGENTS.md doesn't carry in full. Here is one. It loads when Claude touches the Stripe webhook route or the billing pipeline. Editing a marketing page never pulls it in.

---
paths:
  - src/app/api/webhooks/stripe/**
  - src/lib/billing/provider.ts
  - src/lib/billing/webhook.ts
---

# Verify every Stripe webhook, keep every handler idempotent

The webhook route is an unauthenticated public endpoint. The signature is the
only thing between a Stripe event and a forged POST that grants a lifetime
plan.

The route is three lines: `processWebhook(billingProvider, request)`. The
pipeline in `src/lib/billing/webhook.ts` is shared by every provider, and the
Stripe parts are `verifyWebhook` and `translate` in `provider.ts`. Keep it that
way: nothing Stripe-specific in the route.

**Read the body as text.** `processWebhook` calls `request.text()` and hands
those exact bytes to `verifyWebhook`. `request.json()` reorders keys and every
signature check fails. Never add a body parser or middleware in front of it.

First 21 of 71 lines of .claude/rules/stripe-webhook-integrity.md.

The rule names real functions and real files. Further down it names the status codes that drive Stripe's retries. That's what makes it checkable. The full Stripe battery is at /with/stripe.

Personal rules can live in ~/.claude/rules/. They load before project rules and apply to every project on your machine.

How @imports work in CLAUDE.md

Write @path/to/file anywhere in CLAUDE.md and Claude Code pulls that file in at launch.

  • Relative paths resolve from the file that holds the import, not from your working directory.
  • Absolute paths and ~/ paths work too.
  • Imported files can import more files, up to four hops deep.
  • Paths inside backticks or code blocks are not imported.
  • The first time a project imports a file outside the working directory, Claude Code asks you to approve it.

One catch. Imports organize a file. They don't shrink it. Imported files load at launch too, so they cost the same context. To actually save context, use path-scoped rules.

The most useful import is AGENTS.md. In a root CLAUDE.md, write @AGENTS.md. In a rule file, write the path from that file, like @../../AGENTS.md. Which one to pick: CLAUDE.md vs AGENTS.md.

CLAUDE.md best practices

PracticeWhy
Keep each file under 200 linesAnthropic's target. Longer files use more context and get followed less
Write checkable lines"Use 2-space indentation" beats "format code properly"
Group under headers and bulletsEasier to follow than dense paragraphs
Give each fact one homeIf two lines contradict, Claude may pick either one
Scope rules with paths:A billing rule has no business loading for a CSS fix
Turn procedures into skillsSkills load only when invoked or relevant
Turn hard stops into hooksA PreToolUse hook blocks a tool call no matter what Claude decides
Share instructions through AGENTS.mdOther agents read it. Claude Code can import it
Leave maintainer notes in HTML commentsBlock-level <!-- --> comments are stripped before Claude sees them
Check what loaded with /contextA file missing from Memory files isn't being read
Prune it when the code changesDead paths and old commands teach Claude wrong things

Common CLAUDE.md mistakes

  • Pasting the README. Setup prose, badges, a directory tree. Claude can read the tree itself.
  • Vague advice. "Write clean code" can't be checked. "Named exports only, except page.tsx and layout.tsx" can.
  • One giant file. Forty rules in CLAUDE.md means forty rules on every task, relevant or not.
  • Trusting it to stop damage. CLAUDE.md can say "never run git reset --hard". Only a hook can refuse it. The example repo ships 7 guard hooks for that.
  • "Read AGENTS.md" written in words. Claude sees the file only if it decides to open it. Write an @ import instead.
  • A stray CLAUDE.md above the project. It switches off Claude Code's own AGENTS.md loading for every repo below it.
  • Personal notes in the team file. Your sandbox URLs go in CLAUDE.local.md, gitignored. In an AGENTS.md-only repo, that file also counts as a CLAUDE.md.
  • Secrets. CLAUDE.md is committed. Never put a key in it, not even a test key.
  • Fighting your own rules. CLAUDE.md says one thing, .claude/rules/testing.md says another. Claude picks one, and it may not be yours.

Generate a CLAUDE.md: /init or a generator

Two ways to skip the blank page.

/init in Claude Code. It reads your codebase and writes a starting CLAUDE.md with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, it suggests improvements instead of overwriting. It also reads Cursor rules and .github/copilot-instructions.md and folds in the useful parts.

Agentic Boilerplate. Pick your services and your coding agents at /build. All 10 agents are on by default. You get a Next.js repo with AGENTS.md written for that stack, the Claude Code rule that imports it, and everything they point to. For the Indie SaaS preset that's 30 rules, 29 skills, 7 subagents, 7 guard hooks and 74 solution docs. Every solution doc is public in the cookbook. $99 once, with lifetime updates. How the pieces fit: the agentic layer.

Use /init for a Claude-only repo you already have. Use the generator for a new one that every agent can work in.

Keep going

FAQ

Where do I put CLAUDE.md?

At the root of your repo, as ./CLAUDE.md or ./.claude/CLAUDE.md, and commit it. Personal rules for every project go in ~/.claude/CLAUDE.md. Private notes for one project go in CLAUDE.local.md, added to .gitignore.

How long should a CLAUDE.md file be?

Anthropic's docs say to target under 200 lines per file. Longer files use more context and get followed less. Move anything that only matters for part of the code into .claude/rules/ with paths:.

Does Claude Code read AGENTS.md?

Yes, from v2.1.277, when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any folder above it. A stray one in a parent folder turns that off. To load AGENTS.md in every case, import it: @AGENTS.md in a CLAUDE.md, or @../../AGENTS.md in a file in .claude/rules/.

Do I need a CLAUDE.md if I have AGENTS.md?

No. Claude Code can read AGENTS.md on its own, and a rule in .claude/rules/ can import it. Add a CLAUDE.md only for Claude-only notes, and know that its presence turns off Claude Code's own AGENTS.md loading.

Can CLAUDE.md import other files?

Yes. Write @path/to/file. Paths resolve from the importing file, imports can nest four hops deep, and imported files load at launch, so they don't save context.

Does Claude always follow CLAUDE.md?

No. Claude treats it as context, not enforced configuration. For anything that must never happen, use a PreToolUse hook, which runs before the tool call and can block it.

Is there a CLAUDE.md generator?

Claude Code's /init writes a starter CLAUDE.md from your existing code. For a new Next.js project, Agentic Boilerplate writes AGENTS.md, the Claude Code rule that imports it, and the rules, skills, subagents and hooks they index.

Sources

Tool behavior is from the official docs, checked on October 8, 2026. Tools change. The docs win.