instruction-cleanup

Instruction File Cleanup

Restructure bloated instruction files (CLAUDE.md, AGENTS.md, Cursor rules, etc.) to restore agent performance. Follows a three-phase cycle: Audit the full instruction surface area, Plan where each piece of content should live, Implement the restructuring with verification.

Why This Matters

Instruction files are a prompt budget, not documentation. Every line loads into the agent's context window and competes for attention with the actual task. Research shows instruction-following degrades uniformly as instruction count rises — bloated files don't just waste the middle, they degrade adherence everywhere.

The Three Phases

1. AUDIT — measure everything
2. PLAN — classify every section
3. IMPLEMENT — restructure + verify

Work through each phase completely before moving to the next. Do NOT jump to restructuring without measuring first.

---

Phase 1: Audit

Measure the full instruction surface area — everything that loads into the agent's context.

What to measure

For each item, count lines and estimate characters:

1. All CLAUDE.md / AGENTS.md files — walk the directory tree. Note which are ancestors (load at launch) vs subdirectory (load lazily on demand).
2. @-imports — find all @path/to/file references in instruction files. These expand at launch and are hidden context cost. Measure what they expand to.
3. MEMORY.md — first 200 lines or 25KB load every session. Check current line count. Topic files (in the memory directory) load on demand — note their existence but don't count them as always-loaded.
4. .claude/rules/ files — rules without paths: frontmatter load at launch. Path-scoped rules load when matching files are opened.
5. Skill descriptions — every installed skill's frontmatter (name + description) is always in context; bodies load only when invoked. Hard caps: name 64 chars, description 1,024 chars; aim for descriptions under ~500 chars.

Produce the Context Budget Report

## Context Budget Report

| Source | Location | Lines | Est. Chars | Loading |
|--------|----------|-------|------------|---------|
| Root CLAUDE.md | ./CLAUDE.md | ??? | ??? | Always |
| Frontend CLAUDE.md | ./frontend/CLAUDE.md | ??? | ??? | Always (ancestor) or Lazy |
| @-import: README | @README.md | ??? | ??? | Always (expands at launch) |
| MEMORY.md | ~/.claude/projects/.../MEMORY.md | ??? | ??? | First 200 lines |
| Rule: testing.md | .claude/rules/testing.md | ??? | ??? | Always (no paths: filter) |
| Skill descriptions (N skills) | .claude/skills/ + installed plugins | — | ??? | Always (frontmatter only) |
| ...  | ... | ... | ... | ... |
| **TOTAL always-loaded** | | **???** | **???** | |

Target: each file under 200 lines. Combined always-loaded budget: as small as possible.

TOTAL sums only the always-loaded portions: rows marked Always, the first-200-lines/25KB slice of MEMORY.md, and the skill-descriptions row. List Lazy rows for completeness but exclude them from TOTAL.

Present this report to the user before proceeding to Phase 2.

---

Phase 2: Plan

For every section in every instruction file, apply the litmus test and route it to the right destination.

The Litmus Test

For each section, ask: "Would removing this cause the agent to make mistakes?"

• Yes — it stays in the instruction file (but condensed)
• No — it gets extracted, moved, or deleted

The Content Router

digraph router {
  "Content to place" [shape=ellipse];
  "Needed EVERY session?" [shape=diamond];
  "Removing it causes mistakes?" [shape=diamond];
  "Multi-step procedure?" [shape=diamond];
  "Reference material?" [shape=diamond];
  "Shared team convention?" [shape=diamond];
  "Personal learned pattern?" [shape=diamond];

  "Keep in instruction file\n(condensed, <3 lines)" [shape=box];
  "Skill\n(.claude/skills/)" [shape=box];
  "Separate doc +\npitch-style reference" [shape=box];
  "Rules file\n(.claude/rules/)" [shape=box];
  "Auto memory" [shape=box];
  "Delete" [shape=box];

  "Content to place" -> "Needed EVERY session?";
  "Needed EVERY session?" -> "Removing it causes mistakes?" [label="yes"];
  "Removing it causes mistakes?" -> "Keep in instruction file\n(condensed, <3 lines)" [label="yes"];
  "Removing it causes mistakes?" -> "Delete" [label="no"];
  "Needed EVERY session?" -> "Multi-step procedure?" [label="no"];
  "Multi-step procedure?" -> "Skill\n(.claude/skills/)" [label="yes"];
  "Multi-step procedure?" -> "Reference material?" [label="no"];
  "Reference material?" -> "Separate doc +\npitch-style reference" [label="yes"];
  "Reference material?" -> "Shared team convention?" [label="no"];
  "Shared team convention?" -> "Rules file\n(.claude/rules/)" [label="yes"];
  "Shared team convention?" -> "Personal learned pattern?" [label="no"];
  "Personal learned pattern?" -> "Auto memory" [label="yes"];
  "Personal learned pattern?" -> "Delete" [label="no"];
}

