split-claude-md

model	sonnet
name	split-claude-md
description	Six-phase CLAUDE.md cleanup for a file that has grown too large. Phase 0 deletes what the repository itself answers. Phase A rotates old dated records into monthly archives with an index and a navigation header. Phase B consolidates recurring failure patterns into a Known Patterns section with current instance counts. Phase C extracts stable reference sections to sibling files or to a skill, leaving a pointer. Phase D keeps a rule in place and moves only its evidence to a satellite, for always-loaded files where a rule moved out stops being read. Phase E scopes file-triggered rules to .claude/rules with paths frontmatter so they leave the always-loaded set entirely. Use when CLAUDE.md is over its threshold, when a rule is being followed unreliably, or when the user asks to split, shrink, archive, rotate, consolidate, extract, prune or scope a CLAUDE.md.
disable-model-invocation	false
argument-hint	[--cut-date YYYY-MM-DD | --keep-days N | --target-file <path> | --no-prune | --patterns-only | --no-patterns | --extract-only | --no-extract | --no-scope]

Split CLAUDE.md - prune, archive, consolidate, extract, compress, scope

An always-loaded file is re-read on every request of every session. Text in it is not stored once; it is paid for continuously. Six things grow over time:

1. Old dated records load every turn even when no future session needs them.
2. Recurring bugs accumulate as scattered prose with stale instance counts, so a future session cannot tell that a "new" bug is the Nth instance of a known one.
3. Stable reference docs sit inline although they are consulted rarely, and every session that does not need them still pays for them.
4. Rules accumulate their own evidence, and the war story outgrows the rule.
5. Content the repository already answers gets written down and then goes stale, so the file starts contradicting the code.
6. Rules that only matter for one file type load in every session regardless.

There are TWO reasons to cut, and the second one is usually missed. Cost is the obvious one. Adherence is the other: a longer file is followed less reliably, which Anthropic states twice. So a file sitting exactly at its cost threshold is not finished, and a rule being ignored is a reason to cut rather than a reason to restate the rule more loudly.

Read this first

reference/loading-model.md holds the mechanics every phase depends on: what each destination costs, what loads lazily, what is free, what is lost after a compaction, and the hard limits. Read it before choosing a destination for anything. Two facts from it decide most of a run:

• @path imports do not reduce context. Imported files load at launch with the file that imports them. This is the usual wrong answer to a large CLAUDE.md and it saves nothing.
• A rule moved to a lazy destination is LOST after a compaction until a matching file is read again. A rule that fires on a FILE survives that. A rule that fires on a CONVERSATION does not, and must not be moved.

The six destinations, cheapest last

