The discipline of
collaborating with
an agent that forgets.

Every conversation begins with no memory of the prior one.

Each new session, the agent loads what it can — the project's claude.md, the memory index, your first message — and that is the entirety of its context. Yesterday's debugging path, the false trail you ruled out, the reason you chose approach A over approach B: none of it survives unless it was written somewhere the next session will read.

Most engineering tools assume continuity. Claude Code does not. The first time this catches you out, you spend an hour re-explaining the project. The tenth time, you start to suspect there is a discipline you are missing. There is. This manual describes it.

The question, once you accept the premise, is simple: what do you encode, and where? There are two slots, and they answer different questions.

Memory files hold the durable knowledge of a project — its architecture, its conventions, the gotchas you've burned hours discovering, the workflow rules you want to apply session after session. They are written once and consulted forever. They should be true on the timescale of the project itself, not on the timescale of any one task.

The handoff prompt holds the working set — where you left off this afternoon, what is in flight, what the next session should propose first. It is written at the end of every working session and consumed at the start of the next one. It has a known shelf life of exactly one session.

Together they form a protocol between past-you and future-you, with the agent as the courier. Get this protocol right and the agent is a long-running collaborator. Get it wrong and you have an expensive autocomplete.

Six checkpoints that should exist on every serious project.

The rules below are gates — moments where the agent stops and verifies before proceeding. They are not optional politeness; they are the difference between a session that ships and a session that introduces the bug it was supposed to fix. Six are universal. The rest grow on top, project by project, and earn their keep through incident.

Three rules that aren't gates, but should exist on every project.

Where the gates above are checkpoints, these are standing dispositions — reflexes you want the agent to have, encoded as feedback memories so they survive across sessions and do not require re-prompting.

What to paste on day one of a new project.

Treat this as session zero. The agent reads it, sets up the memory system and the standing rules, then waits for the first real task. Adapt the bracketed placeholders to your project; everything else is the universal core. Copy the block below.

You cannot write the full rule set on day one.

Because you do not yet know what is going to bite you. The memory system grows organically, in two ways, and the trick is to recognize the moments when accretion is happening.

From corrections. Every time you tell the agent "no, don't do that" or "stop doing X" — that is a feedback memory waiting to be saved. One project I work on has a rule against launching the development binary with the user's active display, because doing so once put a window onscreen and clobbered the running production app. One incident, one rule, never again.

From validations. Every time you tell the agent "yes, that was the right call" on a non-obvious choice — that is also a feedback memory. These are quieter, easier to miss, and equally important. Without them, the agent drifts away from approaches you have already approved, and you end up re-litigating decisions weekly.

Project memories accumulate similarly. You do not write them up front. You write them when you make an architectural decision worth not re-litigating in the next session. The trigger is simple: this should not need to be discovered twice.

What belongs in the starter prompt, and what does not.

The rules in this manual are universal. They should exist on every project where Claude Code does multi-session engineering work, regardless of language, framework, or domain.

Some rules are not universal and should not be in the starter prompt. A hardware-test gate only matters if you have hardware in the loop. A multi-endpoint release flow only matters if you ship to multiple distribution channels. A polish-pass discipline only matters if you want a deliberate "feature complete" pass over each shipped feature. A library-version-lockstep rule only matters if you publish a library.

These belong in the memory system once the project grows into needing them — not before. The starter prompt is scaffolding; the project-specific rules are the building. Trying to write them up front produces a generic checklist that nobody follows; letting them accrete from real incident produces a memory system that the agent and the engineer both trust.

Treat the agent as a long-running collaborator that has amnesia.

The discipline that makes any of this work is not any single rule. It is the meta-discipline of internalizing one fact and letting it shape everything else: the agent has amnesia, and it is your job to bridge the gap.

Once that fact is fully internalized — really internalized, not just nodded at — the rules write themselves. Anything that should survive amnesia goes in memory. Anything that bridges between sessions goes in the handoff. Anything that is a reflex you want the agent to have goes in a feedback memory. Anything that is true today and false next week goes nowhere; let it stay in the conversation and die there.

The project this manual is drawn from has roughly thirty memory files now. On day one it had zero. Each one was earned by an incident — a bug shipped, a correction given, a validation made explicit, an architectural decision worth not re-explaining. That accretion is the actual product. The starter prompt above is just enough scaffolding to make the accretion happen.

If the discipline feels heavy at first, that is because it is replacing something that used to be free: the assumption that your tools remember you. They do not. But once you start writing the memory yourself, the agent starts to feel less like a chatbot and more like the long-running engineering collaborator you wanted in the first place.