Length doesn't change whether Claude follows your CLAUDE.md. Having one does: in 1,650 runs, a rule with no file was followed 0 of 524 times, and 67.7% with one. CLAUDE.md best practices, in the posts that rank for that query, are a short list: rules at the top, under 200 lines, split imports, the word IMPORTANT, a file per directory.

For the opening, that's from one preprint, Anthropic's memory docs, and Apple's two leaked files. The runs are the preprint (arXiv 2605.10039, May 2026). I checked them on 12 August 2026.

Every line is billed on every prompt, so cut any line Claude could read off the code.

30 October 2026: tightened the opening. The 28 October edit rewrote the prose and didn't re-check the sources, last read on 12 August 2026.

What are the CLAUDE.md best practices?

Write the file. Put in only what Claude can't read off the code. Anthropic recommends under 200 lines per CLAUDE.md file, because every line is billed, not because a longer file goes unread.

CLAUDE.md length and layout did not change adherence

McMillan varied length (25, 100, 250, 500 lines), where the rule sat, whether files were split or nested, and whether the file contradicted itself. None of that changed how often Claude followed the rule. A "nothing changed" reading fits about ten times better for length, and about nineteen times better for a contradiction.

What moved was the kind of work. New code followed the rule 71.3% of the time. Editing existing code, 45.1%. Each extra function in a session lowered the odds by about 5.6%. He found that after seeing the data. /clear is the practical move, for the same reason long runs cost what they cost.

The paper is a single-author preprint about one annotation. His limit, quoted: TypeScript only, Claude Code only, single-turn only, "a meaningful constraint on external validity. Real Claude Code usage is multi-turn."

The 200 line cap is MEMORY.md, and CLAUDE.md loads in full

Anthropic recommends under 200 lines per CLAUDE.md file. That figure on the memory docs is a target, not a cutoff: CLAUDE.md still loads in full. The hard cap of 200 lines or 25KB is auto memory's MEMORY.md. A study of 922 Claude Code files put the median at 485 words. Line 340 of a CLAUDE.md is still read, and it's still charged.

CLAUDE.local.md still loads next to CLAUDE.md#

The docs still list it, and they append it after CLAUDE.md in the same directory. Use it for machine-specific instructions you don't want committed.

A subdirectory CLAUDE.md loads when Claude reads that directory#

Files above the working directory load at launch. packages/api/CLAUDE.md stays out until Claude reads a file in that directory. /context lists what loaded.

An @import in CLAUDE.md loads at launch#

@path is real, with a depth of four hops. Relative paths resolve against the importing file, and backticks keep a literal @. Imports help organisation. They don't save context, because the imported files load at launch.

Next.js ships a CLAUDE.md that points at the Next docs. I delete that one, because the pointer is billed on every prompt. The same pattern burned my usage fastest on Pi.

A NEVER line in CLAUDE.md is a request#

CLAUDE.md arrives as a user message after the system prompt, and the docs promise no strict compliance. "Never edit .env" is a request. A PreToolUse hook that blocks the edit is enforcement. Hooks fail differently, which I wrote up in why a hook silently does nothing.

Claude Code does not read AGENTS.md at runtime

The docs recommend a one-line import instead. Issue 6235 has been open since 21 August 2025.

@AGENTS.md

/init with CLAUDE_CODE_NEW_INIT=1 can read AGENTS.md while it writes CLAUDE.md, and the files don't stay in sync after that. Which tool reads which file is in CLAUDE.md vs AGENTS.md.

CLAUDE.md load order: global ~/.claude/CLAUDE.md, project, local

The order is managed policy, then the global ~/.claude/CLAUDE.md, then the project file, then CLAUDE.local.md. A rule in the global ~/.claude/CLAUDE.md still applies to every repo. Skills override by name. Hooks all fire.

The project CLAUDE.md comes back after compaction#

The context window docs re-inject the project-root file, unscoped rules, and auto memory. Rules with paths: frontmatter, and nested subdirectory files, drop out until a matching file is read again. Skill bodies come back, capped at 5,000 tokens each and 25,000 total.

