I don't write the documentation

Before the second brain, which I wrote about in the previous article, there was a dumber problem, and an older one: every session started from zero on the project itself.

A 2,400-line README

Early 2026, I am still on Cursor. The app is moving, the radio server is running, and I already have written instructions. A 2,400-line README in the backend repo: Payload's original template, security rules added as we went, and next to it a folder full of audits and investigations. A document for the agent, and for me, back when I didn't yet let it touch the server.

Sometimes the agent found the right information. It read the repo structure, found the procedure, did what had to be done. Sometimes it didn't. And I never knew in advance which it would be.

So I spelled everything out. "Restart the server. Careful, we have a procedure so the stream doesn't cut out. Find it, confirm you have it, then apply it." And I said it again every time we touched the server.

In March, we stopped. On the 11th, the first manual went into the backend repo, a .ai/ folder: architecture, domain, flows, rules, automations. On the 16th in the app, on the 19th on the website. The CLAUDE.md files only came a few weeks later, with Claude Code. I wrote those manuals for Cursor, so I would stop having to explain everything again.

Today I say "restart the server", and the agent knows how we do it. "Go and see how many listeners we have right now": the machine's SSH alias, what runs on it, which URL exposes what, it is all written down. And on the agency website, "add a page with this content" means Astro, content that comes from Sanity and never from the code, the design system with its scales, and the writing rules that go with it.

The line that prevents a disaster

In DIA's infrastructure manual, there is one line that has probably saved me from a few disasters: the folder of audio files on the server is not the source of truth. It is a cache, sized for the next twenty-four hours of programming. Whatever isn't there is in archive storage. A missing file does not mean a lost file.

Without that line, an agent looking for last week's episode and not finding it concludes that data has been lost. At best it investigates a problem that doesn't exist. At worst it "fixes" it.

Same thing for what is forbidden, by name. On the backend, the routes that move files before and after broadcast are marked dangerous: they only run with an explicit switch on top of authentication. It is written in the manual, with the reason.

That is what I look for in a manual: what you need to know before acting, what you don't do alone, and what isn't what it looks like. The rest, the agent finds in the code.

Documentation is my job

Specifications, functional specs, PRDs: that is my job, and I still do it. Documentation is essential on a project, it always has been. With agents, even more so.

Alone on a project, you have everything in your head. You document well at the start, then you get into the production flow, one thing after another, and the documentation slips. The project grows, and one day it becomes a real problem.

Today the agents document at the same time as I work, on what we are building or what we just finished. While we develop, produce and test, they write the docs, the specs, the changelogs, the backlog items. I have my project manager, my scrum master and my senior dev next to me, documenting everything as we go. You can't get more agile than that.

Written for agents, readable by humans

Documentation is now written for agents first. An agent opens the project several times a day, with no memory of the day before, and it goes back to what is written, every time. But it has to stay readable by a human, because the day someone steps in on the project by hand, that is the documentation they read.

And I am not the one writing it. Agents write the documentation for agents, so that everyone works properly, humans included.

The agent has just spent hours in the repo. It has read the code, not my description of the code. It knows the real structure, the real dependencies, the places where things get twisted. I describe the project from memory, it describes it from the code.

I check. Is it right. Does it say clearly what we don't touch. Has it made up a rule I have never followed. And when I correct something, the correction goes into the documentation. My client emails are drafted by Claude and reviewed by me: every draft I reject becomes a rule in a writing file, with the rejected example and the right version. The next email applies it without my having to say it again.

What it looks like

A short CLAUDE.md at the root, which the agent reads at the start of every session. An AGENTS.md next to it, three lines pointing to the first one, for Codex and the others. And when the project grows, a .ai/ folder that carries the detail, so that CLAUDE.md stays a table of contents.

The skeleton is the same on all our projects, twenty-eight of them today:

The step-by-step setup, with the prompt that gets the agent to fill all of this in, is in a separate guide.

A wrong manual is worse

A manual describes a project at a given moment. The project moves, the manual doesn't. After a few months, part of it is wrong, and a wrong manual is more dangerous than no manual, because the agent believes it.

It happened to me while writing this article. I had two plans for what came next in the journal: a note in the brain, and a roadmap next to the articles. They said different things, and the roadmap was still carrying a line written one morning in August and made obsolete the same evening. Claude believed it, and announced the wrong article as the next one. We went back through the git history together to find what I had actually decided, we fixed the roadmap, and the brain note now points to it. There is only one plan left.

All of this is permanent work in progress. We get things wrong, we correct them, and the documentation and the processes fit a little more closely to the way I work each time. That is what I like most about this system: it is never finished, it takes shape as you use it.

For the documentation, I simply ask. "Is the documentation still up to date? What has changed, what needs fixing?" The agent has just been working in the code, it sees the gap straight away. It gives me a list, I approve, it fixes.

Do it once, twice. The third time, you know what to do with it: a skill. A process written once and replayed identically, which the agent writes itself because it has just followed it three times with you. Skills deserve an article of their own, with the ones we actually use. It is coming.

The same move, twice

With the manuals, I stopped explaining my projects. With skills, I am stopping explaining how we work. I no longer ask myself whether I have time to write something down. I ask whether I want to say it again next week.

A manual makes a project readable. Twenty-eight manuals in the same place, next to a brain and a handful of skills, do something other than make twenty-eight projects readable. That is next month's article, and it is what really changed the way I work.