/ WHAT IT ACTUALLY IS
CLAUDE.md is part of the system prompt
Most devs land on CLAUDE.md treating it like a project README, a friendly overview of "what this repo does, here's how to get started". Then they wonder why Claude keeps re-suggesting patterns they explicitly avoid, or pasting wrong commands, or losing track of the build system.
Claude Code reads CLAUDE.md into the system prompt on every turn. That changes what belongs in it. A README is for a human who will skim once and then ignore it. CLAUDE.md is for a model that reads it cold, every single response, and uses it to choose behaviour. The two formats are nothing alike, and writing CLAUDE.md as if it were a README is the single most common failure mode we see.
/ THE FIVE SECTIONS
What a production-ready CLAUDE.md actually contains
After running NeuraGrowth and a few other Claude-Code-heavy projects through 18 months of edits, the same five sections kept earning their keep. Everything else got pruned.
- Project identity (3-5 lines). One sentence on what this codebase IS, one on what it ISN'T (a fresh project vs. a fork vs. a continuation), and the deploy target. Cuts down on Claude proposing solutions for a different stack than the one we run.
- Stack (table). Framework, runtime, package manager, database, deploy. Five rows max. No marketing copy ("blazing fast", "industry-leading"). Claude already knows what Next.js is.
- Repo / deploy (concrete commands). The git remote, the branch model, the deploy command. If a deploy needs three commands chained, write all three, not a paragraph saying "we deploy via CI".
- Rules (5-7 items max). The hard constraints, what to never do, what to prefer, what's house style. Each rule is one line. No paragraphs. If you can't make a rule fit on one line, you have two rules.
- What NOT to do (3-6 items). The anti-list. Explicit bans on patterns the model would otherwise reach for: "don't pin requirements with ==", "don't add docstrings to internal helpers", "don't suggest pytest fixtures, we use unittest". This section earns its weight ten times over.
/ WHAT TO REMOVE
Five things almost every CLAUDE.md has that it shouldn't
These are the patterns we strip every time we audit a CLAUDE.md file. They're not technically wrong, they're just noise that costs tokens and dilutes the signal Claude actually uses.
- The "About this project" prose paragraph. Claude can read the package.json description, the main module docstring, and the routes. A three-sentence project summary in CLAUDE.md repeats what's already grep-able.
- Architecture diagrams in ASCII art. Tokens spent on visual structure that the model can't actually USE for decisions. Replace with a flat list: "request flow: client → middleware → handler → db".
- Installation instructions. If your installer is `npm install && npm run dev`, you don't need to write that down. If it's more complex, write a `scripts/setup.sh` and reference it in one line.
- Contributing guidelines. CONTRIBUTING.md exists; let it live there. CLAUDE.md is read by Claude, not by external contributors.
- "Last updated" dates. Git already tracks that. The date in the file body rots within a week and starts lying.
/ WHAT TO ADD
The two sections most CLAUDE.md files are missing
Beyond the five-section spine, two add-ons earn their weight in projects with any non-trivial domain logic.
- Glossary of project-specific nouns. If your codebase has a "manifest" that is NOT the standard web manifest, or a "publisher" that ISN'T a JS publisher, or a "run" that is your domain concept, write a one-line definition. Stops Claude from importing the wrong mental model on every turn.
- Frequent mistakes to NOT repeat. A running tally of things that bit you twice. "Don't async-init the DB pool inside a worker, the daemon forks before the loop starts; create on first request." One sentence each. This is where most of the project-specific value lives.
/ THE MAINTENANCE RHYTHM
CLAUDE.md doesn't update itself
Every CLAUDE.md drifts. Stack changes, conventions shift, the rule that mattered six months ago becomes obvious to anyone reading the code, and the rule you needed two weeks ago isn't in there yet.
The fix is a 15-minute monthly audit. Open CLAUDE.md, read it cold, and ask three questions: Is anything here wrong now? Is anything here so obvious I can delete it? What did I have to tell Claude this month that should be in here? The third question is the most productive, keep a scratch note of corrections you've given Claude in chat, and harvest the patterns into CLAUDE.md.
/ LENGTH
How long should it be
Most production CLAUDE.md files we see settle at 60 to 180 lines once the maintenance rhythm kicks in. Under 60 and you're probably leaning on the model to derive things it consistently gets wrong; over 180 and you've started repeating yourself or describing things Claude can read from the code.
The sweet spot is dense, declarative, and one-screen-skimmable. If you have to scroll to find the deploy command, your section ordering is wrong, not your length.
/ CLOSING NOTE
CLAUDE.md is the cheapest tool you have
A well-tuned CLAUDE.md saves more model time than any other single intervention. It's the only piece of infrastructure that pays back on every turn of every conversation, forever, until you delete it. Most teams treat it as a chore. Treating it as part of the system prompt, and pruning it that way, pays a hundred times over.