harness-diet — put your always-loaded context back under budget
A harness gains weight automatically (every incident note, every boss directive, every fix lands
as another paragraph in an always-loaded rule) but only loses weight when someone runs a diet.
Field measurement on a mature harness: growth-to-reduction commit ratio of ~60:1, natural growth
of ~70KB/month, and adherence degrading as the pile grows. Anthropic's guidance is blunt:
"target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce
adherence", and rules without paths frontmatter load "with the same priority as CLAUDE.md"
— every session, every token (memory docs).
Result you should expect: one field run took a harness from 146KB always-loaded (143% of
budget) to 100.6KB (98%) with zero governance loss — every killswitch, decision table,
trigger keyword, and canonical command verified present after the diet.
Budgets (defaults — override via flags)
| Metric | Budget | Why |
|---|
| CLAUDE.md | < 200 lines | Anthropic official guidance |
| Per always-loaded rule file | 8,192 B | Keeps any single rule scannable; forces narrative out |
| Total always-loaded rules | 102,400 B | Attention-budget ceiling; beyond this, adherence drops |
Bundled script paths: commands below use $HOME/.claude/skills/harness-diet/… (the
install.sh layout). For marketplace (/plugin install) installs, resolve under
${CLAUDE_PLUGIN_ROOT}/skills/harness-diet/… instead. The scripts are stdlib-only Python;
if unavailable, perform the step manually from the described contract.
Phase 0 — Measure
DIET="$HOME/.claude/skills/harness-diet" # or "${CLAUDE_PLUGIN_ROOT}/skills/harness-diet"
python3 "$DIET/scripts/harness_diet_audit.py" # human summary
python3 "$DIET/scripts/harness_diet_audit.py" --json # machine output
python3 "$DIET/scripts/harness_diet_audit.py" --strict # exit 2 if over budget (CI/ratchet)
Auto-discovers ./.claude/rules, ~/.claude/rules, and CLAUDE.md files at project/user level.
A rule is always-loaded iff its YAML frontmatter has no paths: key.
Phase 1 — Classify every always-loaded rule
Walk the list from largest to smallest and pick one bucket per file:
- Keep always-loaded — cross-cutting behavior needed in every session (tone, security
boundaries, routing indexes). Diet the body (Phase 2) but keep the load class.
- Path-scope — the rule only matters when specific files are touched. Add
paths: globs.
⚠ Path scoping fires on file access, never on spoken keywords. A rule triggered by what the
user says cannot be path-scoped. ⚠ No literal brackets in globs ([locale] parses as a
character class and silently never matches).
- Convert to skill / hook-injected — task-specific procedure? Official guidance: "use
skills instead". Best case: the rule's real trigger is already a deterministic hook — have
the hook inject "Read <rule> first" into context and drop the always-load.
- Migrate narrative to reference — the default for oversized keepers (Phase 2).
Phase 2 — Migrate (block-level, never prose compression)
For each oversized file:
- Extract a preservation manifest first (before touching anything):
python3 "$DIET/scripts/preservation_check.py" extract rules/big-rule.md > /tmp/big-rule.manifest.json
- Append the outgoing blocks to
references/<name>-ref.md (or your repo's reference dir),
verbatim under a dated section header. Append before rewriting the rule body, and commit
both together — a slimmed body pushed without its reference content is a content hole for
every mirror that pulls in between.
- Rewrite the rule body: keep the verdict skeleton (what to do / never do), leave a one-line
pointer to the reference for the "why" and the war stories.
Must stay in the body (never migrate): CRITICAL/IMPORTANT banners and their verdicts,
decision tables, trigger keywords and agent names (they are a routing index, not prose),
killswitch env vars, canonical command lines, IDs and threshold values.
Migrate aggressively: incident narratives, measurement history, duplicated explanations of
the same point, long example blocks, anything already present in the reference file.
Phase 3 — Verify (two lenses, fresh checker)
- Loss lens (deterministic):
python3 "$DIET/scripts/preservation_check.py" verify rules/big-rule.md /tmp/big-rule.manifest.json
Exit 2 = something load-bearing got migrated. Restore it before proceeding. Review the
manifest by hand first — prune entries that were intended to move.
- Efficacy lens: re-run the audit; recompute the total; confirm the savings are real
(reference files are lazily
Read, not @-imported — check the rule bodies contain no
@path imports of the reference, or the "savings" still load at launch).
- Fresh checker: hand the diff to an independent reviewer that didn't write it (pairs with
the
review-loop skill). Diets fail quietly: a plausible-looking slim body missing one
qualifier is exactly what the maker cannot see.
Phase 4 — Guard (keep it off)
A diet without a guard regrows. Ship-with options in $DIET/hooks/:
rules-budget-guard.sh — PostToolUse (Edit|Write) advisory: the moment a rule edit pushes a
file past budget, the editing session gets a context note telling it to migrate, not append.
Non-blocking by design — a blocking pre-commit gate silently stalls auto-commit pipelines.- Re-run
--strict weekly (cron, session-start dispatcher, or CI) and surface the report only
when over budget.
Anti-patterns (each one cost a real harness a failed round)
| Anti-pattern | Why it fails |
|---|
| Prose compression ("tighten the wording") | Trigger keywords, guru names, stage names are the routing index. A compression pass that saved 12% destroyed 70% of routing signals and was fully reverted. Move blocks; don't rewrite sentences. |
| Dedup toward a private file | If rules are distributed to a team but ~/.claude/CLAUDE.md is one person's, "delete from rules, it's already in CLAUDE.md" deletes it from every teammate's context. Dedup toward the shared surface. |
| Slim body committed, reference append not | Mirrors pull a body full of dangling pointers. Commit both in one change. |
| Trusting the maker's "everything preserved" claim | Extract the manifest before the edit and verify after. Field run: the maker claimed "6 bullets kept verbatim"; the deterministic check found two qualifiers gone. |
| Treating one diet as the fix | Growth is automatic; reduction is manual. Without the guard, one measured harness regrew from 145KB toward its 220KB peak within weeks. |
References
references/methodology.md — budget rationale, growth mechanics, byte-accounting worksheet,
verification lens design, worked field results.