The CLAUDE.md Guide — everything that actually changes Claude Code's behavior

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.md at 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.md pulls 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.

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 in almost every audit, 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.

Claude Code hooks in 2026 — 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.

When your CLAUDE.md has outgrown you

The pattern we see most: a CLAUDE.md that started as five useful lines and has quietly become two screens of half-true, contradictory, personal-preference-laden instructions that nobody is sure are helping. Every session pays for it, and on a team the cost multiplies by everyone running it.

That’s exactly the knot the CLAUDE.md audit untangles — we read your instruction files, cut what’s costing you, and hand back a tight, contrarian, token-lean version. $299 for a solo file, $799 for a team of 2–10.