CLAUDE.md best practices: most of the advice is fixing the wrong thing

You wrote a CLAUDE.md. Claude ignored it.

So you went looking for best practices, and what you found was structure advice. Put the important rules at the top. Keep it under 200 lines. Split it into imports. Use IMPORTANT and YOU MUST. Nest per-directory files.

Almost none of that is supported by anything you can check.

I went looking for evidence instead of consensus. This piece is what came back: what the one real study measured, six claims that are wrong on Anthropic's current docs, and one widely repeated myth about who wrote the definitive version.

Verified against the live docs and the primary sources on 12 August 2026. Where a claim cannot be traced to a source, I say so rather than repeating it.

TL;DR

Somebody tested this properly, and none of it worked. Across 1,650 sessions, they made the file longer, moved the rule around inside it, split it into several files, and even made it contradict itself. None of that changed how often Claude followed the rule. For file length and self-contradiction, the results suggest these two do not matter.

But having a file at all is the whole game. With no CLAUDE.md, Claude followed the rule 0 times out of 524. With one, 67.7% of the time.

The 200-line limit belongs to a different file. It is a hard cap on auto memory's MEMORY.md. For CLAUDE.md the docs say the opposite: it loads in full regardless of length, with under 200 lines as a soft target.

Splitting into @imports saves you nothing. Imported files load at launch. Same context cost, better filing. And a pointer at a docs set is actively worse, because you pay for whatever it drags in on every prompt.

The only real example we have is eight lines long. Two CLAUDE.md files leaked from Apple's Support app in May 2026. Eight bullets each, for a codebase that size, and every bullet something the model could not have inferred.

Files above your working directory load straight away. Files below it load only when Claude reads something in that folder. This one explains a lot of "Claude ignored my rules" reports, and it is missing from almost every best-practices list.

The "Karpathy CLAUDE.md" everyone half-remembers does not exist. His name comes up constantly on this topic. The trail behind it leads nowhere.

The study that should have changed the advice

In May 2026, Damon McMillan published the only study I can find that actually tests this (arXiv 2605.10039, 11 May 2026). Instead of arguing about how to write a CLAUDE.md, he changed four things about one and measured what Claude did differently.

Here is how it worked, in plain terms.

He put one simple, checkable rule in a CLAUDE.md: add a particular annotation to every function you write. Then he ran Claude Code 1,650 times over two real TypeScript codebases, a Next.js boilerplate and Umami at 663 files, across five coding tasks. That produced 16,050 functions, and for each one you can just look and see whether the annotation is there.

Then he changed one thing about the file at a time and counted whether Claude followed the rule more or less often. Most runs were on Sonnet 4.6, with Opus 4.6 as a cross-check, on Claude Code 2.1.92.

Four things were changed. Here is the entire result:

Four times, the answer was no. Every one of those is something people argue about in best-practices posts.

For two of the four, the analysis went a step further. It grouped the data by either something is going on, or nothing is. For file length, "nothing" fits about ten times better. For the self-contradiction test, about nineteen times better.

The last row is the one I keep coming back to. He deliberately wrote an instruction into the file that contradicted another one, which is the single most common explanation you will read for why Claude ignores your rules. It made no measurable difference.

For anyone who wants the statistics rather than the summary: file size χ²(3)=5.16, p=0.16, BF₁₀=0.096. Position χ²(4)=1.47, p=0.83. Architecture χ²(2)=3.29, p=0.19. Contradiction χ²(1)=0.10, p=0.76, BF₁₀=0.053. Analysis by binomial GLMM with likelihood-ratio tests, Benjamini-Hochberg correction, and a Bayesian companion producing Savage-Dickey Bayes factors. Nothing survived correction.

What did move

Two things changed how often Claude followed the rule, and both are about the work rather than the file.

What the task was, by a mile. Writing brand new code, Claude followed the rule 71.3% of the time. Editing code that already existed, 45.1%. That is a 26 point swing, against zero from everything in the table above.

