Your CLAUDE.md Is a Maintenance Job

If you run serious work through Claude Code, you have almost certainly written a CLAUDE.md. Maybe you also write a handoff at the end of a long session, so the next one starts warm instead of cold. Both are good instincts, and I want to be clear about that before I say anything else: writing down what your AI should know is the right move. If you are still weighing which of those instincts to reach for, there is a practical guide to keeping Claude Code context between sessions. This is about what that file quietly turns into on a project that lasts.

Instructions are not state

A CLAUDE.md is mostly a set of instructions. Follow these conventions. Prefer this library. Do not touch that directory. That is exactly what the file is good at, and Claude Code loads it at the start of every session to do it.

But a long-running project also has a state that is separate from its instructions: what has actually been decided, what changed, what got ruled out, and what is still open. Instructions tell the AI how to behave. State tells it what is currently true. The two feel like the same thing when the project is young, so they end up in the same file. Then the work moves, and it is the state half that goes wrong first, because state changes far more often than conventions do, and it changes in places the file never sees.

One instruction, one later decision

Here is the shape of it, from the kind of situation anyone running a long build will recognize.

Early on you write, in good faith: “Split each new module into its own service.” At the time that is the plan, so into the file it goes. Two months later, after a week of fighting your own infrastructure, you and a colleague decide on a call to stop doing that. Monolith-first from now on; extract a service only when a piece proves it needs one. That decision is real, and it governs the project from that afternoon onward.

But it happened in a conversation. Nobody edited CLAUDE.md. So the file still says split each new module into its own service, and the next session, reading the file, faithfully does exactly that. The instruction did not lie. It simply never heard about the human decision that overruled it. Now your AI is building against a policy you personally reversed, and the only thing standing between that and a wasted afternoon is whether you happen to remember, mid-session, that the file is out of date.

Why the file rots

Nothing updates a hand-written context file except you, from memory, when you think of it. That is the whole maintenance job, and it is heavier than it looks, because the edits that matter most are the ones you are least likely to make. The decision reached at the end of a tiring session rarely feels worth a line. The path you ruled out three weeks ago leaves nothing behind to remind you it happened. The rule that turned out to have an exception stays in the file as an absolute.

Handoffs inherit the same weakness. A handoff is a summary written under time pressure, and a summary keeps what the writer thought to include and flattens the rest. It carries the latest decision but usually not the fact that it changed, or what it replaced, or who had the standing to make it stick. The things a readable summary drops to stay readable — superseded decisions, rejected paths, the source under a claim, a shift in who governs a call — are precisely the things you reach for when you sit back down and ask “wait, what did we settle on?”

More history is not the same as knowing what governs

The natural response, once this bites, is to give the AI more context. A longer CLAUDE.md. The full session logs. Three handoffs instead of one. It feels like it should help, and it mostly does not, because more history is not the same as knowing what currently governs the project.

If both “split every module into a service” and “monolith-first” sit somewhere in the record, reading both does not tell you which one is in force. It tells you both were said. Knowing what governs is a smaller and harder thing: a single current answer, with the reversed version explicitly marked as superseded, that a person has confirmed is correct. History is the raw material. State is the conclusion you draw from it, and the conclusion is the part you actually build on. A pile of true-at-the-time statements is not a conclusion.

Where this points

This is the problem the Project Continuity Founding Beta is being built around: people already running long-term work through Claude Code who are tired of keeping a context file true by hand. As it is being designed, the beta keeps the parts of a hand-written file that make it feel safe — your files stay on your machine, it reads only the folders and sessions you choose, it runs on your own key, and it changes nothing without your approval — and takes on the part that makes it a chore: reconstructing the project’s current state from the work that already exists, and keeping it current as the work moves, rather than waiting for you to notice the file is wrong. These describe the design of a guided beta being prepared, not the behaviour of generally available software.

A CLAUDE.md is worth writing. The trap is the standing promise folded inside it: that you will keep it true, by hand, for as long as the project lives. That is the job worth handing off.