Three files per feature

Jul 2, 2026 · 4 min read · #ai #agents #notes

For any feature I’m working on with an AI agent, the notes live in three files.

A typical folder for a feature I worked on recently looks like this:

projects-feature/
├── overview & index.md
├── data pass contract.md
├── journal.md
├── UI flows reference.md
└── local read endpoints (unblock).md

Three of them are the ones I keep for every feature: the contract, the journal, and the overview. The other two exist because they earned their own file.

The contract goes first

I write the contract before I write code. It’s the highest-level requirement for the feature: the business logic and the data points that need to resolve, in the language a stakeholder would use. It says what has to be true when the feature works, rather than how the code gets there.

Once the contract is written, the agent has a fixed target to check against. I can hand a fresh agent the same contract and ask it to validate the code, without either agent reading the other’s session.

This is test-driven development one level up. In TDD you write the test first because the test is the executable spec for the code. The contract does the same job in plain language, and the agent (or I) checks the implementation against it.

The journal is a different job

The journal accumulates. Every decision the agent (or I) made and why. Every bug it hit and the fix that stuck. Every piece of PR feedback that changed how something worked. Anything that helps a future session pick up where this one left off.

A journal has one job: preserve the trail. When a later agent inherits the work, it reads the journal and knows what was tried, what was ruled out, and why the code looks the way it does. When something breaks two weeks later, the journal is where I look first.

The overview is a router

The overview is small. Links to the contract, the journal, any extra files, the ticket. It exists so an agent starting cold knows what lives in the folder and where to go for what.

Not much else belongs in it. The moment a line here needs more than a sentence of explanation, that explanation goes in the contract or the journal, and the overview keeps only the link.

What the split buys

Token cost is the part I can put a number on. The three files in that folder, as of today:

Reading a note is all-or-nothing. Answering “how does X work?” out of the journal costs the whole 10K every session. Answering it out of the contract costs about 2K, roughly 4× less. The contract stops growing while journals append forever.

One reason to change

A note should have one and only one reason to change.

If a business rule shifts, the change happens in the contract. Bug fixes, decisions, and PR feedback go into the journal, and the contract only changes if a fix reveals a rule that was wrong. The overview stays small: a new agent reads it to figure out where to look, and that’s most of what it does.

That separation is why I can run two agents on the same feature. Session A implements against the contract. Session B validates the code against the same contract with no other context. If they agree, the contract earned its keep. If they disagree, either the code missed something or the contract wasn’t specific enough. Both outcomes are useful.

It’s not exactly three

The folder above has five files. If the feature needs a UI flows reference, that’s its own file. If a subsystem needs an unblock note, that gets a file too. Three is the minimum I reach for. I add a fourth or fifth when a file starts doing two jobs. For example, when UI-flow notes start piling up inside the journal note, they move into their own file instead.