That gap matters, because editing existing code is most of the job. Your rule has to compete with the code already on the screen, and roughly half the time the code on the screen wins.

It also got worse the longer a session ran. The further into a session Claude got, the less often it followed the rule: about 5.6% lower odds with each additional function it wrote. That showed up on both codebases and on both models. (OR=0.944, 95% CI [0.937, 0.951], p=1.08×10⁻⁴⁹.)

Two caveats the author raises himself. He went looking for this after seeing the data rather than planning to test it, and the decline is not perfectly steady. So treat it as a lead, not a law.

But if it holds, it points at something you can act on. Starting fresh more often does more for you than writing more rules, so /clear is the tool for this one. It is a context-window problem, which is the same reason long autonomous runs cost what they cost.

The part that justifies having a file at all

Before any of that, he ran the same tasks with no CLAUDE.md at all. Claude followed the rule 0 times out of 524. With a file, 67.7%. (χ²=534.27, p=3.33×10⁻¹²⁹.)

Two numbers hold the whole argument. Writing the file moves you from never to about two thirds of the time. How you write it leaves you there.

Read this before you cite it

Here is what is wrong with the study I just spent a thousand words on.

It is an arXiv preprint with a single author who works at a company, and it names no journal or conference. Nobody has peer reviewed it.

The thing being measured is deliberately tiny: did the annotation appear or not. That makes it easy to count and hard to generalise from. Counting an annotation tells you whether one simple rule was obeyed. Following an architectural convention is a much harder job, and that is the thing you actually care about.

And the author's own stated limits are worth quoting rather than paraphrasing: TypeScript only, Claude Code only, single-turn only, which he calls "a meaningful constraint on external validity. Real Claude Code usage is multi-turn."

That last one is the real gap. Every session you actually run is multi-turn, and nobody has measured multi-turn at all.

The honest reading is that the burden of proof has moved. Anyone telling you to reorganise your file for better adherence is now arguing against the only direct measurement that exists, and they should say why.

Six things the popular advice gets wrong

These are all checkable against Anthropic's own docs today. Note the domain: docs.claude.com/en/docs/claude-code/* is no longer canonical and now redirects. Everything lives at code.claude.com/docs/en. If a post is citing the old URLs, it is citing a redirect, and that is a decent proxy for how recently anyone checked it.

1. "Claude only reads the first 200 lines"

Wrong file. The hard cap of 200 lines or 25KB applies to auto memory's MEMORY.md. The docs draw the distinction explicitly:

"This limit applies only to MEMORY.md. CLAUDE.md files are loaded in full regardless of length, though shorter files produce better adherence."

The 200-line figure does appear for CLAUDE.md, as a soft target: "target under 200 lines per CLAUDE.md file." A recommendation, not a truncation point. Your line 340 is being read. It is also being charged to every session forever, which is a better reason to delete it than a limit that does not exist.

2. "CLAUDE.local.md is deprecated"

It is not. It has its own row in the locations table, appears in /memory, appears in the compaction table, and appears in --add-dir loading behaviour. The docs: "It loads alongside CLAUDE.md and is treated the same way."

Within a directory it is appended after CLAUDE.md. It remains the right home for anything machine-specific you do not want in the repo.

3. "Subdirectory CLAUDE.md files load at startup"

This is the one worth internalising, because it explains a lot of "Claude ignored my rules" reports:

"CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded in full at launch. Files in subdirectories load on demand when Claude reads files in those directories."

Above your working directory: loaded straight away. Below it: loaded only when Claude reads a file there.

So the carefully written packages/api/CLAUDE.md was not in context when you asked your question. It enters when Claude reads a file in packages/api. If your task never touches that directory, those rules were never loaded, and no amount of rewriting them will help.

This is testable in about thirty seconds with /context, and it is the first thing I check now.

4. "Split your file into imports to save context"

