Evolving CLAUDE.md

This skill is model-invokable — most often you just ask in natural language: "make CLAUDE.md evolve", "add a self-updating decisions log to CLAUDE.md", or "CLAUDE.md is getting too big, compact it".

To compact the log on demand, run the dedicated command:

/evolving-claude-md:compact runs the four downward pressures as one reviewed edit, in the order that keeps lessons safe: supersede gaps, release mirrors (keep what a release taught, drop what it shipped), same-day merges, graduation into Conventions/Gotchas, mega-entry splits, stale checks — and the archive last. Archiving first is the mistake an ad-hoc compaction makes: lessons that should be standing rules end up in the quarterly file instead of the always-loaded one.

The plan for this repository’s own CLAUDE.md — a real run of the planner the command reads.

Every edit is drafted with its exact text and shown before anything is written; plan stops there, yes skips the wait. The data comes from a read-only planner, compact-claude-md.py. Its graduation list finds a tag repeated three or more times — which misses lessons that recur by theme under different tags — so it also lists every entry about to age out, for the session to review first.

Fixed along the way: archive-decisions.py was unsafe to run twice. Rebuilding the section from dated entries only, it dropped the section’s format note, and an entry absorbed any undated line below it — so a second run archived the first run’s teaser and left a new one reporting only its own count. It now parses the section line by line, keeps everything it doesn’t archive in place, and merges into an existing quarter teaser.

1.6.0 gated what gets written. 1.7.0 borrows the two mechanisms an 80-entry survey of instruction-file upkeep tools showed were missing here — chosen because exactly half of those 80 document no staleness handling at all.

Load evidence. A new InstructionsLoaded hook records which instruction file actually loaded, in which session, and why (session_start, nested_traversal, path_glob_match, include, compact), appending to .claude/evolving-claude-md/loads.jsonl. Every other check in the plugin reasons about what the file says; this one records what the harness did, and that makes two failures checkable which no content audit can see:

Both wait for load_min_sessions (default 5) of recorded evidence: "hasn’t loaded yet" and "never loads" are indistinguishable on day one.

Supersede links. An entry may end Supersedes: YYYY-MM-DD topic-tag. The audit then reports a target that is still unstruck — a replaced rule still reading as current — or one that doesn’t exist, catching a typo’d date or tag. The lint exempts the link from the body cap, because charging bookkeeping against the prose budget would price the link out of use. The idea comes from temporal knowledge graphs, which record when a fact stopped being true instead of leaving both versions standing.

Also corrected: the docs claimed in three places that the lint hook enforces a 200-character body cap. It enforces 500, so entries between the two had been passing silently against a documented rule. Both numbers are now stated, with the reason they differ — 200 keeps the log scannable, 500 is where an entry is provably a design doc. Enforcement was deliberately left at 500; tightening it would start rejecting entries in every consuming repo.

1.5.0 gave the log a write path. 1.6.0 asks whether a given write has earned its place, because every mechanism before it was downstream of a write nothing gated: four pruning pressures, zero inlet control.

The bar decides; the six triggers only nominate. Write the candidate as a sentence that is true about the repo tomorrow, then name what a future session does differently knowing it. If the only true sentence is "we did X", there is no entry — the changelog, the tickets and git log already hold it. A delivery earns an entry only when it taught something: a constraint, a trap, a reversal. Most sessions nominate zero, and zero is the right answer to a session that merely shipped. The session-end capture prompt carries the bar, and what NOT to log gains the durable-artifact rule: where a repo keeps a changelog, ADRs or tickets, an entry is earned only by the part that isn’t in them.

New audit check — CHANGELOG MIRROR. Measures that duplication directly: entries naming a version CHANGELOG.md already documents. It found 63% on the repo that motivated the change and stays silent on logs of real learnings.

