Cutting the CLAUDE.md rules Claude ignores
You saw a thread that said cut your CLAUDE.md by 80 percent, or you watched Claude skip a rule for the fifth time and decided the rule was dead. The standard advice agrees with you: Anthropic's guide says "if Claude keeps doing something you don't want despite having a rule against it, the file is probably too long and the rule is getting lost," and the fix it offers is to ruthlessly prune. That advice is right about the disease and wrong about the treatment for most lines, because the rules Claude ignores and the rules that are safe to delete are two different sets that only partly overlap.
Here is the trap. The line you are tempted to cut is the one Claude keeps skipping. But a rule gets skipped for a reason, and the reason is usually that the line is unfollowable, not that it is unnecessary. "Never commit secrets" gets skipped at edge cases because it has no stated reason and no teeth, not because you do not want it enforced. Cut it and you have deleted a rule you needed, kept the duplicate three lines down, and saved fewer tokens than you think.
The one number that decides it
Every finding the analyzer produces lives in src/lib/analyzer.ts, and each one can carry a tokenSavings field. Whether the field is set, and to how much, is not cosmetic. It is the cut-versus-keep verdict written into the data.
Read it top to bottom. The duplicate and cache_bust detectors set token savings to the whole line, because deleting a repeated rule or a "Today is" timestamp costs you nothing. bloat sets it to 35 percent, which is the analyzer saying split this run-on and keep about two thirds of it. And the four detectors that fire on the rules Claude actually ignores (vague, aspirational, missing_why, conflict) set no savings at all. The headline potentialSavingsTokens adds up only the cut-and-split lines, so the analyzer literally credits you zero tokens for cutting the ignored rules. It will not pretend deleting them helped.
The triage, kind by kind
Seven finding kinds, three verdicts. The verdict follows the savings, and the savings follow whether the rule was redundant or just badly worded.
| Finding | Why it fires | Token savings | Verdict |
|---|---|---|---|
| duplicate | Already covered by the first copy | full line | CUT |
| cache_bust | A timestamp is not an instruction | full line | CUT |
| conflict | One half could never be satisfied | one half | CUT |
| bloat | Over 28 words, so it gets skimmed past | 35 percent | SPLIT |
| vague | No testable meaning, agent cannot tell when it won | 0 | KEEP + RESHAPE |
| aspirational | Absolute with no exception, so it breaks on the first edge case | 0 | KEEP + RESHAPE |
| missing_why | Prohibition with no reason, so the agent guesses at edge cases | 0 | KEEP + RESHAPE |
Four of the seven kinds carry no savings, and those four are exactly the shapes that make a rule get ignored. So when your instinct says "cut the ignored rules," the analyzer is pointing at the opposite column. The ignored rules are the keep column. The cut column is the redundant rules you were not even thinking about.
Run it on a file you would actually want to trim
Here is a seven-line file with five rules. Three of them are the ones Claude has been skipping, one is a verbatim duplicate, and one is a session timestamp. Watch where the savings land.
is the honest cut budget for this file, and all of it comes from the duplicate (11) plus the timestamp (12). The three rules Claude was ignoring save 0 tokens if you delete them, because the analyzer never credited them. Cut them and you spend a real rule to save nothing.
What blind-cutting costs you
Same file, two ways to clean it. Toggle between the instinct and the triage.
Delete every ignored rule, or sort by token savings
You delete the three rules Claude kept skipping, plus the duplicate and the timestamp while you are in there. The file is shorter and feels cleaner.
- Deleted "Never commit secrets", a real rule, gone because it had no Why:
- Deleted "handle errors appropriately" instead of making it testable
- Saved 23 tokens you would have saved anyway from the duplicate and timestamp
- Net result: three live rules lost, same token savings
When cutting an ignored rule is the right move
The argument is not "never delete." It is "let the savings number decide." There are three honest cases where an ignored rule should go:
- It is a duplicate of a rule that already exists higher up. The original still fires; the copy is pure noise. Full-line savings, cut it.
- It is one half of a conflict. "Never use comments" three lines above "add comments to every function" means the model was always dropping one of them. Pick the one you mean, cut the other.
- The rule describes something Claude already does without being told. Anthropic's guide is blunt about this one: if removing the line does not change behavior, it was never carrying weight. That is the heuristic doing its job, and it is the case the token number cannot see for you, so you still have to ask it.
Everything outside those three cases is a rewrite. A vague rule becomes a concrete one. An absolute gets an "unless." A bare prohibition gets a reason. You are not keeping the line out of sentiment; you are keeping it because the token-savings field said cutting it buys you nothing, and the rule was supposed to do real work. For the why-it-got-ignored side of this, see why Claude skips rules in your CLAUDE.md; for the pure deletion list, see how to prune dead rules.
Not sure which ignored rules to cut?
Bring your CLAUDE.md. In 15 free minutes we sort it live: the full-line cuts, the splits, and the ignored rules that need reshaping instead of deleting.
Frequently asked questions
Should I delete a rule that Claude keeps ignoring?
Usually no. The instinct is understandable: the rule is not working, so cut it. But the rules Claude ignores most are vague ("handle errors appropriately"), absolute with no exception ("always write clean code"), or a prohibition with no reason ("never commit secrets"). ccmd's analyzer assigns those three kinds zero token savings on purpose, because cutting them does not buy you anything except the loss of a rule that was supposed to be doing real work. The rule was ignored because of how it reads, not because it was worthless. Reshape it. The only ignored rules safe to cut outright are duplicates and stale timestamps, which the analyzer flags with full-line savings.
What is the tokenSavings number and why does it tell me whether to cut?
Every finding the analyzer emits at src/lib/analyzer.ts can carry a tokenSavings field. Two finding kinds set it to the whole line: duplicate (tokenSavings: estTokens(line)) and cache_bust (the stale-timestamp detector). Those are safe full-line cuts. The bloat detector sets it to Math.floor(estTokens(line) * 0.35), which is the analyzer telling you to split the line and keep about two thirds. The vague, aspirational, missing_why, and conflict detectors set no tokenSavings field at all. So the number is the verdict: full line means cut, 35 percent means split, nothing means keep the rule and fix the line.
Anthropic's own guide says to prune rules Claude ignores. Are you disagreeing?
Not exactly. The official best-practices guide says, for each line, ask "Would removing this cause Claude to make mistakes? If not, cut it," and notes that bloated files cause Claude to ignore your actual instructions. That heuristic is correct, but it is a thought experiment: you have to imagine, or actually run, the sessions to find out whether removing a line changes behavior. The analyzer turns that question into a static answer you get from one paste. It also catches the case the heuristic misses: a rule that does matter but is skipped because it is vague or has no escape clause. Removing that line would cause mistakes, so the heuristic says keep it, but most people cut it anyway because it looked like dead weight. The token-savings number stops you.
How does the analyzer know a rule is being ignored from the text alone?
It does not literally watch your sessions. It matches the line against the shapes that make a rule unfollowable: lines over 28 words (bloat), terms with no testable meaning like "appropriately" or "properly" (vague), absolutes like "always" and "never" with no "unless" clause (aspirational), and prohibitions with no reason attached (missing_why). These are the patterns that correlate with rules getting skipped. The detector kinds and their word lists live in plain sight in src/lib/analyzer.ts, so you can read exactly why a given line was flagged.
If I reshape an ignored rule instead of cutting it, does the file not just stay long?
Reshaping rarely makes a rule longer. "Always write clean, well-structured code" becomes "Functions under 40 lines; no nested ternaries," which is shorter and testable. "Handle errors appropriately" becomes "Wrap external calls in try/catch; never swallow an error silently." You are trading a vague sentence the model ignores for a concrete one it can follow, usually at the same or lower token count. The lines you actually delete for length are the duplicates, the timestamps, and the bloated 28-plus-word run-ons (split, keep the useful third).
What is the worst rule to cut by accident?
A security or stack prohibition that was ignored only because it had no "Why:" line. "Never commit secrets" reads like a throwaway and the model skips it at edge cases, so it lands on your cut list. But it is the single rule you least want gone. The analyzer flags it twice (aspirational and missing_why) and assigns it zero token savings both times, which is the signal: this is not dead weight, it is a live rule wearing a bad disguise. Add the one-line reason and an escape clause, do not delete it.
How do I run this on my own CLAUDE.md?
Paste your file into the box on ccmd.dev. The analyzer runs entirely in your browser, no signup and no upload. You get the per-line findings with each one's suggestion verb and token-savings number. Sort by that number: full-line and 35 percent findings are your real cut and split list, and the zero-savings findings are the ignored rules to reshape. The same detectors run on AGENTS.md, .cursorrules, and .grokrules, since detection is by content, not filename.
Paste your file into the analyzer at ccmd.dev to see the token-savings number on every line. It runs in your browser; nothing is uploaded.
Comments (••)
Leave a comment to see what others are saying.Public and anonymous. No signup.