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:
| Scope | Location | Use 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.md | Your preferences, in every project |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md | Team rules, committed to git |
| Local | ./CLAUDE.local.md | Your 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.mdcomes afterCLAUDE.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:
| Content | Where it goes |
|---|---|
| Install, dev, test, typecheck and lint commands | CLAUDE.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 tours | Nowhere. 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.mdis 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.mdorCLAUDE.local.mdin your working folder or any folder above it. - "Above it" includes folders outside the repo.
bun initcan 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.mdis an import. Paths resolve from the file that holds them, so two folders up is the repo root.- A rule with no
pathsloads 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($setupin Codex) andSETUP.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
.mdfile in.claude/rules/is one rule. Subfolders work. Files are found recursively. - A rule with no
pathsloads 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. pathsis 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
| Practice | Why |
|---|---|
| Keep each file under 200 lines | Anthropic'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 bullets | Easier to follow than dense paragraphs |
| Give each fact one home | If 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 skills | Skills load only when invoked or relevant |
| Turn hard stops into hooks | A PreToolUse hook blocks a tool call no matter what Claude decides |
| Share instructions through AGENTS.md | Other agents read it. Claude Code can import it |
| Leave maintainer notes in HTML comments | Block-level <!-- --> comments are stripped before Claude sees them |
Check what loaded with /context | A file missing from Memory files isn't being read |
| Prune it when the code changes | Dead 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.tsxandlayout.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.mdsays 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
- AGENTS.md examples: the file every other agent reads, root and nested.
- CLAUDE.md vs AGENTS.md: which one you need, and how to keep both without drift.
- Claude Code setup for Next.js: rules, skills, subagents, hooks and MCP on one page.
- Codex setup for Next.js: the same repo, from Codex.
- Cursor rules for Next.js:
.mdcrules, and when you need them.
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.
Keep reading
- AGENTS.md examples, from a real Next.js repoWhat AGENTS.md is, a template to copy, real root and nested files from a generated Next.js repo, and how Codex, Cursor, Copilot and Claude Code load them.
- CLAUDE.md vs AGENTS.md: which one you needCLAUDE.md is Claude Code's file. AGENTS.md is the one Codex, Cursor, Copilot and most other agents read. Who reads what, and how to keep both in sync.
- Cursor rules for Next.js, with real .mdc examplesHow Cursor rules work: the .mdc format, globs, alwaysApply and the four rule types, when a nested AGENTS.md is enough, and real Next.js rules to copy.
- Claude Code skills, with 29 real examplesA Claude Code skill is a SKILL.md file that becomes a slash command Claude can also load on its own. How to write one, what to avoid, and 29 real examples.