Why Your CLAUDE.md Gets Ignored

CLAUDE.md gets ignored because instruction-following decays as rule count rises and prose has no enforcement. What to keep, cut, or mechanize.

Your CLAUDE.md gets ignored for two reasons that have nothing to do with how clearly you wrote it. The first is measurable: instruction-following accuracy falls as the number of instructions rises, and models are biased toward the instructions they read first. The second is structural: a rule written in prose is a request, not a constraint, and nothing in the system checks whether it was honored. If Claude is not following your instructions, neither reason is a wording problem, and writing the rule more emphatically does not change either fact. A CLAUDE.md is a budget, not a filing cabinet.

This argument points somewhere commercial, so: we build TLM Forge, which enforces spec-driven development inside Claude Code through gates rather than through instructions. That gives us an obvious interest in the conclusion that written rules underperform enforced ones. The research below is third-party and the failure modes of enforcement are covered honestly, including the ones in our own category. Read the sources and judge the framing yourself.

Why more rules means less compliance

Every rule you add lowers compliance on the rules already there. IFScale, a benchmark built to test how instruction-following degrades under load, evaluated 20 models across seven providers on a business-report writing task carrying up to 500 simultaneous keyword-inclusion instructions. Even the strongest frontier models reached only about 68 percent accuracy at 500 instructions. That is a writing benchmark, not a coding-agent study, and no CLAUDE.md carries 500 rules. What transfers is the shape of the curve, not the specific number, and the shape is not the same for every model.

Sources: How Many Instructions Can LLMs Follow at Once? The IFScale benchmark (arXiv)

There is more than one degradation curve

The paper found three patterns. The strongest reasoning models held near-perfect accuracy through roughly 150 instructions before dropping into a steeper slope with rising variance. Others declined linearly or exponentially from the start, and Claude Sonnet 4 sat in the linear group, the case where each rule you add does buy down compliance across the rest of the set. That was a July 2025 evaluation of a model two generations back, so read it as evidence that the linear pattern exists and not as a verdict on whatever you are running today. Which curve your model follows decides whether a long file costs you a little or a lot, and it is not a property you can read off the file.

The same work documents a positional bias: models satisfy instructions that appear earlier more reliably than ones that appear later. Hold that one loosely. The same paper measures the bias as close to zero at low instruction counts, peaking only around 150 to 200 instructions, which is far past what any real CLAUDE.md carries. So if your file opens with formatting preferences and closes with the rule about never committing secrets, you have ordered it backwards at a measured cost that is small. Ordering the file is close to free, so do it, but do not expect much from it. The rules whose violation costs the most still belong at the top, and the rules you would shrug at belong in the delete pile, not at the bottom.

Do CLAUDE.md files actually improve results?

A study from ETH Zurich and LogicStar.ai examined agent context files, the category Claude Code calls project memory, and found they do not generally improve task success rates while raising inference cost by more than 20 percent on average. Split that result by who wrote the file and it gets pointed. Context files the agent generated for itself dropped the resolution rate in five of the eight settings tested and added 20 to 23 percent to the cost of every run. Files a human developer had committed to the repository beat the generated ones for all four coding agents. The most valuable thing you can do to your CLAUDE.md may be to stop letting Claude write it. One of the two institutions here is a commercial coding-agent company, which cuts against the finding rather than toward it. The result that should sting most: repository overviews, the section most context-file templates open with, did not help agents reach the relevant files any sooner.

Sources: Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (arXiv)

The same paper carries the finding that most cuts against the argument here: instructions inside context files are, in its words, typically followed by coding agents. What it did not find was an overall task-success benefit. Its own explanation is that following the extra instructions makes the task harder, because agents explore more, test more and think longer, and that is where the cost goes. Then the authors ran the experiment that explains the whole thing. They stripped every other documentation file out of the repositories, re-ran the agents, and in that setting the generated context files improved success by 2.7 percent on average. A context file earns its cost exactly when it carries what the repository does not already say. The stronger claim, that redundant content crowds out the few rules carrying real information, is an inference this post adds; the paper measured the redundancy, not the crowding out. Two limits on the study itself: it covers Python only, and the authors note that a model's existing knowledge of Python tooling may be masking whatever effect context files have. Anthropic's own cost guidance points the same direction: keep CLAUDE.md under 200 lines and move standing procedures into skills, which load when they are relevant instead of competing for attention on every single turn.

Sources: Anthropic: Manage costs effectively (Claude Code docs)

Which CLAUDE.md rules to mechanize, and which to keep

Run the contract-or-judgment sort: put every line in your CLAUDE.md into one of two piles. The first pile is rules a machine can check: file paths, commit message shape, whether tests ran, whether a migration accompanied a schema change. The second pile is rules that require judgment: whether the abstraction fits, whether the change belongs in this module, whether the author understood the problem. Pile one should not be prose at all. Pile two cannot be anything else.

