Working with AI is a handover problem

Working with an AI is like working with a super-genius intern with dementia. Immensely capable, and holding almost none of the context the job needs. You cannot expect them to read your mind, and you cannot expect what you told them last week to still be there.

The line is memorable and it is worth keeping. It is also wrong in a way that changes what you should build, so it is worth correcting immediately.

It is not forgetting. It is never having known.

Dementia is the degradation of a memory that was there. An agent never had one. Every session begins from nothing, reconstructing from whatever is in front of it.

That distinction sounds pedantic until you notice it changes the fix. Forgetting is solved by reminding. Never-having-known is solved by a handover — and a handover is the harder of the two, because a reminder can assume shared context and a handover cannot assume any.

The metaphor breaks in two more places, and both are load-bearing.

An intern learns. Six months in they need less context than they did on day one. This is why teams that document badly get away with it: the intern accumulates what the documents never said, and the gap closes on its own. An agent never accumulates. The twentieth session needs the same brief as the first, and will need it again next month.

That is the argument for treating written context as infrastructure rather than courtesy: you cannot amortise sloppiness against someone who is new every time.

An intern asks. Told “come and find me if you’re unsure”, they will. An agent under-asks, and does it confidently — filling a gap with the most plausible reconstruction rather than stopping. That is not a flaw to be scolded out of it; it is a property to design around, and it is why the stop-and-ask boundary has to be written down explicitly rather than left to instinct.

What follows

If every session starts cold, four things stop being optional.

Context has to be written, not remembered. Anything held only in your head is unavailable to the work. The test is uncomfortable and clarifying: if you were unreachable for a fortnight, what would somebody need in order to continue? That is the corpus.

It has to be findable without knowing it exists. An agent cannot search for a constraint it has no reason to suspect. Structure and naming are not tidiness — they are the difference between a document that gets read and one that does not.

It has to say where to stop. Capability without a boundary produces confident action in exactly the places that need a pause. The boundary is the part nobody can infer.

It has to survive being extracted. These files get dropped into repositories and read by agents that never see where they came from. Anything true only in the original context is lost on arrival.

The four layers

Each answers a different question, and they are separable — adopting one is useful, and adopting all four compounds.

1. Rootnotes — what cannot be discovered

Documents at the project root carrying what the repository cannot state: the commercial facts, the conventions, the constraints somebody decided once, and the points at which an agent should stop and ask.

The test for whether something belongs here is whether an agent sitting in the repository could work it out. A framework is discoverable. A jurisdiction is not. A file-naming scheme is a choice nobody wrote down.

2. The documentation set — what was decided, and why

A linked set rather than a pile or one long file: about, architecture, features, decisions, tests, runbook, roadmap. One file per section so a narrow task loads a narrow slice, and links between them so a stale claim shows up as a broken relationship rather than a paragraph nobody reads.

The decision log is the highest-value part and the cheapest to write. The alternatives you rejected are clear exactly once — while you are rejecting them.

3. The working agreement — how work happens, and where it stops

What may be run unattended, what stops for a human, what an honest report looks like. The prohibitions matter less than one property: an agent’s report is not verification, and a reader should be able to predict what they will find when they look.

The tempo of that changes with how you work. A human present turn by turn makes asking cost seconds; a review gate makes it cost a day; unattended, there is nobody to ask and the correct move is to stop rather than to choose. Same boundaries, different cost of pausing.

4. A retrieval corpus — what is too large to hold

Beyond a certain size, context cannot be loaded; it has to be fetched. Reference material, prior decisions, transcripts, specifications. The design question is not which store to use but what a good answer looks like when the agent does not know what it is missing — which is a problem of chunking and naming far more than of embeddings.

What it looks like in a project

The layers are not folders. They are a way of reading files that mostly sit flat in the root, which is most of why this is cheap to adopt — you are naming and placing documents, not restructuring anything.

your-project/
├── CLAUDE.md                     the door — short, and points at everything below
├── AGENTS.md                     the same content, for a second tool
│
├── business-context.md           ┐
├── design-system-context.md      │  1  ROOTNOTES
├── data-handling-and-privacy.md  ┘  what an agent cannot discover from the code
│
├── working-agreement.md          ┐  3  WORKING AGREEMENT
├── runbook.md                    ┘  how work happens, and where it stops
│
├── docs/
│   ├── architecture.md           ┐
│   ├── decisions/                │  2  DOCUMENTATION SET
│   └── testing.md                ┘  what was decided, and why
│
└── src/                          the code itself — an agent reads this unaided

