How to Audit and Fix a Bloated CLAUDE.md File

Every line you add to a CLAUDE.md file makes your agent slightly worse at following the lines already there. Anthropic's own Claude Code documentation is blunt about the failure mode: bloated CLAUDE.md files cause Claude to ignore your actual instructions (Anthropic, Claude Code best practices). Long-context research has repeatedly found that model performance degrades as input grows, well before the advertised window limit. A 2026 ETH Zurich evaluation pushed the point further. Repository context files raised inference costs by more than 20% on average without improving task success (Gloaguen et al., arXiv 2026). Rules files still earn their keep, but only when they are short, current, and tested. This guide walks through the audit that gets a bloated file back to that state. It also covers the point at which re-running the audit stops being worth it.

How Big Is Too Big for a CLAUDE.md File?#

Anthropic's official guidance targets under 200 lines per file, noting that longer files consume more context and reduce adherence (Claude Code memory docs). Cursor draws its line at 500 lines per rule and recommends splitting anything larger into focused, composable rules (Cursor docs). OpenAI's Codex is the bluntest of the three: it caps combined instruction files at 32 KiB by default and silently truncates whatever exceeds it (Codex docs). No vendor publishes a magic number, but every published ceiling sits at hundreds of lines, not thousands, and the failure arrives softly (ignored rules) long before it arrives loudly (truncation).

A working definition for the problem you are fixing: rules-file bloat is the buildup of stale, duplicated, or discoverable instructions in an agent rules file (CLAUDE.md, AGENTS.md, .cursorrules, or a Cursor rules directory) past the point where the file's length degrades the agent's adherence to the rules that still matter. The file keeps loading. The rules stop landing.

If you want the mechanics of how a file reaches that state, we traced the decay pattern in rules-file rot. What follows assumes you already have the symptom and want the fix.

How Do You Audit a Rules File for Outdated Instructions?#

The first half of the audit is subtraction. The ETH Zurich evaluation found that agents are surprisingly good at discovering repository structure on their own, and that codebase overviews, "although popular and recommended by model providers, are not helpful" (Gloaguen et al., 2026). Most bloat is content the agent never needed.

1. Measure what actually loads. Run /context in Claude Code to see the file's real footprint in the session, including nested files and imports, then compare the total against the 200-line target. This is the same attention budget that context rot drains in long sessions, so every stale line has a per-session cost. Codex users should measure against the 32 KiB combined cap, because overflow is dropped without warning.
2. Delete everything the agent can discover by itself. Apply the test Addy Osmani proposed in his February 2026 essay: can the agent find this by reading the code? If yes, delete it (Osmani, 2026). Directory trees, tech-stack inventories, and architecture summaries all fail this test. Claude Code's /doctor command now proposes these trims automatically: it cuts content derivable from the codebase and keeps pitfalls, rationale, and conventions that differ from tool defaults.
3. Verify each surviving rule against the current codebase. Run git log -p on the rules file and on the directories each rule describes, and compare dates. A rule last touched before the convention it encodes changed is a bug wearing documentation's clothes. Execute every command the file names; a build or test invocation that no longer runs is the easiest stale rule to catch and the most embarrassing to ship to an agent.
4. Remove contradictions and duplicates. Anthropic's memory docs warn that when two rules conflict, the model may pick one arbitrarily. Check across every scope that loads together: the user-level file, the project file, nested files in subdirectories, and any path-scoped rules. Two phrasings of the same rule are a maintenance liability; two conflicting rules are a coin flip.

How Do You Test Whether Your CLAUDE.md Rules Are Followed?#

Presence is not adherence. Anthropic's best-practices guide says to treat the file like code: review it when things go wrong, prune it regularly, and test changes by observing whether behavior actually shifts. The second half of the audit does exactly that.