• CLAUDE.md, and unscoped .claude/rules/*.md: full content, every session.
• A skill: description every session, body only when it runs. Zero with disable-model-invocation: true.
• A sibling markdown file plus a pointer stub: the stub only.
• .claude/rules/*.md with paths: frontmatter: nothing until Claude reads a matching file.
• A nested CLAUDE.md in a subdirectory: nothing until Claude reads a file there.
• Deleted: nothing, ever again.

Run order

Phase 0, then A, then B, then C, then D, then E. The letters are names; this line is the order. Phase 0 runs first so every later phase moves a smaller set. Phase E runs last because it needs the rules already reduced to their imperative.

Each phase lives in its own file so a compaction cannot truncate it away. Read the phase file when you reach that phase, not before.

• Phase 0, delete what the repo answers: reference/phase-0-prune.md
• Phase A, archive old records: reference/phase-a-archive.md
• Phase B, consolidate patterns: reference/phase-b-patterns.md
• Phase C, extract reference sections: reference/phase-c-extract.md
• Phase D, split rules from their evidence: reference/phase-d-rule-evidence.md
• Phase E, scope rules to file paths: reference/phase-e-path-scope.md
• Implementation notes, edge cases, and lessons from prior runs: reference/cross-phase.md

The skill's own checks: python3 <skill-dir>/run_tests.py runs every test file and prints one total. It fails when any file reports no tally, because a runner that silently covers a fraction of its suite is the exact shape of a check that cannot fail.

When to run

• The user asks to "split" / "shrink" / "archive" / "rotate" / "consolidate" / "extract" CLAUDE.md.
• wc -c CLAUDE.md reports > 50,000 chars and the bulk is decision-log entries.
• After a long session that added many decision entries.
• Decision-log entries explicitly cite "Nth instance", "Updated count", or "recurring pattern" — a sign Phase B consolidation is overdue.
• CLAUDE.md contains large stable reference sections (architecture pipelines, file maps, directory layouts, advisor / endpoint tables) that haven't been edited in many sessions — a sign Phase C extraction is overdue.
• A rule in the file is being followed unreliably. Length reduces adherence, so a cut is a candidate fix and restating the rule is not.
• The file describes something the repository already answers, such as a directory layout, a dependency list, or a module inventory. Phase 0 is due, and a section the repo now CONTRADICTS is the more expensive case.
• The file carries rules that only matter for one file type (a framework, a document format, a container file). Phase E moves those out of every session.
• /context shows the always-loaded block dominating the startup breakdown, or /doctor proposes trims on a checked-in CLAUDE.md.
• The file is over 200 lines, which is Anthropic's stated target per CLAUDE.md.

When NOT to run

• CLAUDE.md is under 50K chars AND no recurring patterns are obvious AND no large reference sections — the cleanup adds maintenance burden without saving meaningful context.
• The file has no dated records in ANY of the three shapes Phase A can archive (### YYYY-MM-DD: title entries, whole dated ## sections, or dated top-level bullets - Shipped (YYYY-MM-DD): ...); Phases B and C can still run independently.
• All entries are from the last 30 days (or, on a project that cuts by state, every entry is still load-bearing) AND no recurring patterns exist AND all sections are small/active — nothing to do at any phase.
• The file is NOT always-loaded. A satellite, an archive, or a reference doc that only loads when something opens it costs nothing per session, so shrinking it buys nothing. Confirm with /context which files actually load before treating any file as expensive.

Inputs

Default target: CLAUDE.md in the current working directory. Default cut for Phase A: 30 days before today. Archives are CLAUDE_DECISIONS_YYYY-MM.md beside CLAUDE.md. All six phases run in the order above.

• --target-file <path> operate on a CLAUDE.md outside the current directory.
• --cut-date YYYY-MM-DD Phase A, records strictly before this date archive.
• --keep-days N Phase A, keep records from the last N days.
• --no-prune skip Phase 0. --no-patterns skip B. --no-extract skip C. --no-scope skip E.
• --patterns-only run only B. --extract-only run only C.

--patterns-only and --extract-only cannot be combined. If both are passed, stop and ask which was meant. Several --no-* flags together are fine.

If no arguments were passed, use the defaults and report what you are about to do before you do it.

Step 1. Measure, before anything else

Run /context and record the startup breakdown. It reports tokens by category, names which CLAUDE.md and memory files ACTUALLY loaded, and prints its own suggestions. wc -c counts bytes, python len() counts characters, and neither counts tokens, which is the bill. On a file with Hebrew or other multibyte text all three disagree.

/context is also the only way to prove a file loaded at all. A rule that silently stopped loading reads exactly like a rule being ignored, and no character count can tell them apart.

Then run the surveyor, which answers the discovery questions for Phases 0, A, C, D and E in one pass and prints its evidence:

python3 <skill-dir>/survey.py <path-to-CLAUDE.md> --keep-days 30

On a checked-in CLAUDE.md, run /doctor too and read its trim proposal. It is evidence for Phase 0, not a verdict.

Report the line count against 200. That is Anthropic's stated target per CLAUDE.md file. A project's own threshold governs the run; the 200-line figure keeps the gap visible even when the project threshold is met.

Step N. Measure again, and report what MOVED versus what went

Run /context at the end and report the measured drop, not the size of the text you relocated. They differ, and only one of them is a saving.

Report these separately, because they are not the same kind of result:

• Deleted (Phase 0): permanent, never comes back.
• Moved to a lazy destination (C to a skill, E to a scoped rule): gone from startup, returns when needed, lost after a compaction until then.
• Moved to an archive or satellite (A, C to a file, D): gone from startup, found only if a session follows the pointer.
• Compressed in place (D's retained rules): still loaded, just shorter.

A single percentage over all four hides which one happened, and they carry different risks.

Universal rules, every phase

Back up before the first mutation, and never skip it. A run mutates several files: CLAUDE.md is rewritten, an archive is appended to, the index is edited in place, and Phases C and E create new files. Copy each existing one with the same dated suffix, skip absent files without erroring, and never overwrite a same-day backup, which is the only true pre-run state. Back up to the project directory, never to an ephemeral job tmp dir. The full loop is in phase-a-archive.md A3 and applies even when Phase A is skipped.

Fail closed on shape. survey.py classifies a section REFERENCE or RULE and proves reference-ness rather than assuming it. Calling a rule "reference" is the harmful direction, because it ends with a behaviour rule extracted out of an always-loaded file. Calling reference "rule" only costs a slightly smaller cut.

A heading check is not a rule check. Confirming every heading survived passes on a stub whose rule was gutted. Before starting, hand-write the distinctive phrases of the load-bearing rules, and grep the finished file for every one. That is the check that proves the cut was safe.

Never claim a saving you did not measure. Phase B normally GROWS the file and that is correct, because its win is currency and findability. Say so.

A rule shaped "every time X, always do Y" wants a hook, not a destination. CLAUDE.md reaches Claude as a user message, so it is context and not enforcement, wherever it lives. No phase here can make a rule binding. When one turns up, name it a PreToolUse hook candidate in the report and move on.

Compare the character set against the ORIGINAL file, not against an absolute. A pure-ASCII assertion is the wrong check and fails on a legitimate file that carries Hebrew scan terms or arrows on purpose.

Don't

• Don't try to "compress" individual decision-log entries in Phase A (one-line summaries, dropped context, etc.). Phase A MOVES entries; it doesn't rewrite them. Entry content stays verbatim in the archive.
• Don't delete CLAUDE.md before writing the new version. Always mv CLAUDE.md.new CLAUDE.md at the end after verifying.
• Don't run this on files other than CLAUDE.md unless --target-file was explicitly passed.
• Don't push or commit anything. This is a local file restructure; commits/pushes are a separate concern.
• Don't invent pattern names, instance counts, or root causes in Phase B. Source everything from the user's existing decision-log prose. When the prose is ambiguous, ASK.
• Don't promote a candidate to global memory in Phase B without explicit user approval. Even if a pattern looks cross-project, the user owns the global memory layout.
• Don't extract sections in Phase C that are on the deny list, smaller than the threshold, or recently edited — even if the user pre-approves a batch. Confirm per-section.
• Don't rewrite a section's content during Phase C extraction — Phase C MOVES sections verbatim. If a section needs rewriting, do that as a separate slice before or after the extraction.

---

• Don't use @path imports to make a file smaller. They load at launch with the importing file and save nothing.
• Don't move a rule whose trigger is a conversation to a lazy destination. One compaction and it is gone with no file read that will bring it back.
• Don't delete a RULE-shaped section in Phase 0, however derivable it looks.
• Don't put a rule, or any fact a session needs, in an HTML comment. Comments are stripped before Claude sees them, so a rule there is invisible, not cheap.
• Don't report a saving that /context did not measure.
• Don't leave a .claude/rules/ file without paths: frontmatter and call it a saving. Unscoped rules load every session.