This guide is for developers whose project has outgrown a single session with a coding agent. You get the set of files and rules we keep in every project, so that whoever picks it up next, a person or an agent, starts from the facts.
The project instructions file
Every project has one file the agent reads first. In Claude Code it is CLAUDE.md at the root. Ours holds, in this order:
- what to read next, and in which order;
- how we work together;
- fixed rules, each with its reason;
- the local environment: ports, container names, what not to touch;
- decisions already closed, so they are not reopened by accident.
It is a living file. Every time a decision is taken, it goes in. Every time the agent makes a mistake a rule would have prevented, the rule goes in, with the story of how it was found.
Separate files for separate questions
Three questions keep getting mixed up, and each deserves its own file:
| File | Answers |
|---|---|
| a status file | where are we now? Rewritten when the state changes |
| a change log | what was touched, and when? Only ever added to |
| the notes | what did the owner actually say? Kept in their words |
A to-do file holds everything still open: to do, to decide, to test. One list only. Two lists of the same things drift apart, and nobody notices until they disagree.
Recaps and reports
At the end of each step, a short recap in its own file: what changed, how it was checked, what is left. At the end of each plan, a report. Recaps of closed work are not rewritten later, even when names change: they tell how things were on that day, and that is their value.
Isolation on a shared machine
If several projects run on the same computer, each gets its own block of ports and its own container names, written down in its instructions file. The point is not only that they can run together. With distinct ports, a command aimed at the wrong project fails instead of quietly hitting the wrong database.
Add a list of things the agent must never do on that machine. Ours includes never deleting Docker volumes, even when Docker calls them “reclaimable”: an unused volume is often another project’s database, stopped for the day.
Data that is not yours to delete
Write down, explicitly, that the agent never resets or drops a database, and never deletes rows it did not create. Test data the agent creates should carry a marker, such as a dedicated email domain, and be deleted only by the identifiers it recorded, never by a broad condition.
Test data entered by a person trying the product counts as real data.
Measure, do not look
The most useful rule we have is this: a screenshot is not a check. A page can look empty and be complete, or look right and be broken in ways no eye catches. Alignments, contrast, sizes and states are measured, in the browser or with a script. Behaviour is checked by running it, not by reading the code that should produce it.
Then check the tool as well. Before trusting a clean result, feed the check a case that must fail and see whether it does. A check that has never failed may not be checking anything.
Git, locally, from day one
Even without a remote, commit at the end of every step. It costs nothing, and it turns “what did we change last week?” into a command. Remember what git does not protect: the data inside the database and the uploaded files need their own backups.