CLAUDE.md vs a living plan: what each one is for
You need both. A CLAUDE.md holds the rules. A plan holds the state. Trouble starts when a rules file is asked to hold the state, and it starts quietly.
3 min read"Isn't this just CLAUDE.md?" is the question we get most, and it deserves a straight answer.
No. But it's a fair question, because many people use CLAUDE.md as a plan, and that works for about two weeks.
What a CLAUDE.md is good at
CLAUDE.md, AGENTS.md, and .cursorrules are the same idea: a file the agent reads at the start of every session. It's the right place for anything that is true every time.
- The stack and how to run it
- Conventions for naming, folder layout, and tests
- Things the agent must never do, like touching the migrations folder or committing secrets
- Where to look for what
That is a rules file. It's static on purpose. It should change rarely, and when it does, something about how the project works has changed.
Keep it. Every project should have one.
Where it stops working
The failure isn't dramatic. It's drift.
You add a "Current work" section. Then a "Done" list. Then "Decisions," with dates. Then a TODO.md beside it, then PLAN.md, then NOTES-auth.md because the auth notes got long. Six weeks later the repo holds forty planning files, half of them stale, and every session opens with the agent reading twelve thousand tokens of history to find the three lines that matter.
Three things have gone wrong.
The file describes where you were, not where you are. An agent that finished a task in another session didn't update it. The next session reads a plan that is already out of date.
It exists in one repo. Your thinking happens in a chat window. A teammate works in Cursor. A cloud run happens on a VM. None of them see the same file at the same moment, and the chat window can't see it at all.
Nothing writes back. From the agent's side, a rules file is read-only. What it decided, what it tried and abandoned, what it needs from you: all of that goes into the transcript and dies with the session.
What a plan is for
A plan is the opposite kind of object. It changes every session because work happens every session. To do its job it has to be structured (modules, tasks, acceptance criteria, an order), shared (the same object whether you're in Claude Code, Cursor, a chat window, or a phone), writable by the agent (status, comments, decisions worth keeping), and readable by people who never open the repo.
A file in the repo can be structured, at a stretch. It can't be the other three. Those require the plan to live somewhere every agent and every person connects to.
Side by side
| CLAUDE.md | A living plan | |
|---|---|---|
| Holds | Rules and conventions | Work: what's done, what's next, what's blocked |
| Changes | Rarely | Every session |
| Written by | You | You and every agent |
| Lives in | The repo | A workspace every agent and person connects to |
| Read from | That repo, in an editor | Any agent, any editor, the cloud, a phone |
| When it's wrong | Someone forgot to edit it | It updated when the work happened |
How they fit together
In Scope Architect the split is explicit. Always-on rules do the job a CLAUDE.md does; every agent reads them on every session. The plan is the tree of modules and tasks. Memory is where agents and people record decisions worth keeping. When an agent settles something mid-task, it writes it back, and the next session starts caught up.
Your CLAUDE.md gets shorter, not longer. It goes back to being a rules file, and the state moves somewhere that can hold it.
The honest version
If you are one person, on one repo, in one editor, and you don't mind rereading a big file every session, CLAUDE.md plus discipline gets you a long way. Plenty of people work that way and it's fine.
It stops working the moment there is a second agent, a second person, or a second place the work happens. If you're building anything real with agents, that moment is soon.