The CLAUDE.md Guide — everything that actually changes Claude Code's behavior
CLAUDE.md is the single highest-leverage file in a Claude Code project — and the most commonly mis-written. This is the hub: what the file is, what belongs in it, and links to the deep dives on writing, trimming, scaling, and reconciling it with AGENTS.md.
CLAUDE.md is the instruction file Claude Code reads at the start of every session — the place you put the build commands, conventions, and hard-won constraints a fresh model can’t infer from your code. Get it right and Claude behaves like an engineer who already knows your repo. Get it wrong — bloated, contradictory, or absent — and you pay for it silently in worse output and higher token cost on every single session.
This page is the hub for everything we’ve written about CLAUDE.md. Start here for the mental model, then follow the deep dives.
What CLAUDE.md actually is
CLAUDE.md is Claude Code’s native memory file. Three things make it different from “just a README for the AI”:
- It’s hierarchical. A project
CLAUDE.mdat the repo root, plus your personal~/.claude/CLAUDE.md, both load — project rules first, your personal preferences layered on top for your machine only. - It supports imports.
@path/to/file.mdpulls another file in at load time, so you can compose instructions instead of maintaining one giant file. - It’s loaded every session, in full. That’s the power and the tax: every line you write is re-read (and re-billed) on every run. A CLAUDE.md is not documentation you write once and forget — it’s a live cost on every interaction.
The discipline that follows from that last point is the whole game: say only what a fresh model wouldn’t already do, and say it once.
The deep dives
Each of these is a standalone field guide. Together they cover writing, trimming, scaling, and reconciling CLAUDE.md — plus using it to cap how much code the agent writes back.
1. Writing one that works
How to write a great CLAUDE.md — the craft: file hierarchy, what belongs where, and concrete before/after rewrites from production codebases. Start here if you’re writing your first one or rewriting a sprawling one.
2. Keeping it lean
Five habits that are quietly burning tokens — a bloated CLAUDE.md can add 30–60% to per-session token cost across a team. The five specific mistakes we see most often, with the fixes. Read this if yours has grown past a screen.
3. Scaling it across a team
The CLAUDE.md problem in teams of 5+ — solo CLAUDE.md works fine; the wheels come off around five engineers as rules drift and contradict. What breaks and the four habits that fix it. Read this if more than one person edits the file.
4. CLAUDE.md vs AGENTS.md
Which one does Claude Code actually read? — AGENTS.md is now a cross-vendor standard that 30+ agents read, but Claude Code still reads CLAUDE.md. How to run both without maintaining two files, and which wins when they disagree. Read this if your repo (or your team) uses more than one agent.
5. Making it write less code
Claude Code over-engineers by default — the six-question ladder that stops agents from shipping 190-line dashboards for 13-line tasks, as a plugin or as a dozen CLAUDE.md lines, and the two ways forced minimalism backfires. Read this if every small ask comes back as a subsystem.
Companion reading
- Claude Code hooks — the other half of configuring Claude Code: lifecycle hooks, which four are worth having, and the fail-open trap.
- What AI coding agents write to your disk — where CLAUDE.md and every other agent file actually live on your machine.
Was this helpful?
Related reading
- AI coding agents keep wiping production databases — the fix isn't a smarter model, it's the permission model
- Claude Code's 33,000-token startup tax — where it goes, whether it's waste, and what to cut
- GhostApproval, explained — the symlink flaw that lets a malicious repo trick AI coding agents into writing outside your workspace
Reviews independently produced · Editorial policy
Read more reviews →