A Practical CLAUDE.md Structure That Actually Gets Followed (2026)

If you've used Claude Code on a real project for more than a week, you've probably noticed something: a bloated CLAUDE.md gets skimmed, not read. Once it crosses a page or two, the agent still "has" the context technically, but in practice the specific instruction you actually cared about gets buried next to twenty things that didn't need saying.

The fix isn't a bigger file. It's a narrower one.

What actually belongs in CLAUDE.md

Only things that are true right now, non-obvious, and would cause a real problem if missed:

• Commands that aren't guessable — your actual test/build/lint commands, especially if they're not the framework default (npm run test:unit vs a generic npm test that doesn't exist in your repo).
• Constraints an agent would otherwise get wrong — "this repo has no database, don't suggest adding an ORM," "this is a static site, there's no build step."
• Where things actually live — if your routing isn't where a reasonable person would guess, say so once, here.

What doesn't belong

• Anything derivable by reading the code. If a function is well-named, a comment restating it is noise; the same applies to CLAUDE.md restating what package.json already says.
• Aspirational style guidelines nobody enforces. If it's not lint-enforced and nobody actually follows it, it just teaches the agent (and future readers) that the file isn't fully trustworthy.
• Anything that changes weekly. A fast-changing fact in a rarely-reopened file is a guaranteed staleness bug — six months later it's actively wrong, not just outdated.

The test that actually matters

Before adding a line, ask: if this were missing, what would actually go wrong? If the honest answer is "nothing, it'd just be figured out from the code," leave it out. If the answer is "it would confidently do the wrong thing" — that's a real line.

A CLAUDE.md that's eight tight lines gets read in full, every session. A CLAUDE.md that's eighty lines gets skimmed for the parts that matter — which means the eighty-first thing you needed said probably won't land.

---

If you're setting this up for the first time, the free getting-started guide covers the permission model and a first real workflow — the context that makes a CLAUDE.md actually useful rather than just present.