I use Claude in too many forms. The chat app for quick questions. Projects for the longer-running stuff. The desktop app. The API in a couple of scripts. And Claude Code in the terminal for anything that touches a real codebase.

Nobody warns you about the tax: context doesn't travel. Every surface is its own island. I'd explain a project's conventions to Claude in a chat, get great output, open Claude Code the next day, and have to explain it all over again. Multiply that across half a dozen projects and the re-explaining becomes the main cost of using AI at all.

Over the last few months I've quietly converged on Claude Code for almost everything project-related — not because the model is different, but because of one file: CLAUDE.md. It's the only place the context I've painstakingly assembled actually persists.

The walls I hit

Getting CLAUDE.md to work took longer than it should have, because my mental model was wrong. The big one: I assumed it was a kind of system prompt — an unbreakable rule the model always obeys. It isn't. It's delivered as a regular message and it's advisory: Claude reads it and tries to follow it, but a long or contradictory file just gets lost. The first time I watched Claude Code blow straight past a rule I'd written in capitals, I assumed it was broken. It wasn't — my file was too long, and the rule drowned.

That kicked off a rabbit hole, and the things I learned were genuinely counterintuitive:

• Every line costs tokens on every turn. A bloated CLAUDE.md doesn't make Claude smarter — it makes it ignore you. The test I use on every line now: "would removing this cause a mistake?" If not, it's gone.
• After /compact, only the project-root CLAUDE.md comes back. Nested CLAUDE.md files in subdirectories, and anything I'd said only in chat, just vanish. I'd been losing rules mid-session and had no idea why.
• @path imports don't save context. I'd split my file into imports thinking it would lighten the load. They load at launch anyway — they help organisation, not context.

None of these are in the marketing. I found them by walking into them.

The non-obvious bits that actually help

Once the mental model clicked, a few lesser-known features did more for me than any amount of prompt-tweaking:

• Path-scoped rules. When CLAUDE.md outgrows one file, split it into .claude/rules/*.md. A rule with a paths: glob loads only when Claude reads a matching file — so subsystem-specific guidance costs you context only when it's relevant, not on every turn.
• A trigger for what goes in. I stopped agonising over what belongs in CLAUDE.md and started using one rule: add a line the moment you'd otherwise repeat yourself — Claude makes the same mistake twice, a review catches something it should've known, or a new teammate would need the same context.
• Make "done" verifiable. A Stop hook can block a turn from ending until your check passes; or a /goal condition has a separate evaluator keep Claude working until it holds. That's what lets a longer run finish honestly instead of stopping at "looks done."

So I started collecting them

At some point I realised I was reverse-engineering the same lessons everyone else was, in parallel — and that the good guidance was scattered across blog posts, GitHub repos, and HN threads, going stale as Claude Code shipped changes.

So I built State of CLAUDE.md: a curated CLAUDE.md template that tracks what practitioners are learning, with every technical claim checked against the official docs before it ships. That last part matters more than it sounds — plenty of plausible tips don't survive it. A popular "put your stable rules at the top to maximise prompt-cache hits" tip got cut one edition; it sounds right, but it wasn't in the docs. (And the gate cuts both ways: a claim I'd cut the same way turned out to be real the next edition, once the docs caught up to it.)

It's free and MIT-licensed: the template itself, a changelog of what changed and why, and a short guide to the Claude Code primitives — MCP, hooks, plan mode, and the agentic-coding loop the whole file exists to shape.

If you're in the same boat

If you're using Claude across five surfaces and re-explaining yourself daily, try collapsing the project work into Claude Code and putting real effort into one good CLAUDE.md. Keep it short, treat it like code, and prune it the moment Claude ignores something.

And I'm still collecting — if there's a source I should be watching, or a CLAUDE.md rule that's earned its place in yours, I'd genuinely like to hear it.