CLAUDE.md: Why Long Instruction Files Fail to Govern

A team ships a rule into CLAUDE.md after an incident. It works. Two months and six incidents later the file runs to 3,000 words, and the original rule is being skipped again.

Nobody edited it. Nobody removed it. It is still sitting there, in the same words that worked in week one.

The short version: CLAUDE.md is context, not control. It is advisory by design, it is diluted by its own length, and nothing in the loop checks whether any individual CLAUDE.md rule was followed.

That first point is not a criticism from outside. Claude Code’s own documentation draws the line in a single sentence:

“Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens.”

Advisory is the design, not a defect. The problem starts when teams treat the file as though it were enforcement.

What Does Claude Code Actually Do With CLAUDE.md?

It reads the file at the start of every conversation and puts it in the context window.

That is the whole mechanism, and the documentation states its consequence plainly in its guidance on writing the file: “CLAUDE.md is loaded every session, so only include things that apply broadly.”

Files can sit in several places at once. A home folder copy applies to all sessions, a project root copy is checked into git for the team, and a gitignored CLAUDE.local.md holds personal notes.

Parent directories are pulled in for monorepos, child directory files load on demand, and any of them can pull in further files with @path/to/import syntax, recursing up to four hops.

Those imports matter more than they look. They are a common reason a file that reads as 300 words is delivering several thousand.

There is one more location, and it matters for governance specifically. Organisations can deploy an organisation-wide managed policy CLAUDE.md, at /Library/Application Support/ClaudeCode/CLAUDE.md on macOS or /etc/claude-code/CLAUDE.md on Linux, which applies to every session on the machine and cannot be excluded by individual settings.

That is as close as the file format gets to enforcement, and the docs are careful about the limit: “Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude’s behavior but are not a hard enforcement layer.” Undeletable is not the same as obeyed.

Once loaded, the content is in the same context window as your prompt, every file Claude reads, and every command output. The docs are direct about what that window does under pressure:

“Most best practices are based on one constraint: Claude’s context window fills up fast, and performance degrades as it fills.”

So an instruction file is not a settings panel that the runtime consults. It is text competing with other text, and its share of attention falls as the session grows.

Two adjacent subjects are handled elsewhere and not repeated here. Deciding who controls Claude Code rollout and what belongs at the gateway is an organisational question, covered in our platform team’s guide to Claude Code ownership.

Scoring whether the agent picked the right tool with the right arguments is covered in evaluating Claude Code tool use.

Why Does Adding a Rule Make the Other Rules Weaker?

Because attention is finite, and the docs say so without hedging:

“Bloated CLAUDE.md files cause Claude to ignore your actual instructions!”

The same page lists it among its common failure patterns. “The over-specified CLAUDE.md. If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise.”

There is research behind the shape of that claim. IFScale is a benchmark of 500 keyword-inclusion instructions built to measure how instruction-following degrades as instruction density rises. Across 20 models from seven providers, the authors report that “even the best frontier models only achieve 68% accuracy at the max density of 500 instructions.”

Be careful with that number. Keyword inclusion is not repository conventions, and 500 is far past any sane instruction file. What IFScale establishes is the direction and the fact that it applies to frontier models, not a figure for your CLAUDE.md.

It is worth pausing on the numbers you will meet instead. A specific claim circulates widely in write-ups on this topic: that models reliably follow roughly 150 to 200 discrete instructions, that Claude Code’s system prompt consumes about 50 of those “slots”, and that your file therefore gets 100 to 150. The framing is intuitive and the arithmetic is tidy. We have not been able to trace any of it to a published measurement or to Anthropic’s documentation, and we would rather say so than repeat it.

Treat instruction-slot budgets as folklore until someone sources them. IFScale is the measured version of the same intuition, and what it actually supports is a gradient rather than a cliff: adherence falls as density rises, with no threshold at which the model stops reading.

Closer to the actual deployment pattern is HANDBOOK.md, published in July 2026. It tests exactly this arrangement: a standing policy document placed in context and trusted to govern an agent’s tool use.

Its framing is the thesis of this post, stated by researchers. Agents are “deployed under standing instructions: a system prompt, a policy file, or a skills document is placed in context, and the agent is trusted to let it govern every action that follows”, and “existing benchmarks rarely test this deployment pattern directly”.

Across 65 agentic tasks with policy documents of 20 to 124 pages, the authors report that under strict grading, where “a trial passes only if every criterion is satisfied”, “the strongest evaluated model passes 36.2% of trials, and most frontier models remain below 25%”.

Those tasks are far larger than a CLAUDE.md, so the percentages are not yours either. What the paper contributes is the named failure list, which reads like a description of a long instruction file. Agents “lose rule details over long horizons”, and act against a check they have just performed.

