How to work with AI
Every session starts cold.
An agent arrives in a repository it has never seen, with a task it has no history for, and reconstructs from scratch what somebody already worked out three months ago — usually the hard way, usually the same hard way. That is not a memory problem to be fixed later. It is the permanent shape of the work, and it has a name in every other field: it is ahandover.
This site is about doing that handover deliberately: what to write down, where to put it, what it should say, and what the models actually do with it once it is there. Everything described is published here as a document you can take.
Take the course →Build your project's rootnotesGo straight to the library
49 documents · 21 Hard-Won · free to read and free to use
Where to start
The correction that changes what you build
Working with an AI is often described as working with a brilliant intern who forgets everything. The line is memorable, it is worth keeping, and it is wrong in the one way that matters.
It is not forgetting. It is never having known. Forgetting implies something was there and decayed, which suggests reminders. Nothing was there. Every session begins from an empty state plus whatever you handed over, and no amount of prior explanation changes what the next one receives.
What follows is not a memory aid. It is a set of documents that make the empty state a good one — written once, read every time, by something that was never in the room.
Working with AI is a handover problem — the full argument, including what we can and cannot claim for it.
The system, in four layers
Each answers a different question, and they are not interchangeable. Most projects have some of layer 2 and none of the rest.
- 1
Rootnotes — What an agent cannot discover
The commercial facts, the constraints somebody decided once, the conventions that are not in the code because nothing in the code disagrees with them. If it can be read from the repository, it does not belong here.
- 2
The documentation set — What was decided, and why
Decisions with their reasoning attached. An agent that knows what was chosen will follow it; one that knows why will notice when the reason has stopped applying.
- 3
The working agreement — How work happens, and where it stops
What may be run unattended, what must be confirmed first, and what to do when something is ambiguous. The stopping points matter more than the permissions.
- 4
A retrieval corpus — What is too large to hold
Everything that will not fit in a context window and should not be pasted into one — fetched when relevant rather than carried always.
No document yet. This layer is described in the system but not documented in the library.
There is a fifth layer — measuring whether any of this is working — and it is kept separate on purpose, because a half-built measurement tool with a confident interface is worse than no tool at all. The argument covers why.
The library
All 49 documentsWritten by people and their agents, read adversarially before publication, carrying their authors and their last-confirmed date with them. Take the file; you do not need an account.
By area
Recently confirmed
- A rootnote per tool — the vendor's half and the community's halfEach tool a project depends on deserves its own short rootnote in two layers — the vendor's map of its documentation, and a record of where it catches agents out, which vendors rarely publish.
- Brand and claims for an agent writing about the productThe exact name, the claims the product never makes, and how other companies' names and marks may be used — brand decisions an agent cannot infer from the code.
- Open source and licence policy for an agent adding codeWhich licences may enter the project, what even permissive licences oblige you to ship, and where code copied from anywhere — including generated code — has to come from.
- Supportability for an agent working on software people useWhere people get help, which versions are supported, and what an error message, a log line and a diagnostic bundle must and must never contain.
- Working agreement for an agent in this repositoryWhat may be run without asking, what must stop first, and how to report what actually happened.
Two standards, and which is which
Most of what is here is vetted: read adversarially by someone asking what an agent would do differently after loading it, and what could go wrong when it does. Some of it — the argument above, and the system it proposes — is this site's own position. That is stated on the page and in the file itself, because these documents get read inside repositories where no page is loaded.
Publishing an opinion is fine. Publishing one dressed as a review would not be, and diluting "vetted" until it covered both would be worse. How review works ·What you may do with any of it