Writing for an agent that starts from zero
Every Claude Code session starts from zero. It doesn’t remember yesterday’s decisions, the bug we found last week, or why a strange line of code is there. It knows what it reads at the start of the session and what it finds in the code.
That changes what documentation is for. It’s no longer a courtesy for the next person on the team who might skim it. It’s the agent’s working memory, and the quality of the agent’s work depends on it more than on any prompt I type.
On Pressa I can open a new session and type one word, “continue”, and the agent knows which task is next, which rules apply to it and which guide to read first. The project file says so explicitly: if the agent needs more context than that, the docs are incomplete, and that’s a bug to report before asking me anything. That’s the standard I hold the docs to.
One entry file, written as an index
Each project has a CLAUDE.md that Claude Code loads automatically. Mine aren’t short. The Pressa one is 325 lines. But they are written as an index, not as an encyclopedia:
- Who the agent should be. Brutally honest, critical of my ideas, never acting on a guess. If it isn’t sure, it asks first.
- Where everything is. A map of the docs folder: current state, completed work, guides by area.
- Triggers. “Before you add a new way to compile a document, read the quota guide first.” “Before touching domains or headers, read the infrastructure guide.” These are the most valuable lines in the file, because they route the agent to the right context at the moment it needs it.
- Commands it will need. How to run tests, open a production console, deploy, release a package.
- Never and always. Short lists, each item learned the hard way.
The details live in separate guides that are read on demand. The Choose.place file puts the reason plainly: every line the agent reads is paid for again in every call that follows. A thousand lines of background loaded into every session makes every session slower, more expensive and less focused.
A log the agent writes for the next agent
At the end of every task, the agent updates two files. PROJECT_OVERVIEW.md is the current state and says what’s next. COMPLETED_TASKS.md is the log: what was done, what decisions were made, what the review found, what was deliberately left out. On Pressa that log is now more than 3,300 lines long, on Choose.place more than 3,400.
The log is how the next session knows that a strange choice was deliberate. Without it, a fresh agent will “fix” something you decided on purpose two months ago, with complete confidence.
Every mistake becomes a rule, with the reason
When something goes wrong, the fix isn’t finished until the rule that would have prevented it is written where the agent will read it. And the rule always carries its reason.
Two Pressa pull requests once passed all of their tests locally and failed in CI, because CI loads code eagerly and my local setup didn’t. The rule that came out of it doesn’t just say “run the tests with CI=true”. It says which setting causes the difference, which two problems slipped through, which commit fixed them, and exactly which kinds of changes require the extra run. An agent that knows why a rule exists can tell when it applies. An agent that only has the rule applies it blindly or skips it as noise.
Claude Code’s memory follows the same pattern. Each memory is one fact, with a Why line and a How to apply line. “Any request header written to the database must be scrubbed first” is a rule. Adding “because valid_encoding? returns true on binary strings, and a bad User-Agent once silently skipped the quota” is what makes it stick.
A rule in prose is a suggestion
On the client project there’s a rule that an analysis must be checked from several independent angles: the code, the documentation and tickets, the running system on staging, and the primary source. It was written down clearly. One day a session read it at the start, and then skipped it anyway.
So the rule changed shape. Every analysis now has to end with one line:
Passes: code ✅ · docs + tickets ✅ · staging ✅ · primary source ➖ (and why)
The agent can still skip an angle, but it can’t hide that it did. If a rule matters, give it a form that has to be filled in. Prose depends on good intentions, and agents have the same relationship with long instructions that people do.
Documents age
A sentence in a guide was true on the day it was written. On the client project the docs say it outright: environment facts, like which credentials exist, what runs on cron and which service reads what, are checked live, not taken from documentation. A document older than a few weeks is a hypothesis, not proof.
The other half of that rule: when an agent finds an error in the docs and confirms it, it fixes the document immediately, in the same session. Not “I’ll note it”, not a mention at the end. Otherwise the next session reads the same wrong sentence and acts on it.
Tickets are the hardest documents
When a ticket goes to an agent, the agent sees only that text. It can’t ask the person who wrote it what they meant, and it won’t notice that the text contradicts a conversation it never saw.
I learned this on three tickets I wrote for the client project when I was sure I understood the problem. Before handing them over, I ran a check of each ticket against the code. It found:
- an instruction to swap width and height for rotated videos, which Rails already does, so every rotated clip would have ended up sideways;
- a
CASEexpression that would sort items with priority 0 above the ones that need action; - a
NOT IN (1, 2)condition that silently drops every row where the column is NULL, more than two hundred of them; - the wrong test file name, in all three tickets.
Since then, every ticket goes through a review loop against the code after I write it, and every round goes through the same list:
- Every name exists exactly as written: method, constant, file, test file, column, route.
- Every SQL snippet returns exactly the set the text describes, including NULLs and out-of-range values.
- Every claim about framework behavior is checked in the gem’s source, not from memory.
- Every “done when” can be written as a test with the existing fixtures.
- No decision is left as a suggestion. Nothing forces the agent to guess.
- A term defined in two tickets is defined identically, and the order of work is written down.
- The ticket doesn’t ask for something that already exists.
- The ticket doesn’t ask the agent for something it can’t do.
The last one came from a ticket whose acceptance criteria said “file an issue for any gaps you find”. The agent on my home server has no access to the issue tracker, so the completeness check kept failing and sending the ticket back. Now gaps go into a file, and I open the issues.
The loop stops when a round finds nothing new, with five rounds as the limit. If the findings are still changing after five, the ticket doesn’t get the agent-ready label. I write down what’s unresolved instead. Technical uncertainty, like a field name or the shape of a response, I resolve myself from the code and write in as a decision. Real business questions go to the client before the ticket is ready.
What this costs, and what it buys
Keeping docs this way takes time, and most of it is spent at the end of a task, when I’d rather move on. The agents do most of the writing. My part is insisting that it happens, and reading what they wrote.
What it buys is that a session that starts from zero doesn’t stay at zero for long. A new agent, on a new day, in a fresh worktree on a server in my home, can pick up a ticket and work by the same rules I would. When it doesn’t, the reason is almost always a missing sentence somewhere. Then that sentence gets written.