CLAUDE.md: What It Is, Best Practices & Examples

CLAUDE.md is a Markdown file of instructions that Claude Code reads at the start of every session. It holds what Claude can't work out from your code: the commands to run, the conventions that differ from defaults, and the reasons behind your architecture.

Most people either skip it or fill it with things Claude already knows. Below: a complete example, what to put in and leave out, where the file goes, and the practices that keep it useful.

What is CLAUDE.md?

CLAUDE.md is the onboarding note Claude Code reads before you type anything. Every session starts with a fresh context window, and the file is how project knowledge survives from one session to the next (Claude Code docs).

Technically, Claude Code delivers the file's content as a user message right after the system prompt, not inside the system prompt. Claude treats it as context, not enforced configuration: clear, specific instructions get followed reliably, vague or conflicting ones don't. When a rule must hold every time, such as "never write to migrations/", use a hook, which runs as code instead of relying on Claude's judgment.

What does a good CLAUDE.md look like?

A good CLAUDE.md is short, grouped under headings, and every line would cause a mistake if you deleted it. Here's a complete example for a typical web app:

# Acme Dashboard

Next.js 15 app (App Router) with a Postgres database via Prisma.
Customers are clinic managers; the UI must work on a 1280px laptop screen.

## Commands
- `pnpm dev`: start the dev server on port 3000
- `pnpm test path/to/file.test.ts`: run one test file (prefer this over the full suite)
- `pnpm typecheck`: run after every series of changes
- `pnpm db:migrate`: apply migrations; never edit files in `prisma/migrations/` by hand

## Conventions
- Use pnpm, never npm or yarn
- Server components by default; add "use client" only for interactive parts
- Dates are stored in UTC and formatted with `formatClinicDate()` from `lib/dates.ts`
- API handlers live in `src/app/api/`; validate input with zod schemas from `src/schemas/`

## Architecture decisions
- Billing goes through `src/lib/billing/` only. We moved off direct Stripe calls in pages
  because they broke idempotency; don't reintroduce them.
- Feature flags come from `lib/flags.ts`, not environment variables.

## Gotchas
- IMPORTANT: the test database is reset before every test run; don't rely on seed data.
- `NEXT_PUBLIC_` variables are baked in at build time; changing them needs a rebuild.

## Workflow
- Branch names: `feat/<short-name>` or `fix/<short-name>`
- Before opening a PR: `pnpm typecheck && pnpm lint && pnpm test`

See @docs/api-conventions.md for the full API style guide.

That's about 30 lines, well under the 200-line target. Notice what's missing: no directory tree, no list of dependencies, no "write clean code". Claude can see all of that, so including it only spends tokens.

The last line uses an import. An @path reference pulls another file into context alongside CLAUDE.md, up to four levels deep. Imports keep the file organized, but they don't cut its context cost, because the imported file loads with it.

What should you put in CLAUDE.md?

Put in what Claude can't infer from reading the code. Anthropic's best practices list:

• Bash commands Claude can't guess
• Code style rules that differ from defaults
• Testing instructions and preferred test runners
• Repository etiquette: branch naming, PR conventions
• Architectural decisions specific to your project
• Developer environment quirks, such as required environment variables
• Common gotchas or behaviors that aren't self-evident

Add a line when Claude makes the same mistake twice or you type a correction you already typed last session.

What should you leave out of CLAUDE.md?

Leave out anything Claude can figure out by reading the code, plus standard language conventions, detailed API docs (link to them instead), information that changes often, long tutorials, file-by-file descriptions, and self-evident advice.

Some of that content still has a home:

• Multi-step procedures go in a skill, which loads only when it's relevant.
• Rules for one part of the codebase go in .claude/rules/ with a paths: field, so they load only when Claude touches matching files.
• Must-always-happen actions go in a hook.
• Your personal preferences go in ~/.claude/CLAUDE.md or CLAUDE.local.md, not the shared file.

Auto-generated content deserves the same scrutiny. Researchers at ETH Zurich and LogicStar.ai tested context files on 138 tasks across 12 repositories: files written by an LLM slightly lowered success and raised inference cost by about 20%, while files written by developers improved success only marginally (Gloaguen et al., 2026). Run /init for a draft, then delete everything a new teammate could figure out alone.

Where does CLAUDE.md go?

The project file goes at your repo root, as either ./CLAUDE.md or ./.claude/CLAUDE.md; both work, so pick one. Claude Code checks four scopes and loads them all, broadest first:

The files are concatenated, not overridden. At startup Claude Code loads every CLAUDE.md from your launch directory up to the filesystem root; files in subdirectories load only when Claude works there, so per-package files in a monorepo cost nothing until needed. Run /context to see which files loaded, or /memory to open and edit them.

If your repo already has an AGENTS.md for other coding agents, Claude Code v2.1.277 and later reads it when there's no CLAUDE.md. If you want both files, put @AGENTS.md at the top of your CLAUDE.md and add Claude-specific lines below it.

Is CLAUDE.md necessary?

No, Claude Code works without one, but it's the only project context guaranteed to load before you type. Claude can explore your repo and recover the structure; it can't recover intent, like why billing goes through one module or what "done" means on your team. How the file fits with auto memory and @ references: how to give Claude Code context.

CLAUDE.md best practices

1. Stay under 200 lines. Longer files consume more context and reduce adherence, per Anthropic's docs.
2. Write rules you could check. "Use 2-space indentation" beats "format code properly".
3. Group under headings. Commands, conventions, architecture, gotchas. Organized sections are easier to follow than dense paragraphs.
4. Ask of every line: would removing it cause a mistake? If not, delete it.
5. Use emphasis once. "IMPORTANT" on one line makes it stand out; on ten lines, none do.
6. Commit it. The project file belongs in git so the team improves it together.
7. Remove contradictions. If two instructions conflict, Claude may pick either. /doctor prompt-audit finds outdated or conflicting lines across your instruction files.
8. Update on events. Rewrite the file when the stack, the commands or the team's rules change, not when you happen to remember. The habits that keep it current are in how to keep your CLAUDE.md from going stale.

What doesn't CLAUDE.md cover?

It covers the codebase, not the person working in it or the client it's for. Your role, how you like to work, what changed in last week's planning call: that's personal context, and a hand-written file is a poor home for it. ~/.claude/CLAUDE.md carries some of it, but only in Claude Code, only on one machine, and only as current as your last edit.

The numbers back that up. In an August 2026 Unabyss benchmark of 20 tasks run 60 times in Claude Code, a hand-written CLAUDE.md reduced follow-ups but barely moved cost, time or quality, while structured context from Unabyss cut cost by 36% and time by 38% and raised output quality from 7.7 to 8.9 out of 10 (What Structured AI Context Is Worth). Unabyss builds that context from Gmail, Calendar, Slack and GitHub and serves it to Claude Code, Cursor and ChatGPT over MCP. For how it compares with other approaches, see the best AI memory tools.

Keep CLAUDE.md for the project. Connect your apps to Unabyss for the context that should follow you everywhere else.

Related

• How to Keep Your CLAUDE.md From Going Stale
• How to Give Claude Code Context: CLAUDE.md, /init & Memory
• What Is an MD File? How to Open It and Why AI Tools Use It