Destination Guide

Destination	What goes here	Loading behavior
Instruction file (CLAUDE.md)	Facts the agent needs every session: build commands, critical rules, architectural decisions, key gotchas	Always loaded. Survives compaction (root only).
Skill (.claude/skills/)	Multi-step procedures: deployment, migration, debugging workflows, testing playbooks	Frontmatter always in context (name ≤64 chars, description ≤1,024 chars; ~500 target). Body loads only when invoked.
Separate doc + reference	Reference material: route tables, component catalogs, API docs, env var tables, schema docs, code examples	Never loaded automatically. Agent reads on demand.
Rules (.claude/rules/)	Shared conventions scoped to file types: "when editing *.tsx, follow these patterns"	Unconditional rules load at launch. Path-scoped rules load on file match.
Auto memory	Personal learned patterns, workflow preferences, feedback corrections	First 200 lines of MEMORY.md load every session. Topic files load on demand.
Delete	Content the agent can derive from code: file trees, version numbers, standard conventions, self-evident practices	Never existed in context.

Reference Technique: Pitch-Style Pointers

When extracting content to a separate doc, leave a conditional reference — not a bare path.

# BAD — bare path (agent doesn't know WHEN to read it)
- Route table: `docs/routes.md`

# GOOD — pitch-style reference (tells agent when to look)
- Before adding or modifying a route -> `docs/routes.md`
- When creating a React component -> `docs/components.md`
- Before deploying -> `docs/deployment.md`

The pitch-style reference tells the agent both WHAT exists and WHEN to read it — a conditional trigger, not a bibliography entry.

@-Import Warning

@-imports (@path/to/file.md) expand at launch — they are NOT lazy. Every @-imported file loads into context on every session, even when irrelevant. Use plain pitch-style references instead:

# BAD — expands at launch, burns context every session
@docs/api-reference.md

# GOOD — agent reads on demand only when needed
- Before calling a backend endpoint -> `docs/api-reference.md`

Reserve @-imports only for short files (<30 lines) that genuinely apply to every session (e.g., importing a shared AGENTS.md).

Compaction Survival Rule (IMPORTANT for monorepos)

Content in the root instruction file survives compaction — it is re-read from disk and re-injected after /compact. Content in subdirectory instruction files is NOT re-injected — it reloads only when the agent next reads a file in that directory.

Critical rules must live in the root file, not subdirectory files. If a rule matters enough that forgetting it mid-session would cause damage, it belongs in the root. When your restructuring plan moves content between files, always ask: "If /compact runs and this file doesn't reload, would the agent make a dangerous mistake?" If yes, keep it in root.

Produce the Restructuring Plan

For each section, state:

Section	Current	Action	Destination	Condensed Version
Route table	60 lines	Extract	docs/routes.md	"Before adding routes -> docs/routes.md"
Build commands	15 lines	Keep, condense	Instruction file	(3 essential commands)
...	...	...	...	...

Include a verification section in the plan. List 5-10 key terms you will grep for after restructuring to confirm nothing was lost. This is part of the plan, not an afterthought.

Flag compaction-critical content. In your plan table, mark any rule that must survive compaction with "(root only)" in the Destination column. If a critical rule currently lives in a subdirectory file, the plan must move it to root.

Present this plan to the user and get approval before implementing.

---

Phase 3: Implement

Execute the approved plan, then verify nothing was lost.

Composition with instruction-guardian

Phase 3 Edits do not require per-file instruction-guardian invocation — the approved Phase-2 plan IS the guardian pass (same litmus test, same routing flowchart, with explicit user approval). The plugin mechanizes this carve-out via a per-project flag file in the system tmpdir: when the flag is present, the guardian's PreToolUse hook suppresses its reminder for matching Edits. Phase 3 owns the flag's lifecycle (create on approval, remove on completion). The flag never lives inside the consumer's repo, so .gitignore is not involved.