The @path/to/import syntax is real. Documented depth limit is four hops. Relative paths resolve against the file containing the import, not your working directory. Import parsing skips code spans and fenced blocks, so backticks are the escape hatch when you want a literal @.

It saves you nothing:

"Splitting into @path imports helps organization but doesn't reduce context, since imported files load at launch."

Filing cabinet, not a diet. And in practice I have stopped recommending it entirely, because the cost is worse than neutral once more than one tool is reading the file.

A pointer to a docs set is the version that really bites. Next.js ships a CLAUDE.md that points at the Next documentation, and it is a well-intentioned pattern that I would delete on sight. The moment a file says go read that, you are paying for whatever the pointer drags in, on every prompt, whether or not the task has anything to do with routing.

I learned this the expensive way running the same repo through a second agent. Pointer-heavy context files are what put me through my usage allowance fastest on Pi, because the bloat compounds per prompt rather than per session, and the second agent had no idea it was reading something written as a convenience for the first.

The rule I use instead is the one this whole piece ends on: if you think Claude can find something itself, leave it out. A pointer to where it lives counts as content too.

5. "Put NEVER in the file and it won't do it"

CLAUDE.md is context, not a permission system. The docs say where it lands in the prompt, which is the whole explanation:

"CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance."

And the corollary, stated outright:

"An instruction like 'never edit .env' in CLAUDE.md or a skill is a request, not a guarantee. A PreToolUse hook that blocks the edit is enforcement."

If you have written "never commit to main" in a CLAUDE.md and been let down, you wanted a hook. That is a different layer with different failure modes, and I wrote up why they silently do nothing separately.

6. "Just use AGENTS.md, Claude reads it now"

It does not. The docs have a dedicated section saying so, and recommend a one-line @AGENTS.md import instead. The feature request, anthropics/claude-code#6235, was opened on 21 August 2025 and is still open.

There is one narrow exception, and it is generation rather than loading: with CLAUDE_CODE_NEW_INIT=1, /init also reads AGENTS.md, .devin/rules/, .windsurf/rules/, and .clinerules when writing your CLAUDE.md. After that the files do not stay in sync.

The full comparison across sixteen tools, including which ones publish a resolution order when both files exist, is in CLAUDE.md vs AGENTS.md. Short version for this page: pick one source of truth, make the other a one-line import, and do not use the symlink if anyone on your team is on Windows.

The load order, and what survives compaction

Two tables that answer most of the remaining questions.

Load order. The docs call this load order rather than precedence, and that wording is doing real work:

"All discovered files are concatenated into context rather than overriding each other."

Concatenated, so every file you have is in there at once, in full. Your global file and your project file both apply, and they will argue with each other if you let them. Which is why a rule you wrote once in ~/.claude/CLAUDE.md eighteen months ago is still being applied to every repo you own.

What survives compaction. This one is from the context window docs and I have not seen it covered anywhere else:

Put those two tables next to the finding that compliance drops as a session runs, and one possible mechanism appears. Long session, compaction fires, your nested rules drop out and stay out until something happens to read that directory again. The study measured single-turn sessions, so it cannot be the explanation there, but for the multi-turn work nobody has measured, it is the first thing I would look at.

Practical consequence: anything you genuinely need for the whole session belongs in the project root file, unscoped. Path-scoped rules and nested files are for things that are genuinely local to a directory, and you should expect them to come and go.

My own habit here is to avoid the question. I almost never compact. I /clear instead. Compaction is a summarisation step you do not control: you cannot see in advance what it will judge worth keeping, so it is free to drop the one detail the rest of the task depended on. A clear tells you exactly what you are losing. A compaction edits your context silently, and differently every time, and the table above says the scoped half of your instructions goes with it.

Worth knowing about too, and rarely mentioned: .claude/rules/ with paths: frontmatter, the claudeMd key in managed settings, the claudeMdExcludes glob, --add-dir requiring CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 before it loads context files from added directories, block-level HTML comments being stripped before injection, the InstructionsLoaded hook, and /doctor proposing trims from v2.1.206 onward.

