Main idea

A CLAUDE.md file placed at the root of a project tells the agent how to work: the repository's conventions, the permitted formats, what it must never do. It is readily taken for the project's memory, since it's there, it persists, and the agent reads it every time.

It isn't one. That file states what must always hold; it doesn't say what took place. It contains neither the bug encountered on Friday, nor the fix tried then abandoned, nor the decision taken mid-session because the first approach didn't hold. Nothing that happened settles into it, and nothing in it ages.

Two objects, two writing regimes. The rule is drafted once, cold, and holds until you change it. The journal is written as things go, hot, and is only true as of the day it is dated. Trying to hold both in a single file gives you either rules polluted with anecdote, or a journal that mistakes itself for doctrine.

Why it matters

This is the gap nobody sees, because something already occupies the place. A project that has its rules file believes itself equipped, and still finds itself re-explaining every Monday what was done the previous week.

The diagnosis is useful beyond working with an agent: a team's documentation, a charter, a conventions reference suffer from exactly the same blind spot.

Nuances and limits

The boundary moves. A decision taken mid-session and confirmed three times becomes a rule — the journal is precisely what lets you notice it.

And a poorly kept rules file always contains traces of history: prohibitions written after an incident, which nobody can date any more.

Open questions

• At what point should a decision recorded in a journal move up into the rules?