Standalone use: the flag matters only when the instruction-health Claude Code plugin's hooks are installed. With a skills-only install (skills.sh, manual copy, or a non-Claude tool) nothing reads it — Step 0 and the Final step become harmless no-ops you may skip, and the carve-out rests entirely on the Exception section in instruction-guardian.

Run guardian only when a Phase 3 Edit deviates from the approved plan — scope creep, newly discovered sections, ad-hoc additions, or content you decide to handle differently. A deviating Edit should disarm the flag (see "Final step" below) before running, or accept that the hook will not fire for it. If you disarmed the flag and approved-plan Edits remain, re-arm it by re-running Step 0 before resuming them — the plan's carve-out still applies to those Edits.

Step 0 — Arm the carve-out (immediately after Phase-2 approval)

Before any Edits, create the flag so the guardian hook stays silent for the rest of Phase 3:

# CLAUDE_PROJECT_DIR is set for hooks, not for your shell — the $PWD fallback
# runs here. Execute from the project root (the directory the session was
# launched in) so the key matches the one the hook computes.
flag="${TMPDIR:-/tmp}/instruction-health-cleanup-$(printf '%s' "${CLAUDE_PROJECT_DIR:-$PWD}" | cksum | awk '{print $1}').flag"
touch "$flag"

The flag lives in the system tmpdir, keyed by a cksum of the project root (CLAUDE_PROJECT_DIR inside hooks; your cwd when you run the snippet — which must therefore be the project root), so it scopes per-project and never enters the repo. Re-run this step if the session restarts mid-Phase-3 — the SessionStart hook clears the flag at every session start. If the guardian reminder still fires on the first Phase-3 Edit, the flag key did not match; re-run the snippet from the project root.

Implementation Order

1. Create extracted docs first — write the files that content is moving to
2. Create skills — write SKILL.md files for procedures being extracted
3. Rewrite the instruction file — condense kept content, add pitch-style references, remove extracted content
4. Clean up memory — if MEMORY.md was flagged in audit, move misplaced content to instruction files or rules

Verification: The Needle Grep

After restructuring, verify that key concepts are still reachable. Pick 5-10 important terms from the original file and grep for them:

# Can the agent still find routing info?
grep -r "route" docs/ CLAUDE.md .claude/

# Can it find the deployment procedure?
grep -r "deploy" .claude/skills/ docs/

# Is the critical pitfall still inline?
grep "getSession" CLAUDE.md

Pointer check — existence is not reachability. For every doc extracted in the plan table, confirm an always-loaded instruction file still carries its pitch-style pointer:

# Each extracted doc must be pointed to from an always-loaded file
grep -n "docs/routes.md" CLAUDE.md .claude/rules/*.md

A term found only inside an extracted doc, with no pointer from an always-loaded file, counts as lost — a fresh session has no way to discover that doc. (Extracted skills are exempt: their frontmatter descriptions are always in context.)

If a key term is unreachable — not inline in an always-loaded file, and not in an extracted doc that an always-loaded file points to — something was lost. Fix it before committing.

Final step — Disarm the carve-out

Once the verification grep is clean, remove the flag so guardian reminders re-enable for any subsequent edits:

# Run from the project root, as in Step 0, so the key matches.
flag="${TMPDIR:-/tmp}/instruction-health-cleanup-$(printf '%s' "${CLAUDE_PROJECT_DIR:-$PWD}" | cksum | awk '{print $1}').flag"
rm -f "$flag"

Skip-or-forget this step and the rest of the current session silently bypasses the guardian for instruction-file edits in this project. The SessionStart hook clears stale flags at the next session start (and the OS clears $TMPDIR on reboot), but if hooks are disabled the bypass persists indefinitely — always disarm explicitly.

Target Metrics

Metric	Target
Lines per instruction file	Under 200
Code blocks in instruction files	0 (extract to docs or skills)
Large tables (10+ rows)	0 (extract to docs)
@-imports of large files	0 (convert to pitch-style references)
MEMORY.md line count	Well under 200, with headroom for growth

---

Common Mistakes

1. Skipping the audit — Restructuring without measuring leads to "feels smaller" but no actual context reduction. Measure first.
2. Leaving all pitfalls in docs — Critical gotchas (ones that cause CI failures or data loss) MUST stay inline. Only extract the less severe ones.
3. Not considering skills — Deployment procedures, testing workflows, and debugging playbooks are verbs, not nouns. They belong in skills, not docs.
4. One-shot restructuring — This should be a conversation: audit -> present -> plan -> approve -> implement -> verify. Not a single commit.