What a leaked production CLAUDE.md looks like

There is no official Anthropic example file, and the closest thing the public has is a leak from Apple.

In May 2026, version 5.13 of the Apple Support app shipped with two CLAUDE.md files still in the build. One for their conversational support system, internally named Juno AI. One for a shared UI component library, SAComponents. I pulled the raw markdown out and wrote both files up in full when it happened.

The thing that matters is the length. Eight bullets each. For a codebase at Apple scale.

And every one of those bullets is something Claude could not have worked out by reading the code:

"Uses AsyncStream for real-time updates, NOT Combine (unlike rest of app)."

"Service providers are actors (not @MainActor classes) for thread-safe concurrent message handling."

"Messages are wrapped in MessageGroup (UUID container) to avoid SwiftUI ID collisions (rdar://164022273). Don't flatten."

That third one is the whole discipline in a single line. It states the rule, and then it states the reason, and the reason is a radar number, an institutional fact that exists nowhere in the source tree. No amount of reading the codebase gets you there. That is what a line is for.

Now look at what is absent: no formatting rules, no naming conventions, no "write clean, maintainable code", no architecture tour, no table of contents, nothing a linter owns, nothing grep would have answered, nothing that reads as reassurance.

The SAComponents file does one more thing worth stealing: it defines done. "Always include #Preview {} showing multiple states for new components." Proof of work, stated as a requirement rather than a hope. Whatever your equivalent is, whether tests or previews or a docs entry, that is a line worth paying for, because it is a constraint the agent cannot infer and will not volunteer.

One correction to my own earlier write-up, since this piece is meant to be the honest version. In that Medium post I gave "under 200 lines, quality drops when these files get bloated" as rule one. The study above landed nine days later and does not support the adherence half of that claim. Size from 25 to 500 lines produced no detectable effect. The brevity advice survives, but for different reasons than I gave: cost, and the fact that most long files are long because they are full of things the model already knew. Apple's files are eight lines, not a hundred and ninety-nine. The limit was never the point.

If you want to run this structure against your own repo, I turned it into a skill. It scans the codebase, asks what Claude cannot infer, and writes the file from your answers:

npx skills add Alexanderdunlop/skills

What the median real CLAUDE.md actually looks like

