Why Claude skips rules in your CLAUDE.md

Firing is not the same as following. Every line of CLAUDE.md gets concatenated into the system prompt at session start and re-sent on every turn for the session (the analyzer codifies this at src/lib/analyzer.ts line 264 as estimatedTokensFireEveryTurn = totalTokens). So the bytes are always there. But six specific line shapes make a rule unfollowable even when the model reads it: lines over 28 words (the second half gets dropped), 14 vague words like 'appropriately' (no testable success condition), 6 absolutes like 'always' without an escape clause, prohibitions missing a 'Why:' that names the constraint, duplicates, and conflicting absolutes. Each one is detected per-line by ccmd's analyzer.

Yes, it reads it. The file is in the system prompt for every turn. 'Read' is the wrong verb to anchor on. What matters is whether a specific rule survives the model's pass over the system prompt and ends up gating an action. A 38-word stack paragraph is in the prompt and is also functionally invisible because the model treats long sentences as one signal and the middle gets compressed away. The fix isn't to remove the rule. It's to reshape it so the model can't compress it.

It's empirical. The constant lives at src/lib/analyzer.ts line 150. Rule lines over 25 words consistently get treated as one signal by the model, and the second half of the line tends to be dropped. 28 is the comfortable upper bound before the failure mode starts to dominate. Split a 34-word stack paragraph into three 8-word rules and the agent follows all three; leave it as one sentence and Claude follows the first half and silently skips the rest.

Real codebases have exceptions to almost every absolute. When the model reads 'always write clean code' and then encounters a one-line throwaway script where over-engineering would be wrong, it has no resolution path. It can't ask, so it picks one and moves on, often by silently dropping the rule. The analyzer's aspirational detector at line 177 fires when it sees one of six absolutes (always, never, must, should always, in all cases, every time) on a line under 25 words that doesn't contain an exception (unless, except, but if, when X then). Add the escape clause and the model has a procedure for resolving the edge case.

Prohibitions without a stated reason get followed in the easy cases and dropped in the edge cases. The analyzer's missing_why detector at line 227 scans every line starting with DO NOT, NEVER, or don't, then looks at the next 4 lines for one of seven tokens (because, why, reason, past, got burned, incident, happened, caused). If none of them appear, the finding fires. 'NEVER commit secrets' alone gets followed in the obvious case (a literal API key in code) and skipped when the model sees a config-shaped secret that's already in an .env-like file. 'NEVER commit secrets. Why: leaked Stripe key in March 2026.' gets followed in both cases because the model can pattern-match against the named incident.

Yes, in two ways. First, the duplicate burns tokens every turn (the analyzer's duplicate finding at line 207 sets tokenSavings to the full line, not a fraction). Second, duplicate rules create the false impression of redundancy without resolution: when the duplicates have slightly different wording, the model has to decide which version applies and frequently picks the weaker one. Single canonical phrasing wins.

The model has no resolution path. The analyzer ships one example at src/lib/analyzer.ts line 244: a file containing both 'never use comments' and 'add comments' triggers the conflict finding because there's no scoping logic to tell the model which rule applies when. In practice the model picks one rule per turn and silently drops the other. Either rule can be the one that gets skipped, depending on what else is in the prompt. Scope the rules ('never use comments in business logic; document public exports') or pick one.

There's research suggesting attention is U-shaped over long contexts and rules in the middle get less weight. The analyzer doesn't detect this directly because it can't tell where the middle of your conversation will be. But you can hedge: put the rules that must survive every turn at the top or bottom of CLAUDE.md, not buried in the middle. The 'cache_bust' detector at line 193 indirectly addresses this by forcing volatile text (which mostly appears at the top) to move elsewhere.

Sometimes. Aspirational lines with no escape clause and no concrete test fire, fail to resolve, and waste bytes. Delete or rewrite. But for rules that genuinely matter (security prohibitions, stack constraints, hard prohibitions with a named past incident) the fix isn't deletion. It's either reshaping the line (split, add 'Why:', add 'unless') or moving the rule to a different firing surface where it loads only when relevant (a skill .md, a settings.json hook, or an MCP tool description). The analyzer flags candidates; the user decides which lane.

Paste your CLAUDE.md, AGENTS.md, .cursorrules, or .grokrules into the textarea on ccmd.dev. The analyzer runs entirely in your browser, no upload, no signup. You'll see total tokens, the Karpathy 12-rule pass rate, and a line-by-line list of findings. The six skip-cause checks (bloat, vague, aspirational, missing_why, duplicate, conflict) cover most of the file shapes that cause silent rule skipping. Same detector across all four file formats; detection is by content, not filename.