Pile-one rules become reliable once they move. The bigger gain is that every rule you delete is one fewer instruction competing with the ones you kept, which is the effect IFScale measures directly. A short file carrying only judgment-dependent guidance is a smaller ask than a long one where the same guidance sits far down the list. The measured effects are about instruction count and relative position, not line numbers, so read this as a direction of travel.

The honest problem with enforcement

Moving rules into hooks is not a clean win, and any vendor who tells you otherwise is selling. A hook can only evaluate what is mechanically observable, so the rules people care about most, architectural fit and whether the author understood the change, have no hook equivalent and stay advisory forever. Enforcement shrinks the problem without eliminating it.

The enforcement layer also has its own bugs. Claude Code's changelog records PreToolUse auto-allow hooks bypassing tool restrictions inside background agent tasks, which the entry scopes to summaries, compaction and renames, and single-segment allow rules like Edit(src/**) auto-approving writes to same-named directories anywhere in the tree rather than only under the working directory. Point releases 2.1.214 and 2.1.222 fixed them. Those are exactly the shape of failure that a team relying on hooks would not notice: the gate reported success while the restriction it existed to apply did nothing.

Sources: Claude Code changelog

How to shorten a CLAUDE.md

Shortening the file is subtraction in a fixed order: delete what the repository already says, convert what a machine can check, then rank what survives by cost of violation.

• Delete anything the model can read from the repository. Directory listings, the framework you obviously use, and the contents of package.json are not information.
• Delete anything you would not enforce in review. If you would merge the change anyway, the rule is decoration and it is costing you compliance elsewhere.
• Convert every mechanically checkable rule into a hook, a lint rule, or a CI gate, then remove the sentence from the file.
• Move situational procedures into skills or docs the agent loads on demand, so they are absent from the attention budget when irrelevant.
• Order what remains by cost of violation, highest first. The primacy effect is small at the rule counts a real file carries, so treat this as a cheap habit and not a fix.
• Re-read the file every month and delete one thing. Files grow by accretion and nobody owns shrinking them.

The trade is visible in a single line. Delete: this is a Next.js app with TypeScript and Tailwind, and source lives in src. Keep: do not add a new state library, because the Zustand migration is half-finished and a third store will make it unmergeable. The first line tells the agent what it would have learned from package.json in one read. The second is a constraint it could not have derived from the repository at all, and it changes what the agent plans rather than how it writes.

What earns its place in the file

After the deletions and conversions, what should remain is the category of thing an agent cannot derive by reading your code: the decisions behind the code. A repository shows you that a module talks to the payments provider through a queue. It does not tell you that the queue exists because the provider rate-limits aggressively during sales, that a previous synchronous version caused an outage, and that anyone proposing to call the API directly is repeating a mistake the team already paid for. That paragraph is worth more than 200 lines of style guidance.

Three things worth keeping

• Decisions with a reason attached. Not "use the repository pattern" but why this codebase uses it and what broke when it did not.
• Gotchas that look like bugs. The test that must run serially, the environment variable with a misleading name, the endpoint that returns 200 on failure. These cost hours to rediscover.
• Explicit non-goals. What the agent should not touch, not refactor, and not "improve" while passing through. Scope discipline is hard to infer and expensive to undo.

All three are facts about history and intent, not instructions about behavior. That is the distinction that survives the instruction-density problem. A fact informs the plan the agent forms before it acts, while a behavioral rule has to win attention at the exact moment of a specific tool call, competing against every other rule in the file, which is exactly the contest the benchmark data shows it losing as density rises.

Ask what happens if the agent does not follow a given line. If a check would fail, it belongs in the check. If a reviewer would object, route it to review. If the answer is that the agent makes a decision it would have made differently knowing something only your team knows, then and only then does it belong in the file.

What to do with the rules that cannot be automated

The judgment-dependent pile still needs somewhere to live, and the answer is not a longer file. It is a review step that runs against a written intent, performed by something that did not produce the change. This is the design behind TLM Forge: a spec audit that pins down what the change is supposed to do before code exists, and independent review of both the plan and the diff. The pitch is narrow on purpose. It gives the unenforceable pile a reviewer instead of pretending prose was ever going to carry it.

The teams who complain least about being ignored are not the ones with the most carefully worded files. They are the ones whose files are short because everything mechanical moved somewhere it could be checked, and whose remaining guidance is specific enough to change the plan. That is a smaller ask, and smaller asks get honored more often.

If you take one structural change from this post, make it the contract-or-judgment sort: every line in your CLAUDE.md is either a contract you should mechanize or a judgment call you should route to review. Very little of it deserves to stay as a sentence the model reads and probabilistically honors.