The Document-First Principle
In the previous chapter, we looked at the idea behind a design that requires verification and recording in proportion to the irreversibility of an action. This chapter sets down what this project calls the document-first principle — the rule that treats the act of recording itself as a structural requirement.
What the Document-First Principle Is
The document-first principle means making decisions and work judgments by leaving them in files and written records rather than relying on spoken words or memory.
You might think: "Isn't that obvious?" In practice, when you run a system that coordinates multiple AI agents, this obvious point becomes especially important.
Between humans, you can confirm a decision with a quick question: "We agreed on this earlier, right?" AI agents have no persistent memory across contexts. Once a session ends, what was decided and why a particular design was chosen simply disappears — unless it was written down.
That is why "keeping records" is not a best-effort goal. It is a principle that the structure itself requires.
Why Recording Makes a Difference
Keeping things in writing has three main benefits.
The first is the ability to review a decision after the fact.
Whether a particular call was right or wrong often becomes clear only after you act on it. Without a record of why that decision was made at the time, there is no starting point for review. You are left with a vague sense that something went well or something went wrong, and that feeling does not lead to improvement.
With a record, you can compare what you assumed, what you decided, and what actually happened. Over time, that comparison gradually sharpens the quality of your judgments.
The second is the ability to trace accountability.
In a structure where AI handles work, it is easy to lose clarity on who decided what. If both AI output and human approval flow by without anyone noticing, there is no way to identify the cause when something goes wrong.
The document-first principle also means leaving an audit trail (here meaning: a record you can return to later and verify) — noting which role made which decision at which point. With an audit trail, you can analyze the cause of a problem as a structural issue. Once you understand the cause, you can design a fix to prevent it from recurring.
The third is the ability to hand off to another AI or the next person.
This benefit becomes especially clear when you are using AI agents. When you need to pass a design decision made in one session to the next session, without documentation you have to explain everything from scratch. But if the reasoning behind the choice, the rationale for selecting it, and the alternatives that were ruled out are all written down, the next AI can pick up exactly where things left off. The same applies when a human team member changes.
Reducing handoff cost is a condition for running an organization that can keep moving.
How This Works in Practice
Understanding the principle is one thing; without a clear picture of what to write and how, nothing gets done. What follows is a record of the approach this project is actually using.
Write decisions down in a file at the moment they are made.
"I'll write it up later" is effectively the same as not writing it at all. Immediately after making a decision or changing a design, put it into a file — even one to three lines. Adding a single note about why you chose this option and what alternatives existed changes how readable the record is when you come back to it.
Put files somewhere they can be found.
A record that was kept but cannot be found is almost the same as no record. Ideally, you settle on three things upfront: a naming convention, a storage location, and an index. In this project, a designated place for design documents has been made explicit, and files are updated whenever something changes.
Do not try to write everything perfectly.
The biggest enemy of the document-first principle is getting blocked because you are trying to write something complete. Bullet points, a single-line memo — whatever is left behind is clearly better than nothing. Build the habit of leaving traces of decisions first, even rough ones. The quality of those records can be improved later.
Keeping records is also a matter of integrity. Writing down why a decision was made creates a state where you — or someone else later — can genuinely take responsibility for that decision.
That said, as records accumulate, a different problem appears. When records are scattered across multiple places, it becomes unclear which one holds the latest correct information. The more documents there are, the more the way they are managed also needs to be designed.