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

43 documents · 22 Hard-Won · 7 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 43 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 Design contextWhat a design project needs an agent to read before it touches anything: the system, the accessibility floor it is held to, and where the work stops.3 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

A pointer rootnote — addresses, not knowledgeThe one rootnote that contains no instructions and no content, only addresses — and why each entry should name the decision at which it becomes relevant rather than the activity it describes.
Nothing was wrong, or nothing was examinedFour checks that passed because they had no subjects — three in a scoring tool, and one set that caught this document's own author an hour after he went looking for them.
Research context — what has been established, and what has been ruled outThe rootnote a research project needs an agent to read before it starts, and the dead-ends record that is the most expensive thing in any project to rediscover.
Auditing a context file you already haveA pass over an existing AGENTS.md or CLAUDE.md that decides, passage by passage, what is worth its tokens — and the three questions that decide it.
What earns its place in a context fileTwo tests decide whether a passage is worth its tokens, and applying them to twelve rootnotes found that padding accumulates in documents that explain and almost never in documents that constrain.

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