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.

Read the argument →Go straight to the library

34 documents · 20 Hard-Won · 6 curated packs · free to read and free to use

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.
Rootnotes Business context Design system context
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.
A documentation standard
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.
Working agreement Operational runbook
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 34 documents

Written 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.

The canonSeven invariants every document satisfies. What gets rejected, and why.RootnotesDocuments that live in a project root and tell an agent what the code cannot.ContributingWhat is worth submitting, how review works, and what rights you keep.

Curated packs

All packs

Measuring your own workFive failures from building a tool that scores code quality: what the proxies actually measured, what the checks never examined, why validation had no oracle, and what an authoritative interface costs when it is wrong.5 documents Project root starterEvery rootnote in the library: the commercial, privacy, documentation, design and editorial context an agent cannot read from the code.9 documents Security baselineThe floor for any project an agent works in: process hygiene, credential handling, and dependency discipline.3 documents Shipping a desktop appSigning, notarisation and signed self-updates for a desktop application distributed outside an app store.4 documents Testing without the live serviceDrive the interface by stable identity and fake the network, so a full journey runs headlessly with no live external calls.3 documents New edge projectStanding up a site or API on edge infrastructure without the reputation and credential mistakes.3 documents

By area

By kind

Recently confirmed

Nothing was wrong, or nothing was examinedThree checks that passed because they had no subjects, and why the fix is to make each one declare how many things it looked at.
Four ratios, four different failuresFour ratios used to score code quality, and four different reasons each one measured something other than what it claimed.
We could not get ground truth, and it took three attempts to accept itThree attempts to validate a scoring tool against human judgement, and why all three failing was evidence for the tool's premise rather than against it.
When the tool disagrees with you, neither of you gets to winWhat to do when a tool built to outrank your judgement is wrong, given that overruling it destroys the only property it had.
Working with AI is a handover problemWhy every session starts cold, what follows from that, and the four layers that turn context into something an agent can be handed.

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