The first thing most people do with Claude Code is paste their README into CLAUDE.md and call it a day. That file is then loaded into context on every turn, for every prompt, forever. Which means every line you wrote earns its keep on every single invocation — or costs you money for nothing.

A good CLAUDE.md is shorter than you expect and denser than you expect. It documents what Claude couldn't discover by reading the code. Everything else belongs in a README, an ADR, or a tutorial the model doesn't have to re-read every turn.

What to put in it

Three sections, maybe four: stack, conventions, gotchas, and (optionally) a short workflow note. Each bullet should be a fact that's true today and would take Claude several tool calls to figure out from scratch.

Good bullets are the ones where a new hire would hit a wall if nobody told them: "the database pool is in src/db/pool.ts, never import pgdirectly," "we use vitest, not jest, and snapshots live beside the file," "the payload run CLI needs DATABASE_URL set manually — dotenv is not auto-loaded."

What to keep out

Setup instructions. Contributor guides. Explanations of what well-known tools are. Verbose architecture diagrams. Onboarding tours. The entire commit message style guide. Any of it may be useful to humans — none of it is useful as per-turn context for the model.

A rule of thumb: if a line describes something Claude can learn from one ls, one Read, or one grep, it shouldn't live in CLAUDE.md. Let the model look it up the one turn it needs it, instead of every turn it doesn't.

Three shapes, side by side

Flip through the three variants below. The just right version is roughly one-sixth the token count of the bloated one, and actually more useful — because every line in it is a claim Claude couldn't make on its own.

# AI Blog — Next.js 15 + Payload v3 + Postgres

## Stack
- Next.js App Router (src/app). Server components by default.
- Payload v3 mounted in-process at /admin. Local API, not REST.
- Postgres via @payloadcms/db-postgres. Drizzle pushes on dev boot.

## Conventions
- Collections live in src/collections. Each one defaults to read: public
  unless it has auth content.
- Rich-text is Lexical. Custom blocks go in src/blocks.
- Tailwind v4 tokens are in src/app/(frontend)/styles.css @theme.
- Never import from /admin code into /site code — it bloats the bundle.

## Gotchas
- 'pnpm payload run' needs DATABASE_URL in the environment;
  dotenv is NOT auto-loaded.
- Media uploads live on a Docker volume; a git clone won't have them.

Layering with user and enterprise files

Claude Code merges three levels of CLAUDE.md: enterprise-level, user-level (your home directory), and project-level (in the repo). More specific overrides more general. Put project-specific truths in the repo file; put your personal preferences (response tone, default editor, how you like diffs framed) in your user file. Don't duplicate.

A quick smell test

Before committing a change to CLAUDE.md, re-read the new file end to end and ask, for each paragraph: would Claude be measurably worse at its job without this line? If the answer is no — or if the line is re-explaining the obvious — cut it. Your turns will be cheaper, faster, and warmer-cached for it.

The CLAUDE.md that ages best is the one that looks like a useful one-pager for a new teammate on their first day. Not a README. Not a wiki. A one-pager.