The goal is not to hit an arbitrary target. It is to prove that critical instructions load, remain internally consistent, and produce observable behavior.
1Measure bytes, not visual length
Line count and editor pages do not tell you the byte size a loader sees.
Check
wc -c CLAUDE.md
wc -l CLAUDE.md
shasum -a 256 CLAUDE.md
Record the byte count and hash. Compare the byte count with the current runtime documentation and active configuration, not with an assumed universal limit.
Fix
If the file approaches or exceeds a verified runtime boundary, reduce it or change a documented configuration deliberately. Re-measure after every edit and keep the verified hash with your check record.
2Test whether rules near the tail are actually available
A successful read of the beginning does not prove that the end was loaded.
Check
tail -n 100 CLAUDE.md
grep -n '<unique-critical-tail-rule>' CLAUDE.md
Start a new read-only agent session in the intended directory and ask:
Restate the rule containing <unique-critical-tail-rule> and identify the instruction file it came from. Do not edit files.
Fix
Move critical operating rules toward the beginning and repeat the fresh-session probe. Do not rely on the current conversation to confirm a file change.
3Find repeated instructions before deleting unique rules
Repeated long rules waste document budget and drift when only one copy is updated.
Check
sort CLAUDE.md | uniq -d
grep -nEi '\b(always|must|required to|never|must not|do not)\b' CLAUDE.md
Group matching instructions by purpose. Look for a positive and negative directive that share the same action without conditions or precedence.
Fix
Keep one canonical instruction for each behavior. Refer to it from related sections. Add conditions and precedence where strong directives overlap; do not preserve contradictions merely because both sound important.
4Remove text that looks structured but has no operational body
Empty headings and present-tense policy claims consume space without giving the agent a checkable action.
Check
grep -nE '^#{1,6}[[:space:]]+' CLAUDE.md
grep -nEi '\b(always|automatically|now)\b|\b(is|are|gets?) (checked|verified|validated|enforced)\b' CLAUDE.md
Inspect the lines after every heading. Map each enforcement claim to a script, test, hook, checklist owner, or explicit manual step.
Fix
Delete empty sections. Rewrite policy narration as a trigger, action, and observable result. Move background explanations and reference material outside the core operating rules when your project structure supports it.
5Protect verification and completion rules during compression
A shorter file is worse if it deletes the evidence gate that made the remaining instructions testable.
Check
grep -nEi '\b(verify|validate|test|lint|typecheck|check|exit code|git diff --check)\b' CLAUDE.md
grep -nEi 'DONE:|FAILED:|HUMAN_ACTION_REQUIRED:|acceptance criteria|completion (criteria|marker|means)' CLAUDE.md
grep -nE '\b(N/A|TODO|TBD|UNKNOWN)\b|=[[:space:]]*[?]' CLAUDE.md
Fix
Retain the exact verification command, required evidence, and terminal states. Replace placeholder-tolerant existence checks with value-shape checks or explicit error states.
6Verify that shortening did not remove a critical rule
File-size reduction is not success unless the intended operating contract still survives.
Check
git diff -- CLAUDE.md
git diff --check -- CLAUDE.md
wc -c CLAUDE.md
shasum -a 256 CLAUDE.md
Map each critical rule to a surviving line, then repeat the fresh read-only recitation check for both early and late rules.
Fix
Restore any lost requirement, compress explanation instead of enforcement, and record the new verified hash only after the fresh session can restate the critical rules.