Skip to content

Build1 publisher3 min readPublished

Routing a 194,492-character CLAUDE.md by failure cost left 47 rules resident

A dev.to write-up cut a 194,492-character CLAUDE.md to 17,283 by changing what triggers each rule to load, sorting them by what breaks if one stays unloaded at the moment it matters. The harness that checks the result runs one headless Claude Code session per prompt.

The Engineer · Build desk

Illustration accompanying Routing a 194,492-character CLAUDE.md by failure cost left 47 rules resident

What happened

  • A repo's CLAUDE.md ran to 194,492 characters, about 48,600 tokens, and loaded on every single message rather than once per session.
  • The restructure left a 17KB CLAUDE.md plus 12 skills and 28 reference files, loaded either by model judgment or by glob match on the paths being edited.
  • The measurement harness launches one real headless Claude Code session per prompt, each consuming API quota and taking several minutes.

Compiled by The EngineerSomething wrong?How this is made

Why it matters

  • decision Sorting rules by importance gets you nowhere when every line is important, so the routing decision becomes a question about the loader failing: what happens if this rule is absent exactly when it is needed.
  • exposure Anything moved into a skill now depends on the model matching a description, so a rule in that tier can be missing at the moment it applies without anyone seeing a failure.
  • cost Checking the restructure is billed per prompt in API quota and minutes. The regression suite is a recurring line item.
  • constraint The verbatim-lift method only works on rules already written with the rule as their first sentence; a repo of prose notes has to be re-read against the code before anything can be moved safely.

The saving came from the load trigger. CLAUDE.md is resident, so every character in it loads on every message [2]. A skill loads when the model judges its description relevant, and the author is explicit that this is a judgment [8]. A rule file under `.claude/rules/` with `paths:` frontmatter loads by glob match on the files you touch, with no model judgment involved [7].

`@import` is not worth doing for the same reason. Imports expand inline: you get a tidier file and identical context cost [6]. Deleting was ruled out too, because you cannot know which lines are stale without re-reading the code each one describes [28].

Importance could not sort the file, since all of it was important [24]. The author's test is a failure question instead: "If this rule failed to load exactly when it mattered, how bad is that?" [10]. A styling trap costs time; a security rule ships the bug it exists to prevent [11]. So all 26 security rules stayed resident, along with 21 architectural invariants and the commands [12], while fees, booking, notifications, the mobile apps, the rendered pages, test practices and the known-gaps list moved out [13]. The two resident groups add to 47, the number of rules the write-up says the roughly 200-line file states [25].

Compressing 47 unverified rules into one-liners is the move the piece argues hardest against, because the output would be 47 confident-sounding claims nobody checked, looking freshly reviewed [15]. The author quotes his own repo's guidance, written after getting burned: "A stale claim that gets edited without being checked is laundered, not corrected. Re-read the code the line describes, or leave the line alone." [16]. The workaround is mechanical. Lift the rule's existing opening sentence verbatim and push the reasoning one hop away [17]. The Stripe entry keeps one sentence in CLAUDE.md, saying the card never touches this server, that a SetupIntent hands the browser a client secret and Stripe's own SDK collects the number, and that this is why no endpoint here takes one [19], and parks the other 400 words in `hard-rules/references/security.md` [18].

For the 91% figure to transfer, your rules have to already be written with the rule as the first sentence; the author says his were [17]. The disclaimer says the scripts were generated with AI assistance and the workflow was tested end to end on one repository, with all quoted numbers from that run [22]. On size, the old file was about 4.9 times the point at which Claude Code warns about a memory file [3], which puts that threshold near 39,700 characters and leaves the 17,283-character replacement at roughly 44% of it [26].

Verification is metered. The harness launches real headless Claude Code sessions, one per prompt, each consuming API quota and taking several minutes, and the author suggests starting with two or three prompts before running twenty [20]. It also rewrites CLAUDE.md in place and creates files under `.claude/`, so commit first [21]. The four words lost in the cut were all from headings deleted on purpose [4]. That count is a measure of text, not of behaviour. The published text explains how to run the harness but does not include its results [29], though the author calls the measurement "the most useful part and the part nobody writes about" [23].

What to watch

  • Whether a later version of the write-up publishes the harness output per prompt, so the 12 skills and 28 reference files can be checked for misses.
  • Whether glob-triggered rules fire when the agent edits files outside the matched paths, such as generated or vendored code.
  • Whether Claude Code changes its memory-file warning size or its skill-description matching, since both defaults set this design.
Loading claim ledger
Loading source directory links
Loading share composer
Loading topic controls
Loading related stories