Parallel lanes spool instead of colliding. Measured on one 2,400-commit repo running worktree lanes: 86 of 257 non-merge CLAUDE.md edits were made on lane branches, and all 50 merge commits touching the file were resolving them. A lane — a linked git worktree, or any non-default branch with "lane_spool": "branch" — now routes its nominations to .claude/evolving-claude-md/incoming/<branch>.md. One file per writer, so the conflict class disappears rather than being resolved. Then capture-triggers.py fold prints every lane’s nominations together with cross-lane near-duplicates flagged, for one writer to curate on the default branch — five lanes on one epic learn the same lesson five times, and only a reader holding all of them can dedup it. An ordinary feature branch is deliberately not a lane: one writer at a time merges cleanly.

Obsolescence findings name the edit. MISSING from the layout and OBSOLETE in the layout now prescribe the change to make — add the line, or strike it — because a flag a reader must translate into an action is a flag that gets skimmed past.

A fifth check was written and cut before shipping: tag-uniqueness looked like a clean symptom until calibration showed the fleet’s healthiest log runs 100% distinct tags and the changelog-shaped one 98%. It measured naming style, not quality, and would have flagged the best repo in the fleet.

Every earlier mechanism was pruning pressure on entries that already exist; the blind spot was a log that was never written to (issue #37 — installed for weeks on a 127-commit repo, zero output, while sessions rediscovered the same gotchas).

New tree-grounded audit states, fleet-calibrated on 33 repos:

New opt-in capture triggers (both default off until real-use noise is measured): a session-end prompt when a session committed and edited files but never touched CLAUDE.md, and commit-message mining that offers to promote gotcha-shaped commit prose while the context is hot. Both route entries: repo-durable → the D&L log; machine-personal → the learn-on-failure skill.

New structure review: analyze the file’s internal shape against a shipped, researched rulebook (references/claude-md-best-practices.md — 96 cited findings from official docs, ~40 real repo files, and measured studies; adversarially verified). Recommendations must cite a rule or a tree-provable check, and the measured evidence hierarchy caps cosmetic rearrangement.

"Concise" is not a universal number — 40 KB is bloat in a library and reasonable in a monorepo. Every threshold is overridable, resolved defaults → ~/.claude/evolving-claude-md/config.json → <repo>/.claude/evolving-claude-md/config.json.

Name only what you want changed. Unknown keys are ignored and a corrupt file falls back to defaults — this runs on SessionStart, so a bad config must never be why a session starts badly.

.claude.local.md and nested CLAUDE.md files load into context exactly like the root file, so bloat in them was previously the same problem measured nowhere. The audit now size-checks both, walking up to three levels deep and skipping node_modules, target, build and friends.

Only the root file gets the full treatment — Decisions & Learnings parsing, staleness, coverage — because that is where the log lives, and reporting on five files at every session start would be its own kind of noise.

The routing rule for which file a learning belongs in is one question: would this still be true on a teammate’s laptop, in CI, and in a fresh clone? No means .claude.local.md. An absolute path containing your username is the most common way a personal detail gets committed — ~/ is fine, /home/alex/… is not.

Every other check pushes content down: bloat, staleness, clustering, archiving. A file can pass all of them and still be useless — well under every threshold, perfectly formatted, and never saying how to run the tests.

Two gaps, both grounded in the tree rather than in a generic checklist:

The grounding is the design. A docs repo has no build command and a three-directory repo needs no layout section; a generic checklist nags both. Measured across a 29-repo sample these fired zero times, because every one already covered what its tree justified.

Decline a gap by putting the decision in the file itself:

A gotchas check was built and then removed: on the same sample it fired on 17 of 29 repos, and those 17 were exactly the ones with no Decisions & Learnings log — so it was re-detecting "hasn’t adopted this skill", which the audit already reports. Gotchas arrive by graduation from the log, and the topic-cluster check is the grounded way to prompt for them.

Tier 3 — lifecycle hooks on both clients.

The difference that matters: An instruction file edited from the shell (sed, a script) is not a matched tool path, so the lint never sees it. PostCompact findings arrive as a systemMessage rather than injected context.

Install, hook trust and verified limits: Codex compatibility.