propflowai/CLAUDE.md is 2,088 lines — about 82,000 tokens — loaded into
every session before anyone types. An earlier draft of this plan proposed cutting that
to ~8k "without degrading." That claim was too strong. This revision separates the part
that is genuinely free from the part that is a real trade, and names the four situations
where Claude will not see a relocated rule.
Move the reference tier only — 11,210 tokens, 14% of the file, none of which carries a behavioural rule. Then stop and measure whether adherence changes before touching anything that does.
The aggressive migration to ~8k is achievable, but it buys tokens we are not currently short of and costs four specific failure modes. That trade should be made on evidence, not on general guidance.
Anthropic's documented target is under 200 lines per CLAUDE.md, with the stated failure mode that "important rules get lost in the noise." At 2,088 lines we are ten times over. But that guidance is calibrated against the 200k default context window, where this file would consume 41% of everything available.
We run Opus 5 with a 1M window. The same file is 8%. That does not make the guidance wrong — noise-induced rule-skipping is real and is the reason the target exists — but it does mean the case for an aggressive migration rests on an adherence problem we have not measured, not on a context shortage we can demonstrate.
/doctor flags for trimming.
A third, unmeasured saving sits alongside Tier 1: incident forensics into HTML
comments. Block-level comments are stripped before injection, so they cost nothing
and stay on disk verbatim. The file carries 27 narrative markers — History:,
PR #…, "caught the hard way" — which are justification rather than
instruction. Keep one why-clause inline, comment out the archaeology.
Path-scoped rules load when Claude reads a matching file. Everything below follows from that one sentence. These are the honest costs of Tier 2.
Our workflow is explicitly plan-first: Hot Rule 8 is "plan before multi-file work",
and the ultrathink-first skill demands a written plan before the first
edit. Planning happens before reads, so path-scoped rules are structurally absent at
exactly the moment the most consequential decisions get made.
This is the strongest argument against the aggressive migration.
A brand-new .tsx is written, not read, so the UI rule never fires and
Claude reaches for a raw <table> instead of the arsenal
primitives — precisely the bug the section was written to prevent. A tripwire line
in the digest points at the rule, but a pointer is not the content.
Rules with paths: are dropped and only return when a matching file is
read again. In a long session an edit often follows a read from before the compact,
so the reload may never happen. Root CLAUDE.md and unscoped rules are re-injected
from disk; scoped ones are not.
A change spanning voice, temporal and tests loads three rule files at three different moments, in whatever order files happen to be opened. Today all of it is present from turn one. Part of the monolith's value is simultaneity, and no scoping mechanism preserves that.
| Mechanism | After compaction |
|---|---|
| Project-root CLAUDE.md, unscoped rules | Re-injected from disk |
| Auto memory | Re-injected from disk |
Rules with paths: | Lost until a matching file is read again |
| Nested CLAUDE.md | Lost until a file in that directory is read again |
| Invoked skill bodies | Re-injected — capped 5k tokens/skill, 25k total, oldest dropped first |
The documented remedy is blunt: if a rule must persist across compaction, drop the
paths: frontmatter or move it to the project-root file. So every invariant
whose violation is a bug — one source of truth, no fabricated numbers, no arms by
default — has to stay always-on regardless of how far the migration goes.
@path imports save nothingThe obvious refactor — split into files, import them back — buys organisation and exactly zero tokens. Imports expand and load at launch alongside the file referencing them, to a depth of four hops. Worth knowing before anyone spends a day on it.
After compaction a skill is re-injected but capped at 5k tokens, keeping the start of the file. Any runbook we convert must be ordered most-important-first as a correctness requirement, not a stylistic one.
We have 33 project skills plus roughly 100 user and plugin skills. The listing budget is
1% of the context window, and on overflow descriptions are dropped least-invoked
first. Converting sections into skills therefore does not add tokens — it competes
for a capped pool, and can silently strip the description off /smith-review
or /pull-link so they stop auto-triggering. That is a quality risk, not a
token risk, and it needs a /doctor reading before and after.
/context figures and /doctor's
skill-listing estimate, so any later claim about improvement has a before.InstructionsLoaded hook with matcher path_glob_match,
logging which instruction file loaded and why — session_start,
path_glob_match, compact. The only direct evidence that a rule
reached the session it was meant for.paths match at
least one real file. A glob matching nothing is a silently dark rule — the exact failure
this migration risks.skill_activated with OTEL_LOG_TOOL_DETAILS=1, to
catch listing-budget casualties.The placement rule, kept here for when the evidence justifies it. Ask in order, stop at the first yes.
| Question | Destination |
|---|---|
| Would violating it be a bug even if Claude never opens a matching file? | Root CLAUDE.md — survives compaction, reaches custom subagents |
| Must it hold every time, regardless of judgement? | A hook. Prose is advisory; "never push without asking" and "never run seed" are enforcement |
| Is it detail that only matters once you are already in the file? | .claude/rules/*.md with a paths: glob |
| Is it an invoked procedure with a name? | A skill, most-important-instructions first |
| Is it incident forensics or justification? | An HTML comment — zero tokens, preserved verbatim |
One further caveat for whoever picks this up: the built-in Explore and Plan subagents
skip CLAUDE.md and rules entirely, with no setting to change it, and we lean on them
heavily. That is true today as well, so it is not a regression — but it means conventions
a subagent must honour belong in the delegation prompt or a custom agent's
skills: preload, never in a rule.
| Figure | Value | Method |
|---|---|---|
| File size | 2,088 lines | wc -l |
| 207,200 bytes | wc -c | |
| 26,183 words | wc -w | |
| Token cost | ~82,160 | File reader; 2.52 bytes/token |
| Tier 1 reference | 11,210 tok | Section extraction at the same ratio |
| Fully-migrated keep-list | 8,328 tok | Same, incl. ~20 tripwire lines |
| Top ten sections | 1,142 lines | 55% of the file |
| Incident markers | 27 | Regex over narrative phrases |
| Share of 1M window | 8% | 82,160 / 1,000,000 |
Worth noting from the extraction: ## Important Rules is 19 lines but 2,388
tokens — 126 tokens per line. Line count is a poor proxy for context cost in this file,
and any future trim should be judged on bytes, not lines.