The study was single-turn, so compaction can't explain those numbers. I /clear rather than compact. /doctor proposes trims from v2.1.206.

What a production CLAUDE.md looks like: eight bullets Claude could not infer

In May 2026, Support app 5.13 shipped with two CLAUDE.md files still in the build: one for Juno AI, one for the SAComponents UI library. I pulled the markdown out and wrote both up.

Each file is about eight bullets Claude couldn't infer, including a MessageGroup workaround cited to rdar://164022273, a number that isn't in the source. SAComponents defines done as a #Preview {} with multiple states.

Nine days after I wrote that quality drops past 200 lines, the study found no adherence change. Apple's files are eight lines. The same shape is this command:

npx skills add Alexanderdunlop/skills

A typical CLAUDE.md is 485 words and still only grows

Agent READMEs (arXiv 2511.12884, 17 November 2025) read 922 Claude Code files. The median is 485 words. Testing instructions were in 75.0% of them. Security was in 14.5%.

A line belongs in CLAUDE.md when you would paste it into every prompt#

The ETH Zurich evaluation (v2, 23 June 2026) found context files don't generally improve task success, while raising inference cost by over 20% on average.

This part is my judgement. Would I paste this into every prompt? "Make no mistakes" fails, and "I'm using Unity 6.x" passes. Could Claude have found this in the repo? The Apple file passes that test. When I add a rule, I try to remove one.

Write for edits to existing code. That was the 45.1% against 71.3% gap. I had a ban on arbitrary Tailwind [px] values in CLAUDE.md, so it was billed on tasks with no styling. It now lives in the process files for the implementation and review skills. A global "run the TypeScript check" rule is still in my file, and it fires while I'm writing docs.

IMPORTANT and the famous example files have no adherence test

IMPORTANT and YOU MUST are untested. A deliberate contradiction in the study made no measurable difference.

The Boris Cherny gist is unauthenticated and undated. I couldn't find a Karpathy post on CLAUDE.md. As of 12 August 2026, neither anthropics/skills nor anthropics/claude-code had an official example with a commit date. "60,000 projects use AGENTS.md" is an undated code-search count.

Anthropic's June 2026 steering post keeps CLAUDE.md, skills, and hooks separate: each method trades context cost against authority. The April 2025 best practices post now redirects to the docs.

Frequently asked questions

How long should a CLAUDE.md be?
Anthropic recommends under 200 lines per CLAUDE.md file, and the file still loads in full. The 200-line or 25KB cap is MEMORY.md. A study of 922 files put the median at 485 words. Varying length from 25 to 500 lines didn't change compliance. Keep it short because every line is billed.
What should actually go in a CLAUDE.md?
Only what the model can't read off the code. Apple's leaked files are about eight bullets. I'm using Unity 6.x passes a paste-into-every-prompt test.
Should CLAUDE.md link to documentation or other files?
I avoid it. @path imports load at launch, so a pointer bills whatever it pulls in.
Why is Claude ignoring my CLAUDE.md?
Run /context. A subdirectory file loads only when Claude reads a file there. A block, rather than a reminder, is a PreToolUse hook.
Does splitting CLAUDE.md into @imports save context?
No. Imported files load at launch. The depth limit is four hops.
Is CLAUDE.local.md deprecated?
No. It loads alongside CLAUDE.md for instructions you don't want committed.
Do CLAUDE.md files override each other?
No. Managed policy, the global ~/.claude/CLAUDE.md, the project file, and the local file are concatenated.
Does writing IMPORTANT or YOU MUST improve adherence?
No study has tested it. A contradictory instruction made no measurable difference.
Does Claude Code read AGENTS.md?
Not at runtime. Add a one-line @AGENTS.md import. Issue 6235 has been open since 21 August 2025.
What is the difference between CLAUDE.md, skills, and hooks?
CLAUDE.md is billed every session. Skills load on demand. A PreToolUse hook can block an action.
Is there an official Anthropic CLAUDE.md example?
I couldn't find one with a commit date, as of 12 August 2026.