Why Claude Code Ignores CLAUDE.md (We Graded 100 Real Files)

How does Claude Code actually load CLAUDE.md?

Anthropic's memory documentation is clear on the mechanics, and most "it ignored my file" problems start with a wrong assumption about one of them:

• Where it looks. Claude Code loads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it at launch. Project files can sit at ./CLAUDE.md or ./.claude/CLAUDE.md. Files in subdirectories below your working directory load on demand, only once Claude reads, writes or edits a file in that subdirectory.
• How files combine. Everything found is concatenated, not overridden. Content runs from the filesystem root down to your working directory, so the instructions closest to where you launched are read last.
• Imports. @path/to/file pulls another file in. Relative paths resolve from the file that contains the import, and imports can nest up to four hops. The important detail: imported files also load at launch, so imports help you organise a file but do not reduce its context cost.
• How it is delivered. The docs say CLAUDE.md content arrives as a user message after the system prompt, not as part of the system prompt, and that there is no guarantee of strict compliance, especially for vague or conflicting instructions.
• Compaction. After /compact, the project-root CLAUDE.md is re-read from disk and re-injected. Nested CLAUDE.md files and path-scoped rules come back only when Claude touches a matching file again, and anything you said only in chat is gone.
• AGENTS.md. Current versions can read AGENTS.md directly, but by default only when there is no CLAUDE.md on the path. A CLAUDE.md that just says "see AGENTS.md" in words is a trap: per the docs, Claude only sees AGENTS.md if it decides to open it. An @AGENTS.md import or a symlink works reliably.

So the first check is boring but useful: run /context and confirm your file is listed under Memory files. If it is not there, Claude never saw it.

Why do long or vague files get followed less?

Anthropic's own guidance is to target under 200 lines per CLAUDE.md file, because longer files "consume more context and reduce adherence." The same page asks for instructions concrete enough to verify, such as "Run npm test before committing" rather than "Test your changes", and warns that if two instructions contradict each other, Claude may pick one arbitrarily.

That matches what users report. In GitHub issue #17530, opened in January 2026, a user with a CLAUDE.md of roughly 400 lines described Claude ignoring explicit MUST and ALWAYS rules in about half of sessions, and needing several corrections before it followed a required procedure. Treat it as one person's report: the transcript and file were not attached, and the issue was closed automatically as stale without a maintainer response. Still, the pattern is familiar: a long file, lots of shouting, and rules that do not hold.

The likely reasons are not mysterious. A long file spends attention on material that does not apply to the task in front of Claude. Vague rules ("follow best practices", "handle errors properly") give the model nothing to check itself against. Heavy emphasis stops working when every line is critical. And rules that must happen every time, like running a formatter, are better as hooks, which the docs describe as executing regardless of what Claude decides.

Why is the advice on length so contradictory?

Search for a CLAUDE.md length limit and you will find several different numbers:

• Tian Pan suggests 40 to 80 lines, with under 100 as a reasonable ceiling.
• MemX follows Anthropic's under 200 lines and suggests aiming far lower if you can.
• A BestHub article says keep the root file under 300 lines, and cites HumanLayer as reportedly running on about 60.

Several of these repeat a claim that models reliably follow only around 150 to 200 instructions in total. We could not trace that figure to a specific study from these articles, so we would not lean on it. What every source agrees on is the direction: shorter, more specific and project-only beats long and generic. The disagreement is about where the line sits, and nobody has a precise one. That is why we went and measured real files.

What did we find when we graded real CLAUDE.md files?

Method (collected 16 October 2026). We queried Sourcegraph's public search API for file:(^|/)CLAUDE\.md$ fork:no archived:no, which returned 300 public, non-fork GitHub repositories. We kept repositories with a root-level CLAUDE.md (298), sorted them by name and took every third one, giving 100 distinct repositories with a median of about 210 stars. We downloaded each file at the indexed commit. Each file was then scored with the exact grader code behind our CLAUDE.md Grader, run outside the browser. We report aggregates only and do not name repositories.

A quarter of CLAUDE.md files are just pointers

25 of the 100 files contained almost nothing except a reference to AGENTS.md: 16 were an @AGENTS.md import, 8 were symlinks to an AGENTS.md file, and 1 asked Claude in words to read AGENTS.md, which is the setup the docs say may not load. We set these 25 aside and graded the remaining 75.

