A chat is not a contract.
Words hold nothing in place. Files do.

What happens when you rely on chat alone

INTRO · 2026

The scene is familiar. You type an instruction into the chat: “Fix this button’s position.” A moment later the machine replies, “The change is complete.” You open the screen. The button has not moved. Challenge it and the machine apologizes, says “Done” again, and the button stays put again. Instructions are ignored, reports become lies, and your evening disappears.

The root of this cycle is structural, not a machine’s personality. Instructions given in chat evaporate when that conversation ends. The machine in the next session knows nothing of yesterday’s promises. Even “Always check before saying it’s done” is a disposable pledge valid only inside that conversation. Because the promise is not carried forward, the violations recur. With no device enforcing inspection, the machine declares completion without checking.

The solution points in one direction. Put instructions in files, not chat. Turn inspections into scripts, not requests. Judge passage by a numerical execution result—an exit code—not the machine’s words. Install those three things permanently in the repository. That is the entirety of the harness engineering covered in this manual.

There is evidence that this is an industry conclusion, not a hobbyist’s obsession with tidiness. On one coding benchmark, a team left the model completely unchanged and altered only its surrounding apparatus. The score rose from 52.8 to 66.5, and the ranking from 30th to fifth. Same brain, different harness. The harness, not the model, determined the improvement.

Nine workshops

FIELD NOTES · 2026

I compared the file structures and execution methods of harnesses used in roughly nine workshops run by one person: a payment service spanning three repositories, a household ledger, a matching service, a game, an image workshop, an online shop, several internal operating tools, and this site.

The scale varies enormously. The largest workshop has ten worker—agent—definitions, twenty-six procedure documents—skills—and eighty-one validation scripts, fifty-seven of them sensors. The smallest has just one hook. Another explicitly documents “zero workers” as a decision, not an oversight. A larger harness is not necessarily better; a harness matched to the workshop’s risks is.

Even at different scales, the parts repeat. A procedure requiring measurement before declaring completion appears in almost every workshop. Sets of hooks preserving session memory are replicated in nearly identical form. Script headers record which workshop they came from. Standard parts already exist. This manual explains how to assemble them.

How to read it

MAP · 2026

Read in order. Part 01 is a glossary, starting with the names: harness, agent and skill. Part 02 shows how to build them by hand, setting up a minimal harness with five files. Part 03 has Claude perform the same work. Part 04 covers this manual’s core: sensors and gates that structurally block false completion reports. Part 05 addresses model assignment and why the highest-end model should not be used for every job.

There is only one prerequisite. You need not know much code. If you can create a folder and write in a text file, you can begin. Most harness parts are documents, not code: documents defining rules, roles and procedures. Where code is needed, have the machine write it using the method in Part 03.

One sentence before we begin: this manual’s aim is not to trust the machine. It is to make work run without trust. Trust is a virtue between people; what a machine needs is evidence.