outside the repository
├── the retrieval corpus          4  fetched when relevant, never pasted in
└── measurement                   5  reads the repo, reports to a person

The last two sit outside the tree deliberately. The repository holds a pointer to the corpus and never its contents, and a measurement layer is not something you install into the project it measures.

This is not about code

Everything above is set in a repository because that is where it was built, and a repository is the easiest place to show it. None of it depends on one.

A writer has a folder. A researcher has a project directory. A designer has a references folder and a file of decisions nobody wrote down. What none of them has is version control — which changes packaging and history, and changes nothing about whether a document placed beside the work gets read.

All four layers survive the move intact. Two things change, and they are the two that matter:

	What cannot be discovered	Where the work stops
Code	Commercial facts, constraints somebody decided once, conventions nothing in the code disagrees with	What may run unattended, and what needs a diff shown first
Writing	Voice, audience, what has already been covered, what this publication never says, and the commercial reason behind each	Drafts, never publishes. A human sends
Research	The real question behind the stated one, what counts as evidence here, and the dead ends already walked	Gathers and summarises; flags uncertainty rather than resolving it. A human concludes
Design	Brand constraints, the accessibility floor, which decisions are settled, and what was rejected and why	Proposes; a human ships

The research row is the one to look at hardest. A cold session re-walks dead ends by definition — it was never told they were dead. Every research project carries that record in somebody’s head and nowhere else, and it is the single most expensive thing to rediscover. That is the handover problem at its purest, and it has nothing to do with software.

The design row has the same shape one step along: an agent that does not know what was rejected will propose it again, in good faith, every session, and the cost lands on whoever has to recognise it each time.

What genuinely changes without a repository is smaller than people expect, and it is worth being exact about the one real loss. Git records when a file last changed; a folder does not. So the confirmation date on a rootnote — the thing that makes staleness visible — has to be written by hand rather than derived. That is the whole difference, and it is a habit rather than an obstacle.

A fifth layer, and why it is separate

The four above are behavioural: they change what an agent does. There is a fifth that is different in kind — measurement. Does any of this actually hold? Are the documents current? Was the rollback ever run? Is the standard being followed or merely present?

It is separate for a reason worth stating plainly. The behavioural layers are most of the value, and they require no tooling at all. A reader who adopts the rootnotes and installs nothing gets most of what is on offer here. Measurement tells you whether a system is holding; it does not create one.

It also carries a specific hazard, and anyone building it should know this before they start: a tool that measures your system can be confidently wrong, and its interface will not say so. A scanner’s own source necessarily contains every token it searches for, so a document about a convention reads as a document following it. That failure is invisible to a test written by whoever wrote the check, because both share an assumption.

The instinct when a scanner disagrees with you is to trust the scanner. That instinct is frequently wrong, and a half-built measurement layer with an authoritative interface is worse than none.

And this is the layer that does not obviously generalise. The four behavioural layers move to writing, research and design unchanged. Measurement does not: you can scan a repository for a lockfile, and it is genuinely unclear what you scan a body of writing for. Something is probably there — whether a publication’s own editorial rules are being followed is a checkable question — but nobody here has built it, and a scoring rubric for prose is precisely the kind of confidently-wrong instrument this section is warning about. Stated as open rather than answered.

What we can and cannot claim for this

We use this. The documents on this site are the artefacts it produces, which is the strongest evidence available for it and is still weaker than a controlled comparison — there isn’t one, and we are not going to pretend otherwise.

One observation is worth reporting precisely because it is small and specific. A convention was placed in a documentation standard in one project. Seven hours later, an agent in a different project — different repository, different task, nobody asking — had adopted it. That is one data point, and it is offered as one: not proof that structure changes behaviour, but the reason we think it is worth your time to find out.

Where to start

Not with all of it.

Write one decision record, today, for something you decided this week. It is short, it is the highest-value form, and it is the one nobody regrets.

Then one rootnote, for whichever thing you have most often explained twice.

The rest follows from noticing how often you stop repeating yourself.