1. Probe each rule with a task designed to trigger it. Start a fresh session, assign a small task where the rule should bind (a migration, if migrations have a rule; an API handler, if handlers have one), and watch what happens. A rule that survives every audit but has never been observed changing behavior is decoration, and decoration costs tokens.
2. Log corrections for one week. Every time someone re-types a correction in chat or review that the file already covers, record it. Repeated corrections mean the rule is not landing, and the usual cause is length: Anthropic's guidance states plainly that if the agent keeps doing something despite a rule against it, the file is probably too long and the rule is getting lost. A correction with no matching rule is your one legitimate reason to add a line.
3. Move hard constraints into enforcement. Rules files are advisory; hooks, linters, and CI are deterministic. Anthropic recommends hooks for anything that must happen every time, and OpenAI's Codex guidance reserves formatting and lint checks for CI. Anything that must never fail should not live in prose. What remains after this step is short and load-bearing, and lean files measurably pay off: a 2026 study across 124 pull requests found a well-scoped AGENTS.md cut median agent runtime by roughly 29% and output tokens by about 17% (Lulla et al., arXiv 2026).

Why Does the Audit Stop Scaling as Your Team Grows?#

The AGENTS.md format now appears in more than 60,000 open-source projects and is stewarded by the Agentic AI Foundation under the Linux Foundation (agents.md). The format spread faster than the maintenance practice behind it, and the audit above is that practice. Its cost grows on every axis your company grows on.

More engineers means more conventions changing per week, so step 3 has more drift to catch. More tools means more files, since Claude Code, Cursor, and Codex each read their own, and keeping several rules files in sync is a separate discipline with its own failure modes. A larger codebase means more candidate rules, and adding a line is always cheaper in the moment than probing one. A quarterly audit that took an afternoon for a 10-person team becomes an every-sprint chore for a 60-person one, and the sprint you skip is the sprint the bloat returns.

What Replaces the Recurring Audit?#

The audit produces, at real cost, a snapshot of your current conventions. The snapshot is the problem. Every answer the audit recovers already exists somewhere: the merged PR that changed the pattern, the review thread that rejected the alternative, the design doc that explains the constraint. A rules file is a hand-copied summary of those sources, and hand copies drift the day after you write them. Handing an agent the summary, or even the whole repo, is access, and access is not the same as understanding.

A context engine takes the other route. Unblocked provides institutional context for coding agents by synthesizing current conventions from the places they actually change: PRs, review comments, design docs, and tickets. One query spans code, discussions, tickets, and docs, and it surfaces decisions you would not have known to search for, including why the convention exists and what it replaced. The convention an agent receives is current as of the last merge, not the last audit. Whether you then keep a lean rules file at all, and for what, is the rules files versus context engine decision; the practical split most teams land on is a short file for hard constraints and retrieval for everything that moves.

Frequently Asked Questions#

How often should you audit a CLAUDE.md file? Quarterly is a reasonable baseline for a small team with a stable stack. A better trigger is behavioral: audit when the same correction shows up twice in a week, or when /context shows the file taking a meaningful share of the session window. Teams that retrieve moving conventions through a context engine mostly stop needing scheduled audits.

Does splitting a large file into imports fix bloat? No. Anthropic's docs note that imported files still load into context at launch, so imports reorganize the bloat without reducing it. Path-scoped rules are the exception: they load only when the agent touches matching files, which genuinely shrinks the per-session footprint.

Does the same audit work for agents.md and cursor rules files? Yes, all seven steps apply. Adjust the thresholds: Cursor's docs allow up to 500 lines per rule but push you to split into scoped rules, and Codex truncates combined instructions past 32 KiB, which makes step 1 urgent rather than optional.

Is a bigger rules file ever worth it? The 2026 evidence is mixed in an instructive way. Agents reliably follow explicit, specific instructions, yet the ETH Zurich evaluation found context files raised costs over 20% without lifting overall success, while the Lulla study found lean files made agents meaningfully faster. Specific-and-short beats comprehensive in every result published so far.

What are the clearest signs of rules-file bloat? Corrections that repeat despite a written rule, commands in the file that no longer run, contradictions between user-level and project-level scopes, and a file that has crossed the 200-line target without anyone deciding it should.

Run the Audit Once, Then Stop Scheduling It#

Run the seven steps once and you will probably delete a third of the file. You will fix a handful of stale commands and watch adherence improve within a day. That result is worth having. Then look at your calendar before you book the second pass. The durable question is not how to keep auditing but which knowledge belongs in a hand-maintained file at all. Hard constraints, few and testable, stay in the file. Conventions that move belong in a system that reads the sources they move in. That is what a context engine is for. It is the difference between a file that described your team last quarter and context that keeps up with it. If audit number two is already scheduled, treat that as the finding. Change the system, not the calendar.