Last time, we chose a comfortable interface, dealt with the agents' private notebooks and put up a straightforward sign: everything about the project belongs in the project. One small thing left: put something useful in there.
Creating a docs folder is easy. Ask an agent and, within minutes, you can have enough beautiful files to award yourself a certificate in organisational excellence. The trouble starts later, when you need to know why yesterday's decision was made, who's changing the neighbouring component and whether a task is actually finished.
I want documentation that tells an agent where it has arrived, what we're doing and how to continue. That's where I'd start.
First, explain what we're building
Suppose we're making a catalogue of books at home. This is a teaching example, not another project I'm starting. Given my tendency to get distracted, the article could otherwise end with a new app.
The problem is simple: lots of books, and I'd like to see what we own, where they are and who's borrowed them. The first version needs a title, author, shelf location and a note about the borrower. Everything stays local, family synchronisation can wait, and we aren't building an ebook shop.
Those last two points may be as useful as the first four. An agent could reasonably decide a catalogue needs accounts, a server, an external book database and cover recognition. Sensible ideas? Certainly. Do I need them now? I wanted to stop buying a second copy of the same book.
We begin by recording the intention and boundaries: who it's for, which annoyance we're removing, what the next version should do and what we're deliberately leaving alone. If something is undecided, say so. “Undecided” is more useful than an agent confidently imagining what we must have meant.
This is where discussing the idea helps. I explain it in my own words, answer questions, examine the agent's understanding and correct it if necessary. It can help shape the thought, but I need to recognise my own problem in the result. If I asked for a catalogue and received a business plan for a book marketplace, preparation isn't finished.
How many files do we need?
Enough to find and update what you need without mounting an archaeological expedition every time. Evasive, I know. But I don't believe every project needs the same folder of twenty-five compulsory documents on arrival.
I have mobile apps, and I have this project where we're preparing articles. Articles don't have Android builds. They do have author-edited text an agent mustn't silently rewrite, and stories I don't yet want published. Import every messenger rule here and we'd get an exceptionally well-documented mess.
Our teaching catalogue could start small:
book-catalog/
├── AGENTS.md
├── README.md
└── docs/
├── idea.md
└── work.mdThe last two names are just examples. If an existing project already has suitable documents, don't rename them to match my diagram.
AGENTS.md explains the working procedure: what to read before changes, which rules to follow and where to record results. README.md explains what's in the directory and where to find the relevant parts. idea.md holds the intention. For now, work.md needs only two sections: outstanding work and decisions already made. We can separate them as the project grows. At present, we haven't catalogued one book and we're already establishing an administrative department.
The most useful part is how the documents connect. The agent reads the entry instructions, finds the intention and current work, then knows where to return with its result. If each file exists independently and is discovered only by luck, you have a collection of texts.
I call that connected procedure an algorithmic documentation structure. The documents suggest the next step: what to read, which decision to check, where to leave new information. Without asking me for directions every time.
Instructions you can actually follow
The project's AGENTS.md doesn't need another portrait of the ideal programmer from my magic-prompt collection. It needs clear instructions the agents can follow. For our catalogue, the opening might be:
Before making changes, read README.md, docs/idea.md and the current tasks in docs/work.md. Check the working directory's state so you preserve other people's unfinished work.
>
Don't expand the first version's scope without discussion. If a task conflicts with an accepted decision, show the conflict and clarify it before implementation.
>
After the work, record the result, verification and remaining questions in docs/work.md. Reflect agreed changes to the intention in docs/idea.md. Sign entries with the agent's name and session ID.
>
Don't present a plan as completed work, or a successful build as a human usability check.
A reader from earlier instalments is probably raising a hand: “Alex, you said prompts were rubbish, and now you're giving us instructions for agents for the second article running.”
Yes. I still have to explain the job in words. I've given up “you are the greatest developer”, not task descriptions. Each requirement here can be checked: was the file read, the result recorded, the verification supported? And the instructions live beside the project, where we can update them with the process.
I also want both main agents reading shared rules, rather than two editions drifting apart. We covered connecting Claude and Codex to a common project document in article six. Now the job is filling it with the rules of this particular project.
The file needs instructions too
We've told the agent where to write. We should also tell it what belongs there. Otherwise, “record the result” quickly becomes a retelling of the session, including three failed command attempts and congratulations to itself on a productive day.
At the top of each working document, I want its purpose, entry structure and boundaries with neighbouring documents. Our work.md could say: current tasks at the top, accepted decisions and their reasons below; no detailed logs; look in idea.md for the intended product.
Then the synchronisation decision might read: “For version one, keep the catalogue on one device because we're testing whether maintaining the list is useful. Family synchronisation is deferred; revisit it after checking the basic workflow.” A made-up decision for this example, but you can see why we made it and when to reconsider.
Write only “synchronisation isn't needed” and the next agent may treat it as an eternal law of nature. Later we'll have to discover where this permanent ban came from, when nobody intended one.
Unfinished work needs the same care. “Continue the catalogue” says almost nothing. “Adding a book is implemented; saving title and author has been checked; next, check editing the shelf location” gives the next agent somewhere to start. Provided it's true, of course, rather than an attractive report of its anticipated future success.
Can we avoid setting this up by hand every time?
Yes. This is where the repeatable process comes in.
I have a friend whom I helped move from copying code through ChatGPT to letting Codex work directly with files. Eventually, he had more projects and familiar questions: why does the agent get stuck, why do I keep explaining what we're doing? I helped separate the projects, transfer useful notes and establish documentation rules.
The rules turned out to transfer quite well. He didn't need to turn his projects into my messenger to use them. His document collection was different, but the general procedure survived. According to him, things finally began working as he'd initially wanted. I occasionally looked in to tidy an agent's private notebooks, but I no longer needed to stand over him with the instructions.
I'd standardise the questions a project must answer and the procedure for preparing it. A starter task might be:
Prepare this project for work by multiple agents that can replace one another. First, read existing instructions and inspect the directory without changes. Briefly explain what is known about the project's purpose, what documentation exists and what is missing before work can begin. Don't ask questions already answered in the documents; raise contradictions and genuinely unknown things for discussion.
>
Propose the minimum documentation needed for this project. Reuse existing files where suitable. For each document, specify its purpose, maintenance rules and relationship to the others. Distinguish the intention and accepted decisions from current tasks and verification results.
>
After agreement, create or update those documents while preserving others' changes. Connect them through a clear entry procedure in the project instructions. Don't fill gaps with invented facts or create sections merely to have sections. Don't change application code as part of this task.
I'd adapt that to the actual work. A new project needs more discussion. An established project needs an examination of what's already there; otherwise, the agent may happily build a new system beside the old one and congratulate us on getting organised. Been there. Thank you.
And I always read the result. If an agent creates a server-state log for a writing project with no server, we need to revisit the purpose of the documents, rather than admire its foresight.
Test it on the next agent
The first check doesn't require a grand experiment. Open a new session, give the agent only the project directory and ask it to read the documents, then explain what we're doing, where we stopped, what comes next and where the reason for that choice is recorded. No changes yet.
Don't tell it the whole history first and then test its memory. Let it find the history and show its sources.
If it can't, investigate. Does a link lead to the wrong place? Did a decision remain in an old chat? Do two files contradict each other? Or is everything recorded, but the agent decided reading was optional? Those are different problems. Another large document won't fix all of them.
Then observe real work. One agent finishes a task and records the result. The next understands what's done, what's open and what needs my decision. That's when documentation starts paying its way.
To make those entries traceable, I ask each agent to sign the sections it writes with its name and session ID. The name tells us who made the entry; the ID distinguishes one run from another. If we later need to understand where a decision came from or how a task ended, that gives us a clear lead instead of leaving us to guess.
Recently I noticed another pleasing effect of signatures. We used to have a jumble of entries with no clear author. Now the agents see who is doing what. Claude says something like: I'm ready to continue, but Codex is working there; let's wait for its commit, then decide who deploys what. “I didn't do that” becomes “my colleague is doing that; I won't get in the way”.
Two extraordinarily well-mannered employees. Who'd have thought?
A signature didn't magically teach them manners. But they now have shared information they can use to coordinate. An agent name, a session ID and a current work status proved more useful than another appeal to “work together and make no mistakes”.
That's enough to begin: a small collection of useful documents, clear instructions for entering the project and recording results, and a check during a real change of agent. The rest can appear as needed — and sometimes disappear, because the system has to keep up with your work.
Why I still occasionally have to say “read the bloody docs” is a story for another time. It involves a dog with perfectly valid ownership papers who nevertheless sleeps wherever he likes.