CLAUDE.md is a plain markdown file at the root of your project. Claude reads it automatically every session. Project-level: ./CLAUDE.md. Global (all projects): ~/.claude/CLAUDE.md. Project overrides global: the global file holds your defaults, the project file holds this repo's specifics.
Think of it as the onboarding document you give a highly skilled contractor who knows nothing about your project. Without it, every session begins with Claude guessing your stack, your naming conventions, and your past decisions. Guesses become code, code becomes bugs. CLAUDE.md short-circuits that chain. A file beats a clever prompt because it works whether you remember or not.
Five sections that earn their keep. Three to six bullet lines each:
1. Stack: frameworks, DB, auth, email, with versions. "Next.js 16, Postgres on Neon, Resend for email, Stripe for payments, Supabase for auth."
2. Routes: where things live. "App in /app, server actions in /actions, API under /app/api/v2, shared components in /components/ui."
3. Conventions: rules obvious to you, invisible to Claude. "Money in cents (int), dates UTC, filenames kebab-case, IDs as UUID v4."
4. Security Rules: things that must never happen. "Never log API keys. Parameterize all SQL. Rate-limit all public endpoints."
5. Don't Do This: traps you already fell into. "Don't add deps without asking. Don't run migrations from local against prod."
A worked template. Swap in your real project details:
# Plinko Grant Tracker
## Stack
- Next.js 16, Postgres (Neon), Resend, Stripe
- Auth: Supabase Auth with Google OAuth
## Routes
- App in /app, actions in /actions, API under /app/api/v2
## Conventions
- Money in cents (int), dates UTC, filenames kebab-case
- IDs: UUID v4. Boolean columns: is_ or has_ prefix
## Security Rules
- Never log secrets, parameterize SQL
- Rate-limit all POST/PUT/DELETE endpoints (10/min per IP)
- New Supabase tables ship with RLS policies in same commit
## Don't Do This
- Don't add deps without asking
- Don't run migrations from local against prod
- Don't use select(*)Notice the specificity. "10/min per IP" is actionable. "Use rate limiting" is not.
The most expensive mistake: vague rules that sound specific.
Weak: "Handle money carefully." Claude will handle money the way it thinks best, which may not match your system.
Strong: "All monetary amounts are integer cents. Never floats. Never display raw cents; divide by 100 and format with a currency symbol." Storage type, processing rule, display rule. No ambiguity.
The second mistake: writing aspirations instead of constraints. "We value clean, readable code" is an aspiration. "Files over 200 lines are split into modules" is a constraint. Aspirations require judgment; constraints produce consistent behavior. Fill your CLAUDE.md with constraints.
CLAUDE.md is a living document. Three signals it needs updating:
You paste the same context into a prompt for the second time. If you are saying it again, it belongs in CLAUDE.md.
Claude makes a mistake a rule would have prevented. The mistake is the rule. Write it before the next session.
You explain a convention to a colleague. If it was worth saying out loud, it is worth loading automatically.
Length discipline: three to six bullets per section; past eight, split the section. A CLAUDE.md too long to skim stops working because the important rules get buried. Six lines that are the right six beat sixty lines of padding.
Scaling past roughly 300 lines: split into topic files with @filename includes:
# CLAUDE.md (root)
@rules/stack.md
@rules/security.md
@rules/db-migrations.mdEach topic file stays focused; the root stays short.
Commit CLAUDE.md to version control. Rules become reviewable in PRs, and a new teammate clones the repo with Claude already configured. Add each Don't Do This rule in the same commit as the bug fix that taught it. One caution: generalize machine-specific paths before committing.
What belongs in CLAUDE.md vs a prompt? Blast radius. If a rule prevents a class of mistake that costs an hour or more to fix, it goes in CLAUDE.md. Session-specific instructions stay in prompts.
Create your first CLAUDE.md in ten minutes. Give Claude this prompt:
"I am setting up Claude Code for a project with this stack: [stack]. Key conventions someone new would not know: [conventions]. Security rules that must never be violated: [rules]. Things that caused bugs before: [traps]. Draft a CLAUDE.md with five sections: Stack, Routes, Conventions, Security Rules, Don't Do This."
The first draft gives you 80 percent. Refine it with what Claude missed; the remaining 20 percent is what is specific to your actual experience with the project.
CLAUDE.md at the project root loads your stack, routes, conventions, security rules, and traps into every session. Global file for cross-project defaults, project file for overrides. Constraints, not aspirations. Six right lines beat sixty. Update it whenever Claude makes a mistake a written rule would have prevented.