CLAUDE.md, without the Lies

I read the only real study that has tested CLAUDE.md. Then I read the two mining studies. Then I read all Anthropic’s current docs. Once again, I read the six posts (again) that everyone else quotes and checked sources.

Most of the popular advice honestly just fails.

Here are 22 things that always survive all of my flows. Most have sources and if they don’t I openly say so.

With no CLAUDE.md, Claude followed the given rule 0 times out of 524. With the CLAUDE.md file, 67.7%.

That gap is the largest anyone has measured.

Damon McMillan ran 1,650 sessions and changed four things about the file: length, rule position, file arrangement, and self-contradiction.

Reorganising your headings does nothing.

The hard cap of 200 lines belongs to MEMORY.md.

CLAUDE.md loads in full at any length. The 200 line target for CLAUDE.md is a recommendation for cost.

Your line 340 is being read. It is also being charged to every session forever, which is a better reason to delete it.

Files above your working directory load at launch.

Files in subdirectories load only when Claude reads a file in that directory.

Something like packages/api/CLAUDE.md is not in context. Run /context and look at the Memory files list.

Managed, then user, then project, then local. All of them get pasted into the same context.

Your ~/.claude/CLAUDE.md from months ago applies to everything. Go and double check it.

The docs say it directly: imported files load at launch.

It does not save tokens.

Relative paths resolve against the importing file.

Next.js ships a CLAUDE.md that points at the Next docs. Delete this pattern.

The pointer drags in whatever it references, on every prompt, whether or not the task needs it.

The cost compounds per prompt, not per session.

A second agent will have no idea it’s burning this context.

The docs are explicit: CLAUDE.md is a user message, it’s not a system prompt.

“Never edit .env” in CLAUDE.md is a request. A PreToolUse hook is enforcement.

Claude Code reads CLAUDE.md. The docs recommend a one-line @AGENTS.md import as the bridge.

GitHub issue #6235 has been open since 21 August 2025.

It appears in the current locations table, in /memory, in the compaction table, and in --add-dir.

It loads alongside CLAUDE.md and is appended after it.

It is the for machine-specific rules you don’t want to commit.

Nested files and rules with paths: frontmatter will get lost after compaction, until Claude reads a file in the right directory.

Project-root, unscoped rules and auto memory get re-injected.

Skills get re-injected too, capped at 5,000 tokens each and 25,000 total.

Given the compaction item above, this is the only slot that survives every event in a session.

Nested and path-scoped rules are for genuinely local things and can come and go.

Compaction is a summarisation step you do not see. It can drop the one detail the task depended on. /clear tells you exactly what you are losing.

McMillan measured 71.3% compliance on new code and 45.1% on edits.

Write your rules for the harder case.

If a convention is not already visible in the file Claude is editing, one line in a context file is thin protection.

Odds of following the rule fell about 5.6% with each function written.

Same effect on both models and both codebases.

Treat it as a guide, instead of a law: the author found this after seeing the data.

But if it holds, /clear more often does more for you than writing more rules.

Version 5.13 of Apple’s Support app shipped two CLAUDE.md files by mistake. Eight bullets each, for a codebase at Apple scale. Every bullet stated a decision Claude could not have inferred and named the reason. No formatting rules. No naming conventions. No “write clean code.”

That is what a line looks like when it earns its place.

922 real Claude Code files.

Median was 485 words, roughly 60 to 100 lines.

The 200-line template you see posted is already above the median maintained repo.

Apple shipped eight bullets.

In the same 922 files:

• 75% covered testing

• 70% implementation details

• 68% architecture

• 62% build commands

• Security and performance were 14.5% each.

We write these files to make agents functional, then hand them write access.

The file prepends to every message. Read each line as if you were typing it again at the top of every task.

• “Make no mistakes” is a fail.

• “I’m using Unity 6.x” is a pass.

If yes, delete it. Architecture tours, file trees, “we use TypeScript”, conventions already visible in fifty files.

Every one of them is context you pay for, forever, for information the model was going to read anyway.

When you add a line, try to remove one.

Not always possible.

However attempting is a good mechanism.

It forces every addition to be a ranking decision instead of an append, and ranking is what never happens on its own.

Always, always, always do this.

Enforcement goes to hooks. Process goes to skills, which load on demand and cost nothing until invoked. What stays in CLAUDE.md is what is true for every prompt in the repo, always.

A concrete example. I had a rule about not using arbitrary [px] values in Tailwind.

It sat in CLAUDE.md, charged to every task, including tasks with no styling.

It now lives in the process files for my implementation and review skills.

I only pay for this twice a day instead of two hundred times.

Three claims that circulate constantly.

• IMPORTANT and YOU MUST: No study has tested it, there is no Anthropic statement that endorses it. A deliberately contradictory instruction makes no difference, which disproves it.

• The Karpathy CLAUDE.md. This is completely made up, he hasn’t posted this anywhere and all sources are in fact people on their own repos with his name.

• The Boris Cherny gist. Once again made up, similar people sourcing it to their own repos with his name.

Every list tells you what to put in. Nobody has a mechanism for what to take out.

Mining data: 59 to 67% of these files have multiple commits, and they still only grow. There is no moment in anyone’s week called prune the context file.

Share

Share this with someone you know

• Run /context in a repo with nested CLAUDE.md files. Read the Memory files list. This will help you understand.

• Open your project CLAUDE.md. Mark every line as context, enforcement, or process. Enforcement goes to a hook. Process goes to a skill. What is left is context. Try it out.

• Always ask yourself, would you paste this line into every prompt? Could Claude have found it without you? Delete anything that fails either.

This is a shortened Substack version of the full write-up on my site, which has the statistics, the source citations, and the FAQ block. Read the long version.