The arithmetic is what makes it concrete. Treat a file as n rules, each followed with probability a. The chance a given run honours all of them is a^n.

Read the 99% column. A rule followed 99 times out of 100 is a rule that works. Fifty such rules hold together in 60.5% of runs.

The point where a clean run becomes a coin flip arrives earlier than intuition suggests: 69 rules at 99% adherence, 35 at 98%, and 14 at 95%.

This is a model, not a measurement, and it assumes rules are independent, which real rules are not. It is still the right mental shape, because it names the asymmetry that governs the file.

Cost grows as n. Reliability decays as a^n.

Adding a rule is therefore never neutral. It is a withdrawal taken from every other rule already in the file, paid on every session.

Which Rules Get Lost First?

The ones buried in the middle of a long file, and the ones you moved into a subdirectory.

Position matters, though not in the way the folk answer suggests. IFScale’s authors report a “bias towards earlier instructions”, measured within a single flat list of instructions in one prompt.

Whether that maps onto append-order in a file that grew over months is untested. Treat it as a reason to care about position, not as a rule about recency.

The practical advice does not depend on resolving it: a file long enough for position to matter is already too long.

Imports compound it. A file that opens with several @path pulls pushes its own content further down, behind whatever those files contain, and imports can recurse four hops deep before Claude Code stops following them.

Length itself degrades adherence, and the documentation now attaches a number to it: target under 200 lines per CLAUDE.md file, because “longer files consume more context and reduce adherence”.

Contradiction is the failure teams miss entirely. The docs warn that “if two rules contradict each other, Claude may pick one arbitrarily”, which is what makes a file that grew by accretion dangerous rather than merely long. Two rules written eight months apart, both reasonable, can quietly disagree.

Compaction is the one place the picture is better than the folklore. A project-root CLAUDE.md survives it: Claude re-reads the file from disk and re-injects it after compacting. Nested CLAUDE.md files in subdirectories are not re-injected automatically, and reload only when Claude next reads a file in that directory.

So the rules that go quiet are the ones you pushed down into subdirectories to keep the root file short. The tidying move and the reliability move point in opposite directions.

There is also a second file nobody is pruning. Claude Code’s auto memory writes its own notes to a per-project MEMORY.md, and the first 200 lines or 25KB load into every session alongside your CLAUDE.md.

That is an instruction surface which grows without review. It is the same failure this post describes, one layer down.

What Is the Difference Between an Instruction and a Control?

One asks, the other guarantees. The advisory sentence quoted at the top is the whole distinction, and Claude Code ships six mechanisms that sit at different points on it.

Path-scoped rules are the rung almost nobody has adopted. A file in .claude/rules/ with a paths frontmatter field loads only when Claude reads a matching file. Without that field it loads at launch like the rest.

So a rule about your API handlers costs nothing on the sessions that never touch them. It is the cheapest way to shorten a root file without demoting a rule to a skill.

The documentation is unambiguous about the top of that ladder, in its section on hooks: “Use hooks for actions that must happen every time with zero exceptions.”

It is equally clear about skills. They are for content that is “only relevant sometimes”, and Claude “loads them on demand without bloating every conversation”. Moving occasional workflows out of CLAUDE.md shortens the file without losing the instruction, which is the only kind of pruning that costs nothing.

That gives a test you can apply line by line. Ask what happens if the model ignores this line on a given run. If the honest answer is that something breaks, or something irreversible happens, then no amount of bolding fixes it, because the mechanism is wrong rather than the wording.

The docs reach the same conclusion in the fix they attach to over-specified files: “Ruthlessly prune. If Claude already does something correctly without the instruction, delete it or convert it to a hook.”

You can raise adherence at the margin. Adding emphasis such as “IMPORTANT” or “YOU MUST” is documented as a way to tune it. That moves a closer to one. It never makes a equal to one, and every rule you add still multiplies against it.

How Do You Tell Whether a Rule Is Being Followed?

This is the part the tooling does not answer, and it is worth stating plainly, because the same guidance that warns about bloat also asks you to do something it gives you no instrument for:

“Treat CLAUDE.md like code: review it when things go wrong, prune it regularly, and test changes by observing whether Claude’s behavior actually shifts.”

Code has tests. This file does not. Every other artefact in the stack has a verification path, and the one that encodes your conventions has none.

Both instructions in that sentence need a number you do not currently have. Pruning safely means knowing which rules are load-bearing. Testing a change means knowing adherence before and after. Both are per-rule questions, and neither is answerable by reading the file.

The failure is quiet, which is what makes it expensive, and it is quiet in both directions: HANDBOOK.md’s authors found agents that “report compliance they did not achieve”.

