Evolving CLAUDE.md

Wires CLAUDE.md to maintain a living Decisions & Learnings log that the assistant updates as the project evolves — without letting the file bloat. CLAUDE.md is read into context every turn, so the goal is a small, well-pruned set of durable decisions, with everything else linked out or archived. Three hooks keep the log healthy automatically. It complements the built-in init skill: init describes the codebase, this adds the mechanism that lets the file grow safely.

Install

/plugin install evolving-claude-md@alexmskills

Trigger it

/evolving-claude-md: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".

When to use it

  • "add learning mechanism to CLAUDE.md", "make CLAUDE.md evolve", "self-updating CLAUDE.md"

  • "decisions log", "ADR-style notes in CLAUDE.md", "project memory in CLAUDE.md"

  • "compact CLAUDE.md" / "CLAUDE.md is getting too big"

  • A CLAUDE.md exists but has no mechanism to keep itself current

  • Not for plain codebase documentation — use init for that

What it does

Three automatic hooks

The plugin ships hooks/hooks.json (pathed via ${CLAUDE_PLUGIN_ROOT}), so the hooks register on enable with nothing to add to settings:

  • SessionStart — audit-claude-md.py checks the D&L section + whole-file size + staleness and injects a recommendation when something needs attention; silent when healthy.

  • PreToolUse on Write|Edit of CLAUDE.md — lint-claude-md.py rejects new entries that lack a date or topic-tag, or exceed 200 chars.

  • PostCompact — re-runs the audit so the assistant sees the current state without paying to re-read the whole file.

What’s new in 1.1.1

  • Merge as the fourth downward pressure — SKILL.md now documents merging same-session same-area clusters (phased rollouts e2a/e2b/e3/e4; multi-aspect bursts within ~48h) as the compaction lever that works pre-14-days. Graduation and quarterly archive both require old entries; merge does not. Discovered while compacting a sibling repo’s 37-entry log when the audit fired "RECOMMENDED" but every documented pressure was blocked.

What’s new in 1.1.0

  • Whole-file size check — audit now reports total CLAUDE.md KB independently (warn 25 KB, recommend 40 KB). Catches bloat that lives outside the # Decisions & Learnings section (Conventions / Architecture / Gotchas) which the entry/line counters never saw.

  • Self-report when D&L is missing — a repo without the # Decisions & Learnings section no longer exits silently; the audit reports the file size + total dated-bullet count and nudges to wire evolving-claude-md.

  • Staleness trigger — for each D&L entry, the audit extracts backticked artifact-looking tokens (paths, ClassName.method, --cli-flags, <xml-tags>, filenames with known extensions) and runs git grep -qF against the tree. Entries citing ≥2 missing tokens surface as "may be wrong now" candidates. Budget-capped (~2.5s) so the hook stays fast. Closes the only signal the bloat-only audit lacked: a delete lever, not just a compress lever.

Entry format contract

Every entry follows - YYYY-MM-DD — topic-tag — what. Why: reason. [see → docs/decisions/…​]. Absolute dates only, a mandatory kebab-case topic tag, and a hard 200-char body cap (bigger detail moves to docs/decisions/).

Downward pressure on size

A Recent (last 14 days) / Historic split keeps the actively-scanned section small. Reversals are struck through, stable patterns graduate into Conventions/Gotchas, and a quarterly archive-decisions.py run moves old entries into docs/decisions/{YYYY-Q}.md.

Notes

  • Manual (non-plugin) install requires copying the three scripts into .claude/skills/evolving-claude-md/ and adding the hooks to .claude/settings.json, then one session restart.

  • The quarterly archive is the one operational step nothing automates — set a calendar reminder.

  • Disable a hook by removing its entry; disable all via disableAllHooks: true.