The headline numbers

• Median length: 102 lines, about 1,350 estimated tokens. The longest file ran to 1,262 lines.
• 23 of 75 files (31%) were over Anthropic's 200-line target, and 7 were over an estimated 8,000 tokens.
• Median score was 87 out of 100. Files of 200 lines or fewer had a median of 90; files over 200 lines had a median of 74.
• Only 6 of the 29 files over 2,000 tokens split anything out into imports or linked docs.
• No file contained anything our grader recognised as a secret. 4 contained machine-specific absolute paths.

What changes as files get longer

The interesting part is not the score drop, which partly reflects the grader's own length penalty. It is that the kind of problem changes:

• Vague rules move in. Phrases like "best practices", "properly" and "high-quality" appeared in 3 of 52 files at 200 lines or under, and in 9 of 23 files over 200 lines.
• Shouting moves in. No file at 200 lines or under used more than three MUST, NEVER, ALWAYS or IMPORTANT words. Five of the 23 longer files did, with a median of 18 such words per file and a maximum of 27.
• Short files miss the basics instead. 18 of 52 shorter files had no test command at all, and 27 of 52 had no conventions section. The longer files were more complete, just much noisier.
• Formatting rules (indentation, semicolons, quote style) showed up in 10 of 75 files across all sizes.

The sweet spot in this sample was 100 to 200 lines: long enough to include commands and conventions, short enough to stay under about 2,000 tokens and avoid filler.

Limits of this data

Be careful with what this proves. The grader is a heuristic built from documented guidance, not a measurement of how Claude behaves with a given file, so a high score does not mean a file will be obeyed and a low score does not mean it will be ignored. Token counts are estimates. 100 repositories from one search index is a small, non-random sample that skews toward starred projects. We also excluded one grader check (unfilled placeholders) after a manual review showed it mostly flagged legitimate lines such as - Lint: `npm run lint`. And reasonable people differ on some checks: Anthropic's own docs use "Use 2-space indentation" as an example of a good specific rule, while our grader nudges you to let a formatter enforce it.

How do you get Claude Code to follow your CLAUDE.md?

1. Confirm it loads. Run /context and check the Memory files list. If your CLAUDE.md only says "read AGENTS.md", replace that sentence with an @AGENTS.md import.
2. Cut to the rules that apply to every task. Aim for under 200 lines. For each line, ask whether removing it would cause a mistake. If not, delete it.
3. Make every rule checkable. Replace "write clean code" with the specific limit, and "test your changes" with the exact command.
4. List the commands. Build, test, a single test file, lint and typecheck, inside backticks. In our sample this was the most common gap in short files.
5. Move detail out, the right way. Imports keep a file tidy but still load at launch. To actually save context, use path-scoped rules in .claude/rules/ with a paths field, which load only when Claude touches matching files, or skills, which load only when needed.
6. Put must-hold rules in the project-root CLAUDE.md. That is the file re-injected after /compact. Rules that live only in chat, in a nested file, or in a path-scoped rule may be missing right after compaction.
7. Re-check after /compact. If behaviour changes after compaction, ask Claude what its project instructions say, or run /context again.
8. Use hooks for anything that must always run. Formatting, linting before commit and blocked commands are more reliable as hooks than as reminders.
9. Save emphasis for two or three rules. If everything is IMPORTANT, nothing is.

Want a quick read on your own file? Paste it into the free CLAUDE.md Grader. It runs in your browser, shows estimated tokens and lines, and flags vague rules, formatting rules, missing commands and emphasis overuse. For ready-made prompts that ask Claude to audit or tighten a CLAUDE.md, see the Claude Code prompt library.

If you would rather keep CLAUDE.md small and put specialist know-how somewhere that loads only when it is needed, that is the idea behind the Agentsforce kit: 55 Claude Code specialist agents and 89 skills for a one-time $49. Your project file stays focused on your project, and the deeper guidance lives in agents and skills.

Bottom line

Claude Code ignores CLAUDE.md less often than it seems. Usually the file is loaded, but it is long, vague or competing with itself. In our sample of 100 public repositories, a quarter of CLAUDE.md files were just pointers to AGENTS.md, nearly a third of the rest broke the 200-line target, and the longer files were where vague rules and shouting piled up. Keep it under 200 lines, make each rule checkable, list your commands, move part-time rules into path-scoped rules or skills, and grade the result.