Your CLAUDE.md rules have an expiry date

A developer tested three long-standing rules in framesmith's CLAUDE.md by deleting each one in a throwaway git worktree and running a headless task with `claude -p "<task>" --permission-mode acceptEdits`, finding one rule dead, one worth keeping as insurance, and one reducible to a single clause in about an hour across three runs. The ESM `.js` extension rule proved unnecessary because the agent copied neighboring files' style, the test-storage redirect rule stayed because a miss would overwrite the real `~/.framesmith` design store, and the MCP tool registration rule shrank to just the VISION.md tick. The developer packaged the procedure as verderer, a CLI that keeps a ledger of harness rules recording when each appeared, what was decided about it, and which model it was judged against.

Your CLAUDE.md rules have an expiry date TL;DR: Every rule in your CLAUDE.md or AGENTS.md is a patch over something a model once got wrong. The model improves, your codebase grows into the convention, and the rule stays. I took three long-standing rules from framesmith’s CLAUDE.md, deleted one at a time, and gave the agent a task that forced exactly that decision. One rule was dead, one was worth keeping as insurance, and one shrank to a single clause. It took an hour. I turned the procedure into verderer https://github.com/vicmaster/verderer , a small CLI that keeps a ledger of your harness rules: when each one appeared, what was decided about it, and which model it was judged against. Rules are written against a model Think about when you wrote your oldest CLAUDE.md rule. You probably wrote it right after the agent did something wrong. Wrong import style, tests writing to your real home directory, a new feature that forgot the docs. You patched it with a sentence, and the sentence worked. That sentence was written against the model you had that week and the repo you had that week. Both have changed since. The rule hasn’t. Dead rules aren’t free. They cost tokens in every session, and they can do worse than that. When I A/B tested a generated CLAUDE.md summary https://victorvelazquez.dev/blog/agents-didnt-need-context7-for-my-rails-app/ , the clearest effect was harm: agents obeyed over-broad rules over the code right in front of them. An instruction file is the loudest voice in the room. Every line in it should still deserve that. The usual answer is a ritual: every few months, delete the whole thing and see what breaks. It works, roughly. But you lose the rules that were quietly preventing an expensive mistake, and you learn nothing about which ones those were. The trial: one rule out at a time From framesmith’s CLAUDE.md, I picked three rules I suspected had outlived their purpose and ran the same small experiment on each: 1. Make a throwaway git worktree. 2. Copy in the CLAUDE.md and delete one rule. 3. Run a headless task that forces the decision that rule exists for: claude -p "<task " --permission-mode acceptEdits . 4. Read what the agent did. Three worktrees, three runs, about an hour. Here’s what came back. ESM imports use .js extensions. Dead. Without the rule, the agent wrote ./probe-util.js and explained it had copied the style of the neighboring files. The codebase carries this convention now. The rule was useful when the repo was young and had few files to copy from. Tests that persist data redirect storage off the real ~/.framesmith . Derivable. Without the rule, the agent redirected storage to a temp dir before importing the store, in the right order. So the model can figure it out. But a miss means a test run overwrites my real design store. That’s an expensive mistake, and keeping one sentence to prevent it is cheap. The rule stayed. A new MCP tool gets registered, documented in the README, and ticked in VISION.md. Reducible. Without the rule, the agent registered the tool, updated the README, the guidelines and the server instructions, and wrote a test. It skipped exactly one thing: the VISION.md tick. So the rule now says only that. One rule deleted, one cut to its single useful clause, one kept on purpose. Honest caveat: that’s one task per rule. One run tells you the model can do it unaided, not that it always will. That’s exactly why the “derivable” verdict exists. Why rules die Look at why the dead rule died. The model didn’t get smarter about ESM. The repo got bigger. Once enough files used .js extensions, the code itself became the instruction, and the agent read it. That’s the part I find useful. A rule is a bridge for a gap in what the agent can figure out on its own. Sometimes a better model closes the gap. More often, in my repos, the code closes it. Either way, nothing tells you when it happened. verderer: a ledger for harness rules I wrote verderer the same day, to make the trial repeatable. It’s a zero-dependency Node CLI: npx verderer scan inventory rules into .claude/verderer.json npx verderer status each rule, when it appeared, its last verdict npx verderer probe print the ablation recipe above scan reads the top-level bullets in your CLAUDE.md and AGENTS.md and writes one ledger entry per rule. It’s append-only: known rules keep their history, new ones get a date, and rules that left the file are marked retired, never deleted. One design choice came straight from the trial breaking. My first probe script crashed because framesmith’s CLAUDE.md is gitignored, on purpose, so it didn’t exist in the fresh worktrees. Plenty of repos keep their harness private like that. So verderer checks how git sees each harness file and gets provenance from wherever it can: - Tracked: git blame dates every rule for free. The date tells you which model era a rule was written in. Pruning is a normal commit, and rollback is git. - Ignored: there’s no history, so the ledger carries it: the first scan records rules as origin: unknown , and everything after that gets a date. You can still commit the ledger file even if the harness stays private. Verdicts have three values on purpose: dead , derivable , needed . “Derivable” is the one a naive cleanup tool would get wrong. The model does it, but you keep the rule because of the blast radius. That’s a judgment call, so verderer reports and you decide. It never deletes a rule. The part that makes it worth having: model changes A verdict is only true for the model it was judged against. So every verdict records its model, and scan reads the model the repo has actually been running on from Claude Code’s own session logs. That’s the concrete model id, so an alias like opus doesn’t hide an upgrade underneath. When it changes, you see which verdicts are now stale: model changed: claude-opus-5-5 → claude-opus-5-6 1 verdict s rendered against another model are stale — re-run their inquests. It doesn’t poll for model releases. The question isn’t “did a new model ship?”, it’s “is this repo running on a different model than the one these verdicts came from?” For tools without a detection adapter yet, verderer checkpoint --model <id records it by hand. What it doesn’t do yet It’s v0.2.0, and I’d rather you know the edges before you try it: - The probe is a recipe, not automation. verderer probe prints the steps. Running the worktrees and headless runs per rule is the next piece of work. - Verdicts go into the JSON by hand. There’s no verdict command yet. - A rule is a top-level bullet. Prose paragraphs aren’t parsed. Reword a rule and it’s a new rule to the ledger, with no verdict. That’s arguably right, since a reworded rule needs judging again, but know it. - Only CLAUDE.md and AGENTS.md at the repo root for now, and model detection only reads Claude Code. Codex sessions, .claude/agents/ , GEMINI.md and Cursor rules are on the roadmap. What I’d tell past-me Write rules like they’ll expire, because they will. When you add one, you’re recording a gap between what the agent can figure out and what you need. Gaps close. Usually the code closes them, sometimes the model does, and nobody sends you a notice. You don’t need a tool to start. Pick the three oldest rules in your CLAUDE.md, delete one at a time in a throwaway worktree, and give the agent a task that hits that decision. If the agent does the right thing and a miss would be cheap, the rule is done. If a miss would be expensive, keep it and write down why. That second list is the part of your harness that actually earns its tokens. verderer is on GitHub https://github.com/vicmaster/verderer and on npm, MIT licensed. It’s the third tool in a family: reeve https://github.com/vicmaster/reeve enforces what agents may do, banneret https://github.com/vicmaster/banneret disciplines how they work, and verderer audits what you tell them.