The CLAUDE.md instruction token threshold is 28 words, not 2,500.

1. Most guides quote the wrong ceiling

Search any variant of this question and the answer comes back the same: keep CLAUDE.md under 200 lines, or under 2,500 tokens, or under some other file-level cap. That advice is fine. It is also the wrong number to be quoting first, because a CLAUDE.md can pass the file ceiling and still fail every individual rule inside it.

The failure mode looks like this. The file is 1,500 tokens, well under budget. Five of the rules are 35 to 40 words each. The model reads the file every turn (that part the file-level guidance is right about), but for each of those five rules, the back half of the sentence falls off the attention curve. The rule appears to fire because the first half lands. Then an edge case shows up, the part that handles the edge case lives in the second half, and the agent does the thing the rule was meant to prevent.

You audit the file. The token count is fine. The rule is in the file. You assume the rule is working. The only signal that it is not is the regression you ship.

2. The exact code path

Here is the per-line check, copied unmodified from the analyzer that runs in your browser when you paste a file on ccmd.dev. No upload, no signup; the function is pure TypeScript and the file path is verifiable in the repo.

Three numbers in that block do load-bearing work and are worth calling out individually.

• 28: the strict word-count trigger. Lines with 28 words or fewer pass; 29 or more fire the finding.
• 25: the human-readable target in the message. This is what you set your editor soft-wrap at if you want zero findings without thinking about it.
• 0.35: the fraction of the line's tokens credited as recoverable savings when the rule gets split. Floor of est-tokens times 0.35. That is the empirical drop from rewriting a run-on as 2 to 3 short bullets.

3. Three thresholds, not one

CLAUDE.md has three different token thresholds the analyzer enforces. Conflating them is the single most common mistake we see.

The first is the threshold this page is about. The second is the one every other guide quotes. The third is the highest-leverage fix in the audit (one line move, full cache hit rate restored). All three live in the same analyzeConfig function and run on the same paste-and-score.

4. A worked example

Here is a single rule from a real CLAUDE.md that crossed the per-instruction threshold. The first version is one bullet, 47 words, one signal as far as the model is concerned. The fixed version is four bullets, each under 12 words, four signals. The token count of the fixed version is almost the same (the connectors and qualifiers drop, the body stays).

What changed in the model's view: four discrete signals instead of one. Each bullet has its own attention budget. "Run tests AND check snapshots" cannot get truncated because there is nothing else to the rule. The single-bullet version did get truncated in the field; the bug we wrote it to prevent (broken snapshots merged because tests alone passed) shipped twice before the rule got split.

5. What the report looks like

Paste any agent-config file into the analyzer and the per-instruction findings come back sorted by line. Five bloat lines on a 194-line file, each one named with its word count and the suggested fix. The savings number at the bottom is the sum of Math.floor(estTokens(line) * 0.35) across every bloat finding.

The $5.80 per engineer per month number is small on purpose. The per-instruction threshold is not where the dollars hide; the file-level threshold is. The per-instruction threshold is where the reliability hides. A rule that fires half the time costs you regressions, not tokens.

6. How to fix every line over the threshold

7. Why splitting beats shortening

The suggestion field is hard-coded to "split into 2-3 shorter directives, each one actionable." That is deliberate. The alternative (rewriting a 38-word rule into a 22-word rule) is what most people try first, and it underperforms.

The reason is shape. A 22-word rule still asks the model to track multiple constraints in one breath, just with fewer connectors. The back-half attrition drops, but the rule is still a single attention unit. Splitting the same content across three 8-word bullets gives the model three separate hooks. Bullets read as a list; the model treats list items as discrete signals. Tight prose reads as one sentence; the model treats it as one signal.

The same principle is why "## Always" lists outperform their paragraph equivalents in every CLAUDE.md we have scored. The per-instruction threshold is not really a word-count check. It is a shape check, expressed as a word count because words are easy to count.