A rule that stopped working does not raise an error. It produces a slightly wrong commit message, a test written with a mock you had banned, a migration touched in a directory you had fenced off, spread thin enough to look like ordinary variance.

So the missing step is measurement against real runs. Take one rule, take the sessions that ran under it, and score whether the output honoured it. That turns the a in the joint-adherence arithmetic from a hypothetical into a number, one rule at a time.

# pip install ai-evaluation; needs FI_API_KEY and FI_SECRET_KEY
from fi.evals import evaluate

# One rule, scored against real session outputs rather than assumed.
RULE = "Prefer running single tests, not the whole suite."
session_transcript = open("session.log").read()   # what the agent actually did

result = evaluate(
    "prompt_instruction_adherence",
    prompt=RULE,
    output=session_transcript,
    model="turing_flash",
)

print(result.score, result.reason)  # a per-rule adherence signal, with an explanation

Score each rule separately rather than the file as a whole. A single number over a 3,000-word file tells you the file is imperfect, which you already knew. Per-rule scores tell you which lines to keep.

Where Does Future AGI Fit?

The measurement above is a built-in eval rather than something you assemble.

Prompt Instruction Adherence “assesses how closely a response follows prompt instructions, checking task completion and constraint compliance”. It takes a prompt and an output, and returns a score alongside a reason field in plain language.

The reason field is the part that matters for pruning. A score tells you a rule slipped. The explanation tells you whether it was ignored, misread, or quietly contradicted by another line in the same file.

Rules that are specific to one repository will not match a built-in template, and that is what custom evals are for. A custom template covers “any domain-specific, business, or regulatory rule you define”, written as criteria with Mustache placeholders such as {{output}} and {{context}}, mapped to your data at run time.

That covers the conventions that actually live in a CLAUDE.md: your branch naming, your test runner, the directory nobody may touch without a migration review.

Instruction Adherence sits under output quality and format among 156 templates across 14 groups, so the same run can score adherence next to the correctness checks you already care about.

One honest note on scope. This scores whether an instruction was followed in an output. It does not tell you the file was too long, and it will not choose between a hook and a rule for you. What it gives you is the per-rule number that makes both of those judgements evidence-based instead of instinctive.

Which Rules Belong in CLAUDE.md?

Keep the rules that are broad, that apply to every session, and that you can afford to have skipped occasionally. Code style, the test runner, branch naming, the environment quirk that is not visible in the code.

Move everything else. Rules that must happen every time become hooks, rules that must never happen become permissions, rules that matter only sometimes become skills, and rules that apply to one directory become path-scoped rules.

Move them deliberately, though. A rule relegated to a subdirectory CLAUDE.md is the one that goes quiet after compaction, so demoting a rule you actually care about buys shortness at the cost of the thing you were trying to protect.

Audit the file you did not write while you are there. Auto memory’s MEMORY.md loads alongside yours on every session and nobody prunes it, which makes it the likeliest place for a stale instruction to be sitting right now.

Then measure what is left, and delete what does not move behaviour. A rule that scores the same whether it is present or absent is not governing anything. It is paying rent on every session and taking attention from the rules that are.

Frequently Asked Questions About CLAUDE.md

How Long Should a CLAUDE.md File Be?

Anthropic’s documented target is under 200 lines per file, because longer files consume more context and reduce adherence. Pair that ceiling with the per-line test: ask whether removing a line would cause Claude to make mistakes, and cut it if not.

Treat 200 lines as a ceiling rather than a budget to spend. The real limit is how many rules the model holds at once, not how many bytes you sent.

Why Does Claude Ignore My CLAUDE.md Instructions?

Usually because the file is long and the rule is competing with everything else in it. The documentation names this failure directly: if your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise. Instructions are advisory rather than enforced, so nothing blocks a run that skips one.

Should I Use CLAUDE.md or a Skill?

CLAUDE.md for things that apply broadly, a skill for things that apply sometimes. There is a third option worth knowing: a path-scoped rule in .claude/rules/ loads only when Claude reads a matching file, which suits a convention that is specific to one directory rather than one workflow.

Do CLAUDE.md Instructions Survive Compaction?

A project-root CLAUDE.md does. The documentation is explicit that after compaction Claude re-reads it from disk and re-injects it. Nested CLAUDE.md files in subdirectories are not re-injected automatically, so rules pushed into subdirectories are the ones that go quiet. Anything that cannot be dropped still belongs in a hook, which runs regardless of what the context holds.

How Do You Test Whether a CLAUDE.md Rule Is Working?

Score adherence to that rule on real session outputs instead of reading the file and assuming. Anthropic’s advice is to treat CLAUDE.md like code and test changes by observing whether behaviour actually shifts, which needs a per-rule number. An instruction-adherence eval provides it one rule at a time, so pruning becomes evidence rather than guesswork.