CLAUDE.md vs spec vs plan: what each one remembers
Your coding agent starts every session cold. It reads whatever files you give it, does good work for an hour, and then the session ends and the reasoning goes with it. Next time it ships what you asked for, not what you meant, because the meaning was never written anywhere it could read. Three files are usually blamed. They remember different things.
CLAUDE.md remembers how to work here
CLAUDE.md, or AGENTS.md, or whatever your agent loads on start, is the file that says how this repository is worked on. Which package manager. How to run the tests. Where the API lives and what not to touch. It is loaded every session, which makes it the most reliable memory the agent has, and that reliability is exactly why it fills up. Every lesson gets a line. After a few months it is a junk drawer of conventions, warnings and one-off notes, and the agent reads all of it whether or not today's task needs it.
What it does not hold is why the product exists. It can tell the agent to keep the API self-contained. It cannot tell the agent that the API exists because the whole bet is that agents plan alongside their humans, and that a feature which makes the API harder to reach is a step backwards even if the tests pass.
A spec remembers one feature
A spec is the right tool for a bounded piece of work: what to build, the edge cases, the acceptance criteria. It holds the what, for one feature, at one moment. When the feature ships the spec is done, and a month later it is describing something that no longer matches the code. Specs are good at getting one thing built well. They are not a memory of the product, because each one is written to be finished and forgotten.
The trouble starts when the spec is the only context the agent has. It will build precisely what the spec says and nothing the spec implies. If the feature was meant to serve a user need that three other features also serve, the agent cannot know that, and it will happily duplicate, contradict or undercut the others.
A plan remembers why
A plan, in the sense used here, is a small tree. At the top are the outcomes you are trying to reach, with a measure on each. Under each outcome are the user needs that stand in the way. Under each need are the approaches you are betting on, with a status, because some bets are still being validated and some have been retired. Under each approach are the jobs: checkpoints you can observe, assigned to a phase, that tell you whether the bet is paying off.
Read top-down and the plan says why any piece of work exists. Read bottom-up and every job has a reason above it. That is what a coding agent is missing when it forgets between sessions: not the conventions, not the acceptance criteria, but the chain from this job to that outcome. Give it the plan and it can answer the question it otherwise guesses at: does this change serve the need it sits under, or does it just satisfy the request?
Which file answers which question
| The agent asks | Answered by |
|---|---|
| How do I run this, and what must I not break? | CLAUDE.md |
| What exactly am I building today? | the spec |
| Why does this work exist, and what else serves the same need? | the plan |
| Is this bet still live, or did we retire it? | the plan |
| What did we decide last month, and did it stick? | the plan, if it records changes |
The three are not rivals. CLAUDE.md stays short when the why moves out of it. Specs get better when each one names the need and the approach it serves. The plan is the thing that survives the session, because it is not written to be finished.
What this looks like with a coding agent
The plan has to be somewhere the agent can read and write without you copying it in. In ProductBrain the same tree is a canvas for you and an API for the agent: it can search the plan, read a node in context, add a job under the right approach, and record what changed. It works over a REST API, an MCP server, or plain files (the plan exports to JSON and to an OKF markdown bundle), so the plan is yours and portable. The free tier includes the API, up to a hundred nodes, which is more than a small product needs for a long while.
The honest limit: a plan only helps if it is kept true. That is a habit, not a feature. What the tool does is make the habit cheap, because the agent that did the work is the one that records it.
Read one
The quickest way to see the difference is to read a plan for a product you already know. Here is one for Ghost, the publishing platform, reconstructed by a coding agent from the public repository: the goals, the needs, the bets and their status, and the jobs that check each bet.