The harness

In a factory the model is a dependency you upgrade. The harness is the thing you write. It is the set of version-controlled instruction files every agent reads before it does anything, and because they all read it, one edit changes the behaviour of the whole fleet — which is an unusual amount of reach for a file with no tests.

What the harness actually is#

Four kinds of thing, and it is worth keeping them apart. Entry-point rules that say how work proceeds at all — research before planning, planning before implementation. Standing rules that must hold across every change: security boundaries, the architecture contract, git conventions, what the tests are for. A map of the system, so an agent looking for the code that handles a thing is not exploring twenty services one grep at a time. And named reference implementations — this is what a well-formed one of these looks like here, copy its shape.

What does not belong is anything true of one work item only. That belongs on the item. The test is whether a statement would still be true next month for a different change; if not, it is context and it goes in the hand-off. Harnesses rot when this line is not held, because every incident produces the temptation to add one more sentence.

The map is worth building deliberately rather than leaving to exploration. A machine-readable file naming each service, the paths it owns, its dependencies, the team accountable for it, its build command and its risk class does two jobs at once: it makes the agent’s answer to which services does this touch a lookup instead of a guess, and it cuts how much of the codebase has to be loaded to answer the question. Both of those show up on the bill.

Precedence, or it is just a pile#

A harness with five sources of truth and no stated order is five sources of truth that will eventually disagree, resolved each time by whichever the model happened to weight most. The order has to be written down, and the useful thing about writing it down is that it forces you to notice where the model’s own knowledge sits.

Bottom. It sits at the bottom, consulted only where the repository is silent — and a finding that rests on it says so, in the finding. That is the inversion that makes a harness worth having, because the default for a general-purpose model is the opposite: it starts from everything it has read and treats your repository as one more input. A reviewer that flags a pattern as wrong because it is unusual in open-source code, when the codebase has a written decision saying otherwise, has consulted the rungs in the wrong order.

Width in that figure is authority, and the narrowing is the point. Each rung constrains what the rung below is allowed to decide. A security rule does not argue with a local pattern; it removes the question. Which is also the honest reason the top rung exists at all: it is the set of things you are not willing to have decided per run.

The part that regresses#

Here is the thing that catches teams out. When agent quality drops, the instinct is to look at the model — a new version, a different tier, a provider incident. It is usually the harness. The harness is what changes every week, edited by people, with no build failing when a new rule quietly contradicts an old one. The model changes rarely and loudly.

There is a structural reason for it, and Spotify’s write-up names it from the other direction: in their more fragmented codebases, agent performance is measurably worse. Consistency of the surrounding code is the strongest predictor they report. A harness is an attempt to state, in prose, what a consistent codebase would have shown by example — and the more inconsistent the code, the more the harness has to carry, and the more of it there is to contradict itself.

Which leads to the discipline that turns this from a warning into a practice: a harness change is a code change, so it gets a code change’s treatment. It is reviewed. It is versioned, and the version is recorded against every run so that a bad week can be attributed to something. It is rolled out to a few work items before the whole fleet. And it is replayed against a fixed set of already-solved work before it goes live, because that is the only way to find out whether an edit that reads like an improvement actually is one. A model upgrade goes through the same gate, for the same reason: what you are measuring was never the model alone.

The other failure is slower and harder to reverse. Every time an agent gets something wrong there is pressure to add a sentence, and none of those sentences is unreasonable on its own. After a year the file is long enough that no one has read all of it, two rules in it conflict, and the agents are behaving unpredictably for reasons nobody can locate. The counter-pressure has to be deliberate: something is removed or narrowed when something is added, and a rule that has never changed an outcome is deleted. A harness that only grows is a record of past incidents wearing an instruction set’s clothes. The first place that discipline pays off is the step that decides whether work is buildable at all.