Bryan Low

Don't write CLAUDE.md

aiclaude-code

CLAUDE.md rots. You write a rule for today's model, then the model changes or the harness learns to do the thing itself. The rule stays behind, wrong or redundant, costing tokens every session. Add Codex, copy the rules into AGENTS.md, and now two nearly identical files drift apart.

I stopped treating either file as the source. I keep one baseline of what I want from a coding agent, then periodically audit the two files against it. The audit proposes what to add or remove. I review the proposal before anything changes.

Neither file changes unattended. I call them outputs because neither is where I decide what I want.

The baseline

The baseline isn't tied to a particular tool. It holds durable preferences, not workarounds for how one model happens to behave this month. Each entry has an instruction and a reason for keeping it.

- **Context hygiene**: route disposable work — searches, whole-file
  reads, log triage — to subagents, so only distilled results reach the
  main context. _Why: long contexts can bury relevant information._

The reason is there for future me. Six months later, I can see why I added the rule instead of trying to guess from the wording. Preferences tend to last. Claims about model behaviour need checking.

I change the baseline when my intent changes. A model release or an alarming Reddit thread may trigger an audit, but neither gets to rewrite the baseline.

Projection

One rule decides what reaches each instruction file:

A line is projected only while the harness doesn't already cover it. If that coverage goes away, the line comes back.

This avoids spending context on instructions the harness already supplies. Genuine differences belong in the projection, not in two versions of my intent.

When a rule is derived from policy or configuration, its prose comes from that data instead of another hand-maintained list.

Coverage is the awkward part. A model's account of its own harness instructions is not ground truth. Prompts may be hidden, different model tiers may receive different instructions, and a model can simply misjudge whether two rules are equivalent. I treat the result as a review aid. If the evidence is weak or the models disagree, the line stays.

What earns a line

Every rule costs context and attention. The fiftieth rule isn't automatically harmful, but it still needs a good reason to load in every session. Mine has to clear four bars:

  • Observed failure. It fixes a mistake I've watched happen more than once, not one I'm bracing for. A one-off wants a better prompt; only a recurring gap wants a rule.
  • Non-inferable. The agent can't work it out at runtime from the code, the harness, or policy it's already under.
  • Durable intent. It's what I want, not a patch for a current quirk. Quirk patches go in on-demand docs with a date on them, where they expire cheaply.
  • Not mechanically checkable. If a sandbox rule, a hook, or a linter can enforce it, it goes there. Prose fails silently; enforcement fails loudly.

Most things I reach to write down miss at least one of these.

The audit

After a model or harness update, I run an audit. It reads the baseline and current projections, asks each model tier to assess native coverage, then produces a matrix for review.

# agent-instructions-audit
 
For each baseline principle and output:
 
absent from any model tier, missing from projection -> ADD
covered by every model tier -> SHAVE
partial coverage or disagreement -> KEEP
projection contradicts baseline -> CONFLICT
 
Get a second model's opinion on proposed changes.
Report evidence and diffs. Change nothing without confirmation.

SHAVE requires agreement across every tier using that output. If one tier appears to need the instruction, or the evidence is ambiguous, I keep it.

A principle, end to end

One baseline rule says:

- **State persistence**: where compaction is unreliable, persist the plan,
  decisions, and open threads before the context gets tight.

At the time of one audit, the two projections differed:

claude   covered   -> OMIT
codex    partial   -> KEEP

That result won't be true forever. The next audit might disagree with it. If the evidence changes, I get a new proposal and decide whether to accept it.

Refreshing the whys

The rule might last. The reason might not. “I want to review my own commits” is a preference. “Long contexts can bury relevant information” is a claim that needs checking.

So I have a second skill for that:

# doctrine-refresh
 
Pull every empirical claim from the baseline.
Check each one against current evidence.
Mark it supported, contested, or obsolete.
Get a second model to review the result.
Report. Change nothing without confirmation.

If a reason is weak, the skill proposes new wording. If the whole case for a rule has collapsed, it stops there. Evidence can tell me the reason is wrong. It can't decide that I've changed my mind.

Evidence and limits

The research doesn't agree on whether these files help. Gloaguen et al. found no general improvement in task success and higher inference cost, though agents followed recorded non-standard practices. Lulla et al. found lower median runtime and fewer output tokens with comparable task completion.

A study of 100 repositories found context bloat in 42% of agent configuration files and skill leakage in 35%; conflicting instructions often appeared alongside them (dos Santos et al.). That's a good reason to prune. It doesn't prove my audit works.

Lost in the Middle, RULER, IFScale, and When Instructions Multiply give useful background on long-context use and following multiple instructions. Their tasks are not coding-agent instruction files, so I treat them as reasons to be cautious, not proof that fewer lines will improve an agent.

I haven't measured a task-success improvement from this workflow. What I can see is more modest: the two files no longer drift independently, temporary harness quirks are easier to spot, and every standing rule has a reason I can revisit.

The work hasn't disappeared. It moved from patching two files to reviewing one intent and the evidence behind it. For me, that has been a smaller, calmer job through several model updates.