CLAUDE.mdis a plain-Markdown file that Claude Code reads automatically to learn how to work in your repository — the stack, the commands, your conventions, and which files to ignore. It's the same idea as AGENTS.md, just the filename Claude looks for. A good one saves you from re-explaining all of that in every session. The real work is keeping it short and specific enough that Claude actually follows it.
Where CLAUDE.md goes
Claude Code looks in a few places, and uses all that apply:
- Repo root — the main one.
CLAUDE.mdat the top of your project is loaded into context at the start of every session. - Subdirectories — a
CLAUDE.mdinside a package or folder adds instructions scoped to that area; the nearest one to the file being edited wins. - Your home directory —
~/.claude/CLAUDE.mdholds personal preferences that apply across every project on your machine. - Personal, untracked notes— put things you don't want to commit in a
CLAUDE.local.md(gitignore it) so they don't land in the shared file.
What to put in it
Keep it short and imperative — Claude follows a scannable list of rules far better than a wall of prose. The sections that pull their weight:
- Project overview. One or two lines: the stack, where the real source lives, anything non-obvious about the architecture.
- Commands.The exact build, run, test, and lint commands, so Claude doesn't guess between
npm,pnpm, andyarnor skip your tests. - Conventions.The house-style rules you'd tell a new teammate — patterns to follow, patterns to avoid.
- What to ignore. The files that carry no signal — lockfiles, build output, vendored code. This is the section most people leave out, and the one that most saves your context budget.
A copy-paste template
Start from this and swap in your project's specifics:
# CLAUDE.md
## Project
Next.js 16 app (App Router) + TypeScript. Payments via Stripe,
data in Supabase. Real source lives in app/, lib/, and components/.
## Commands
- Install: `npm install`
- Dev server: `npm run dev`
- Test: `npm test` (Vitest) — run before every commit
- Lint: `npm run lint`
## Conventions
- Use the semantic color tokens in globals.css; never hard-code hex.
- Server Components by default; add "use client" only when needed.
- Match the style of the file you're editing.
## Don't read these
- package-lock.json, dist/, .next/, **/*.min.js — generated files
with no signal. Skip them to keep context on real code.Tip: inside Claude Code, the /initcommand drafts a starter CLAUDE.md by scanning your repo. It's a solid first pass — then tighten it and, above all, add the “don't read these” list it won't know to include.
One thing about that last section: a “don't read these” list in CLAUDE.md is advisory — Claude reads it and usually complies, but nothing stops it from opening a listed file anyway. Claude Code can also enforce the skip at the harness level, through deny rules in .claude/settings.jsonthat block a read before it happens — a best-effort block, not a guarantee, but one that doesn't depend on the model's cooperation. That's how enforcement works.
Why Claude sometimes ignores it
When CLAUDE.md doesn't seem to stick, it's usually one of these:
- It's too long. A multi-page essay buries the rules that matter. Trim it to the must-follows and put them near the top.
- It's vague. “Write clean code” is unactionable. “Use the tokens in globals.css; never hard-code hex” is a rule Claude can actually apply.
- It contradicts itself — or contradicts a nested CLAUDE.md. When two rules disagree, the outcome is a coin flip. Keep them consistent.
Using more than one agent?
If your team also uses Cursor, Gemini, or Copilot, each reads its own file, and you want the instructions identical across all of them — see CLAUDE.md vs AGENTS.md for how the files relate. Rather than hand-copy, ContextPruner generates AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, and Copilot instructions — plus the four enforced ignore files, all nine from one triage of your file tree — with the ignore lists already filled in, free and entirely in your browser.