There is a mining study worth knowing about: Agent READMEs: An Empirical Study of Context Files for Agentic Coding (arXiv 2511.12884, 17 November 2025, NAIST / Queen's / Kasetsart). It ran no agents. It read 2,303 context files from 1,925 repositories, 922 of them Claude Code files.

Median Claude Code file: 485 words. Roughly 60 to 100 lines depending on how you write. The 200-line manifesto people post as a template is already well above what the median maintained repo actually ships.

What is in them:

Those last two rows are the finding. Seven files in eight tell the agent how to run the tests. One in seven tells it anything about not writing insecure code. We write these files to make the agent functional and almost never to make its output safe, and then we hand it write access to a production repo.

The other useful number: 59 to 67% of these files have multiple commits. They are maintained like config, not written once like documentation. So people are editing these files repeatedly and the files still only grow, which makes the absence of any pruning habit more striking.

Caveat on the study: the people sorting these files into categories agreed with each other only 80.3% of the time, so they disagreed on close to a fifth of the calls. Treat the percentages as a rough shape rather than exact figures.

The Karpathy CLAUDE.md does not exist

Andrej Karpathy's name follows this topic around. Ask about CLAUDE.md in most places and someone will mention his, usually secondhand, as though there were a definitive version with his name on it.

I went looking for the primary source. There isn't one. No post, thread, talk, or gist by him about CLAUDE.md or AGENTS.md turned up anywhere I looked. What circulates traces back to third-party projects that borrowed his name, and to write-ups repeating each other.

It is a small thing, and it tells you how thin this topic is: the most-cited authority on CLAUDE.md best practices has, as far as I can establish, never written about them.

What actually earns a line

Given all of the above, here is what I would do, separated into what the evidence supports and what is my judgement.

Supported by the evidence:

Write the file. With no file, Claude followed the rule 0 times out of 524. This is the only change anyone has measured that makes a large difference, and everything else is rounding error next to it.

Stop optimising its structure. Size, position, architecture, and internal contradictions were all measured and none of them moved. Reorganising your file is work on something that was tested and did nothing.

Put anything session-critical in the project root file, unscoped. Nested and path-scoped rules load lazily and are dropped by compaction.

Keep it short, but for cost rather than adherence. The ETH Zurich AGENTS.md evaluation (arXiv 2602.11988, v2 23 June 2026) found that adding context files "does not generally improve task success rates, while increasing inference cost by over 20% on average." Note that is the v2 wording; v1 said context files "tend to reduce task success rates" and the authors softened it on 23 June. Most people are still quoting v1. Either way, the case for brevity is the bill, not the compliance rate.

My judgement, marked as such. Three tests I actually apply:

1. Would I paste this into every prompt? Because that is literally what happens. The file is prepended to your work whether or not it is relevant, so read each line as though you were typing it out again at the top of every single message.

"Make no mistakes" fails instantly. It is filler, it costs tokens forever, and it changes nothing.

"I'm using Unity 6.x" passes, and it is worth more than a page of style rules, because getting that wrong sends the model down an API that no longer exists, and nothing in the codebase necessarily announces the version.

2. Could Claude have found this itself? If you think it is smart enough to work it out, leave it out. This is the test the Apple file passes on every line, and it is the one that deletes the most from a typical repo. Architecture tours, file trees, "we use TypeScript", conventions already visible in fifty files. All of it is the model being told something it was going to read anyway.

The corollary that people miss: a pointer counts as content. Linking to a docs set instead of summarising it does not make the cost go away, it makes it worse.

3. What comes out when this goes in? My rule is one-in-one-out: when I add a rule, I have to try to remove another. Not always possible, but the attempt is the mechanism, because it forces every addition to be a ranking decision rather than an append, and ranking is the thing that never happens on its own.

Two more, from running this on real repos:

Write for the case where Claude is editing code that already exists. That produced the largest gap in the data, 45.1% against 71.3%, so the rules most likely to be ignored are the ones competing with the code already on screen. If a convention is not already visible in the files Claude is editing, one line in a context file is thin protection for it.

Move everything you can out of prose. Enforcement goes to hooks. Process goes to skills, which load on demand and cost nothing until invoked. What stays in CLAUDE.md is only what is true for every prompt in the repo.

A concrete one: I had a rule about not using arbitrary [px] values in Tailwind. It sat in CLAUDE.md, being charged to every task including the ones with no styling in them. It now lives in the process files for my implementation and review skills, which are the only two moments it is ever relevant. Same rule, same enforcement, paid for twice a day instead of two hundred times. With anvil I run the same budget discipline on the skills themselves, so this is a move sideways into a cheaper slot rather than a demotion.

And the one I still have not fixed, as evidence that this is a live discipline rather than a solved problem: I have a global rule telling Claude to run TypeScript type checks. It is correct and it is useful, right up until I am scoping a ticket or writing documentation, at which point it fires for no reason at all. That is the standing charge, in miniature, in my own file.

What the evidence does not support

IMPORTANT and YOU MUST framing. No study has tested it. No Anthropic statement I could find endorses or discourages it. It is folklore that spread because it feels like it should work. If anything, the conflict result cuts against the premise that emphasis is what compliance turns on.

The "Boris Cherny's CLAUDE.md" gist. Widely shared, not authenticated as his, undated, and not on an Anthropic account. Do not treat it as canonical.

Any official Anthropic example CLAUDE.md. I could not find one with a commit date in anthropics/skills or anthropics/claude-code. Someone may yet turn one up, but as things stand nobody can point at a vendor reference file, which is part of why this topic runs on vibes. The Apple files above are the closest thing the public has to a production reference, and they got there by accident.

The 60,000-project AGENTS.md adoption figure. It is a live GitHub code-search count on an undated page. It supports "widely visible" and nothing more precise.

A unified precedence stack. There isn't one, and any post that draws you a single ladder is inventing it. CLAUDE.md files concatenate. Skills, subagents, and MCP servers override by name. Hooks all fire. Settings have their own order: managed, then CLI args, then local, then project, then user. Anthropic's own June 2026 steering post declines to unify them and frames the choice as a tradeoff instead: "Each method trades context cost against authority."

One more thing worth knowing if you are reading around this topic. Anthropic's famous April 2025 best practices post now 302-redirects to a docs page. The essay everyone quotes now resolves to documentation, so a lot of the citations you will see point at something that has since been rewritten.

The question best-practice lists keep dodging

Every list you will read tells you what to put in. This section is about what to take out.

That asymmetry is the actual problem, and the mining data shows it: these files get committed to repeatedly, 59 to 67% of them have multiple commits, and they still only grow. There is no moment in anyone's week called prune the context file.

Which matters because of what a line in this file actually is. It loads at launch, in full, every session, whether or not it is relevant to what you asked. Line 140 is charged to the task that has nothing to do with line 140. Forever, until somebody removes it. And the study says the extra lines are not buying adherence. The file's presence bought that, back at line one.

Which makes the useful question this one:

What earns a line, and what takes one away?

Almost nobody has an answer to the second half. A rule goes in after a bad session, and a year later nobody can tell you whether it is still doing anything or whether Claude would have got it right without it. People are not being lazy about this. There is simply no mechanism that does the removing.

What I built for this

anvil is a set of Claude Code skills that treat context as a budget rather than a scratchpad.

The rule it is built on:

A line in a context file is paid every time the command that reads it runs, forever. So the default answer to "should this go in a context file?" is no.

Corrections do not go straight into a file. Every command logs them as they happen, along with the moments Claude stalled or had to guess, into two append-only logs. A separate /feedback pass is the only thing that reads those logs and the only thing that writes to context files, and a lesson has to get past three questions to be admitted:

1. Could Claude have inferred this from the code? If yes, drop it.
2. Is it stated as a direct constraint rather than a suggestion? If not, rewrite it until it is.
3. Does it fit on one line? If not, it is two lessons, or it is not a lesson.

Most corrections fail the first question and die in the logs. That is the system working.

What survives is written at the narrowest scope that holds it, and only moves outward on evidence. A lesson scoped to one command has to recur in two separate tickets before it applies to that command generally, and in three before anvil will even propose it as a line in the global file every session pays for.

The budgets are hard ceilings rather than warnings. When a file is at its limit, adding a line means removing one, and /feedback has to name the line it evicted and say why the new one beats it. That is the part almost nothing else does: it makes every addition a ranking decision instead of an append, so pruning happens continuously rather than on a schedule nobody keeps.

docs/FILE_CONTRACT.md is the whole thing written down: every file, its purpose, its line budget, and who is allowed to write it. If you only read one page, read §1.

Start by doing this

2 mins: Run /context in a repo with nested CLAUDE.md files and read the Memory files list. Anything below your working directory that is not listed was never loaded. That alone explains a good share of "Claude ignored my rules".

5 mins: Open your project CLAUDE.md and mark every line as context, enforcement, or process. Enforcement goes to a hook or to settings, because prose cannot say no. If you have never written one, the hooks decision tree is the shortest route in. Process goes to a skill, where it is paid on invocation instead of on every prompt.

10 mins: Run the two tests over whatever survived. Would you paste this line into every prompt? Could Claude have found it without you? Delete anything that fails either. Then take one pass at the pointers. Every @import and every "see the docs at" is content you are paying for, not a reference you are saving.

Then: if you want that to happen continuously rather than once, anvil is the mechanism. And if you are still deciding which filename to feed in the first place, that is a different question with a different answer.