Skip to main content
skill CX Codex

harness-diet — Claude Code skill: trim always-loaded context

harness-diet — a Claude Code skill that measures the always-loaded context of a harness and pulls it back under budget. Runs when CLAUDE.md and always-on rules have piled up.

MIT ★ 880 updated 2026-09-03

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sangrokjung/claude-forge --skill harness-diet -a claude-code
Open on GitHub

What harness-diet does

The skill targets CLAUDE.md and rule files whose YAML frontmatter has no paths: key, since those load in every session. A bundled harness_diet_audit.py script discovers them at project and user level and reports the volume. Each rule then goes into one bucket: stay always-loaded, get path scoping, become a skill or hook-injected rule, or hand its narrative to a reference file.

Narrative moves in blocks, never through prose tightening. A preservation manifest comes first, then the outgoing blocks are appended to references/<name>-ref.md, and only after that the rule body is rewritten. Verdicts, decision tables, trigger keywords, killswitch variables and canonical commands stay in the body. preservation_check.py compares the body against the manifest.

Default budgets: CLAUDE.md under 200 lines, a single rule file up to 8,192 bytes, always-loaded rules together up to 102,400 bytes. To keep the diet from undoing itself, hooks/rules-budget-guard.sh listens on Edit and Write and nudges the session to migrate a block instead of appending. The scripts need Python 3.

What it helps with

  • measure always-loaded harness context and spot the overrun
  • move incident narratives out of an oversized rule into a reference file
  • switch a rule to path-scoped loading with paths:
  • confirm no killswitch or trigger keyword was lost in the diet
  • add a hook that stops rules from regrowing

Example prompts for the agent

  • Run harness-diet and show how much always-loaded context the harness carries
  • Go through the biggest rules without paths and tell me what moves to reference
  • Check rules/big-rule.md for anything lost after the block migration

How to install harness-diet

1Skills CLI (Vercel)

npx skills add sangrokjung/claude-forge --skill harness-diet -a claude-code

2Manually: put the files in place

~/.claude/skills/harness-diet/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/harness-diet/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about harness-diet

How do I install harness-diet in Claude Code?

Run npx skills add sangrokjung/claude-forge --skill harness-diet -a claude-code. The skill lands at ~/.claude/skills/harness-diet/SKILL.md.

What does harness-diet do?

It counts the always-loaded volume of CLAUDE.md and rules without paths, moves narrative into reference files, converts rules to path-scoped or skill-triggered loading, and checks the body against a manifest.

What is required for the skill's scripts to run?

Python 3. Both harness_diet_audit.py and preservation_check.py use only the standard library. Without it you follow the described contract by hand.

Source text

SKILL.md · MIT
---
name: harness-diet
description: Measure and shrink the always-loaded context of a Claude Code harness (CLAUDE.md + rules without paths frontmatter) back under budget — migrate narrative to reference files, convert rules to path-scoped or skill-triggered loading, and verify zero governance loss with deterministic preservation checks. Use on "harness diet", "context diet", "rules diet", "CLAUDE.md too long", "always-load budget", "trim my rules", "context bloat", "하네스 다이어트", "룰 다이어트", "컨텍스트 다이어트", "always-load 줄여줘". Not for one-off prose editing or project docs cleanup.
license: MIT
metadata:
  category: harness-maintenance
  phase: v1
---

# 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](https://docs.claude.com/en/docs/claude-code/memory)).

**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

```bash
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:

1. **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.
2. **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).
3. **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.
4. **Migrate narrative to reference** — the default for oversized keepers (Phase 2).

## Phase 2 — Migrate (block-level, never prose compression)

For each oversized file:

1. **Extract a preservation manifest first** (before touching anything):
   ```bash
   python3 "$DIET/scripts/preservation_check.py" extract rules/big-rule.md > /tmp/big-rule.manifest.json
   ```
2. **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.
3. **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)

1. **Loss lens (deterministic)**:
   ```bash
   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.
2. **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).
3. **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.

© sangrokjung · MIT · sangrokjung/claude-forge

Similar skills

All skills for Agent setup: memory, context, orchestration →
create-harness-spec hedera-dev create-harness-spec — a skill for Claude Code and Codex that turns a Hedera feature idea into a full harness recipe: PRD, spec.yaml, validators, and optional stages. It runs a grilling session before writing any files. CX Codex +1 593installs test-harness zernie test-harness — a Claude Code skill that tests your harness — hooks, skills, settings, CLAUDE.md. Two of three test tiers run free on every commit with no API key. CX Codex +1 2,100installs harness-spec-anatomy hedera-dev harness-spec-anatomy — a skill for Claude Code, Codex, Cursor and other agents that holds the shared vocabulary for hedera-harness v3 recipes — files, defaults, stages, and the blind/evaluate-checklist rule. CX Codex +1 592installs meta-harness-optimization reason-machines meta-harness-optimization — a skill for Claude Code, Codex, Cursor, Copilot and Gemini CLI that runs automated search over model harnesses — the scaffolding controlling what a fixed base model stores, retrieves, and sees. CX Codex +1 420installs harness-engineering guanyang harness-engineering is a skill for Claude Code and other platforms that designs an autonomous agent's control system: editable surfaces, feedback, logs, and approval points. Activated when building research or experimentation loops. CX Codex +1 204installs harness-writing trailofbits harness-writing is a Claude Code skill for building and refining fuzzing harnesses in C/C++ and Rust. It comes into play when creating a fuzz target or investigating crashes that fail to recur. CX Codex +1 6,000installs

From the same set44

The whole set →
adversarial-reviewer The adversarial-reviewer subagent for Claude Code checks behavioural changes before a task is marked complete, reproducing issues and returning a verdict without modifying repository files. CX Codex ★ 880repo stars rca-debugger rca-debugger investigates complex failures when ordinary debugging has stalled, including flaky bugs and differences between CI and local runs. CX Codex ★ 880repo stars security-reviewer security-reviewer scans a diff for OWASP Top 10 flaws, hardcoded secrets and shaky dependencies, then ranks what it finds. You get a report with secure code samples. CX Codex ★ 880repo stars systematic-debugging The systematic-debugging skill guides an agent through finding an error’s cause before suggesting a fix. Use it for failed tests, builds, deployments, configuration conflicts, or repeated failed attempts. CX Codex +1 ★ 880repo stars tdd This command guides one task through TDD: define interfaces, write failing tests, implement the minimum, refactor, and check coverage. CX Codex +1 ★ 880repo stars escalation-fixer escalation-fixer — a last-resort subagent for Claude that takes over after narrower build fixes have failed and is allowed to restructure the project to get it green. CX Codex ★ 880repo stars e2e The e2e command for Claude Code generates and runs Playwright end-to-end tests across browsers, capturing screenshots, traces, and reports. CX Codex +1 ★ 880repo stars skill-factory The skill-factory skill reviews work from a session, spots repeatable patterns, and turns selected ones into Claude Code skills. Use it to capture a workflow for reuse. CX Codex +1 ★ 880repo stars

Project sponsors

Companies that keep this analytics open