Chapter 7 — Harness Engineering I: Guides and Sensors

"Agent = Model + Harness." — Böckeler, Harness engineering for coding agent users [D]

Context Files: present in 90.6% of repositories. Hooks: 0.9%–3.2%. — Galster et al., n = 2,853 [A]

Those two lines are the chapter. One is the framework; the other is what the framework got used for.

7.1 The two harnesses

Chapter 1 fixed the vocabulary; this chapter puts it to work. The founding equation is Böckeler's, and it is worth restating because of what it excludes:

Agent = Model + Harness. The harness is everything that is not the weights.

That framing does real work. It says the interesting engineering object is not the model — you did not train it and you cannot change it — but the entire apparatus around it. Chapter 2 measured how much that apparatus is worth: the same weights, a different interface, 1.31% to 12.47%.

Böckeler splits the apparatus into two rings, and the split is the practical crux.

Note the asymmetry the diagram implies, because it becomes an argument later. The model changes without your consent — a new checkpoint arrives and behaviour shifts. The builder harness changes without your consent — a vendor revises a system prompt, adds a tool, alters retrieval. The user harness is the only ring whose behaviour you can hold still. Anything you need to be stable belongs there.

7.2 The quadrant

Böckeler's central contribution, and this book adopts it wholesale with credit. Two axes.

When does the control act? Before generation, shaping what happens — a guide, feedforward. Or after, detecting what happened and enabling correction — a sensor, feedback.

What executes it? A CPU running deterministic code — computational. Or a model producing a probabilistic judgment — inferential.

Two clarifications before the argument, because both matter.

A mechanism is a vehicle; a cell is a function. A hook is a vehicle — a script that runs at a lifecycle point. It can carry a sensor (run the type checker after every edit) or a guide (inject the current schema before every call). MCP can expose a computational guide (a code graph to query) or reach a sensor (a coverage service). The mapping from tool features to cells is therefore not one-to-one, and I will be careful about that in §7.6 where it matters most.

Inferential does not mean inferior. Computational controls are cheap, fast, and reliable but can only check properties expressible in code. "Is this the right abstraction?" and "does this test actually test anything?" are semantic questions, and Chapter 8's hardest problem lives there. The two columns are complements, not competitors, and Böckeler's point is precisely that inferential controls "allow us to both provide rich guidance, and add additional semantic judgment."

7.3 Guides assert. Sensors observe.

Here is the distinction that the rest of the chapter turns on, and it is epistemic rather than technical.

A guide is an assertion. It says: this is how things should be done here. It is a claim, written in advance, about behaviour that has not happened yet. Its truth is never tested by the act of writing it.

A sensor is an observation. It says: this is what did happen. It makes contact with the artefact and returns a verdict about the actual state of the world.

The asymmetry between these is the whole game. An assertion can be wrong, stale, contradicted by a neighbouring assertion, or simply ignored, and none of those failures announces itself. An observation can also be wrong — a flaky test, a false-positive lint — but its failures are loud, because a sensor that fires produces an artefact someone must dispose of.

Now consider a harness composed almost entirely of guides. It is a system of assertions about the organisation's own behaviour with almost no observation of that behaviour. It will feel well-governed. It will read well in an onboarding document. And it will contain no mechanism by which a false assertion is ever discovered.

There is a name for a body of confident claims insulated from contact with evidence, and it is not engineering. Taleb's long argument against narrative — that a coherent story is not a substitute for a record of outcomes, and that coherence is easier to manufacture than accuracy — applies directly. A guide is a map. A sensor is contact with the territory. You can improve a map indefinitely without ever touching the ground.

This gives the ordering that Chapter 5 arrived at from a different direction. Chapter 5's gate audit asked: if producing the artefact became free, would this gate still carry information? Every gate that survived was computational; every gate that failed was social. The reason is now visible in the quadrant. Social gates inferred an unobservable from an observable that used to correlate with it. Computational sensors observe the property directly. They never cared how hard anyone worked, and they do not care whether the author was a person.

So the four cells have an authority ordering, and it is forced:

7.4 Where a sensor sits

Fowler's community teaches keep quality left — distribute controls by cost and speed so cheap ones run often and early. Chapter 5 explained why the principle now bites harder: a regulator slower than its plant does not regulate it.

But "left" is usually read as earlier in the delivery pipeline, and for agents there is a more precise axis: how close is the sensor to the agent's action?

The ordering is not aesthetic. It is Chapter 3's arithmetic. A blocking sensor consumes no review capacity at all — the bad state never exists. An in-loop sensor consumes tokens, which are elastic. An out-of-loop sensor consumes human attention, which is the binding constraint. Moving a sensor from level 3 to level 1 is a direct increase in μ, and it is the cheapest such increase available.

Chapter 2 supplies the measurement. The linting guardrail in SWE-agent was a level-1 blocking sensor: let a modification apply only if it does not produce major errors. It was worth +3.0 points, and it prevented a cascade in which one failed edit dropped the odds of eventual success from 90.5% to 57.2% [A]. The value came not from telling anyone about the bad edit but from the bad edit never landing.

Now the observation I think is genuinely useful, and it is about politics rather than engineering.

Blocking controls were always the most effective and always the least adoptable. Every engineer who has tried to introduce a rejecting pre-commit hook knows the objection: it is obstructive, it fires on false positives, it stops people working, someone will add --no-verify. Those objections were reasonable. A human being blocked by a tool experiences friction, resents it, and escalates.

An agent does not. It has no ego, no deadline anxiety, and no ability to complain to your manager. It reads the rejection, adjusts, and retries — which is precisely what the SWE-agent guardrail measured.

Delegation has made a whole class of control politically available for the first time. The blocking sensors that human teams rejected on grounds of friction are now free of the thing that made them costly.

This is one of the few genuinely good consequences of the transition in this book, and almost nobody is collecting it. Which brings us to the evidence.

7.5 What teams actually built

The best available picture of harness practice comes from Galster and colleagues: 2,853 GitHub repositories using at least one agentic coding tool, filtered from 37,249, snapshot February 2026 [A]. Chapter 6 used its context-file figures; here the whole dataset matters.

They identify eight repository-level configuration mechanisms: Context Files, Settings, Skills, Subagents, Commands, Hooks, Rules, and MCP. Two are supported by all five tools studied; no single tool implements all eight.

Adoption, as a percentage of each tool's repositories:

Context Files are present in 2,586 of 2,853 repositories (90.6%) — 4,768 files in total, CLAUDE.md 1,640, AGENTS.md 1,508, copilot-instructions.md 1,393. Most repositories hold one or two.

The advanced mechanisms are barely used. 601 Skills across 158 repositories (median 2); 450 Subagents across 131 (median 2). And the finding Chapter 6 already quoted, which matters even more here: 514 of 601 Skills (85.5%) bundle no additional resources at all — no scripts/, no references/. The authors' conclusion is unhedged: Skills "function primarily as structured text rather than executable scripts." Also: no repository used the persistent memory feature of Subagents.

The authors' own summary: "Harness engineering in open source today is therefore mostly context engineering."

7.6 The ratio

Now map those mechanisms onto the quadrant, and something appears that neither source states.

Recall the caveat from §7.2: a mechanism is a vehicle. Context Files, Rules, and text-only Skills carry inferential guides — reference documentation, principles, conventions. Hooks execute scripts at agent lifecycle points and are the primary vehicle for putting a computational sensor inside the agent loop, at level 1 or 2 of Figure 7.3. MCP is mixed. Commands package prompts. Settings enable rather than control.

The headline is a ratio. Within Claude Code repositories, 1,223 have Context Files and 42 have Hooks — 29 to 1. Within Copilot repositories, 944 against 9: 105 to 1. Across every tool studied, Hooks are the least-adopted of all eight mechanisms, and Context Files are the most.

Set that against §7.3's authority table and the conclusion is stark:

The field has invested overwhelmingly in assertions and almost not at all in observations — and specifically, it has left nearly empty the one cell whose authority Chapter 5 demonstrated to be the only kind that survives cheap generation.

Three qualifications, because the argument should be stated at its weakest as well as its strongest.

Sensors exist outside these mechanisms. Every one of these repositories almost certainly has tests and CI. The absence of Hooks does not mean the absence of linters; it means the linters are at level 3 of Figure 7.3 — out-of-loop, consuming human attention when they fire — rather than at level 1, blocking, inside the agent's edit cycle. That is a weaker claim than "there are no sensors" and it is the claim I am making. The sensors are there; they are in the wrong place relative to the agent.

The mapping is imprecise. Hooks can implement guides; MCP straddles cells. But the imprecision cannot rescue the picture, because the extremes are three orders of magnitude apart. No reasonable re-assignment of vehicles to cells turns 90.6% against 0.9–3.2% into a balanced portfolio.

Open source is not enterprise. The authors say so explicitly, and enterprise practice may differ. But Chapter 3's enterprise case is the only counter-datum available, and it points the same way: that organisation reached for inferential sensors — automated review bots, ≈38% of review events — under queue pressure, not for computational ones inside the loop.

7.7 Why it happened

The temptation is to read §7.6 as a failure of diligence. It is not, and treating it as one guarantees the wrong remedy. It is a cost gradient, and we have met this shape before.

Chapter 4 asked why an agent duplicates rather than extracts when both are correct, and answered: extraction requires knowing every call site, which is expensive from a bounded view, while duplication is cheap and safe. The gradient points at duplication, and no instruction reverses a gradient.

Run the same analysis one level up, on the humans building harnesses.

Writing a paragraph in CLAUDE.md takes minutes, requires no tooling, breaks nothing, and produces an artefact that looks like progress in a pull request. Wiring a custom check into every edit requires deciding what to check, building it, integrating it, and then living with its false positives forever. Both are "harness work." One costs an afternoon; the other costs a quarter and an owner.

So harnesses drift toward text for exactly the reason codebases drift toward duplication. Individually rational, collectively degrading, nobody's fault, and not fixable by asking people to try harder.

There is a second force, and it is the more insidious one. Chapter 2 established that guides age and sensors persist — a guide compensates for a model deficit, and when the deficit closes the guide becomes overhead. Combine that with Figure 7.5 and the portfolio problem sharpens:

Teams have concentrated their harness investment in the cheapest to build, weakest in authority, and fastest to depreciate asset class.

A test written in 2015 still works. A type system still works. A CLAUDE.md paragraph explaining how to avoid a failure mode that three model generations have since eliminated is not neutral — it occupies the budget Chapter 6 showed to be scarce, and worse, it teaches everyone reading the file that the file's contents are decorative. Taleb's Lindy heuristic gives the portfolio advice in one line: tests and type systems have survived fifty years and will likely survive the next model; context-file conventions are eighteen months old. Weight accordingly.

None of this argues against context files. Chapter 6 defended them: architecture is exactly what an agent cannot infer locally, and a markdown file is the cheapest available attack on the right problem. The argument is about portfolio balance, and the balance is currently 29-to-1 or worse in favour of the asset that depreciates.

7.8 What to build first

The practical output. If §7.6 is right, the highest-value move for most teams is not a better context file — it is the first level-1 blocking sensor.

Chapter 2 tells you which one, because it measured it. The single most valuable control in the SWE-agent ablation was a check that ran on every edit and refused to apply a change that introduced a syntax or compile error. Cost: milliseconds. Value: +3.0 points, and the prevention of a cascade that halved recovery odds.

Generalised into a first move:

Wire your fastest deterministic check into the agent's edit cycle as a blocking control, before you write another guide. Syntax, then types, then the fast unit tests. In that order, because that is the order of speed.

Then a minimal harness that populates all four cells rather than one. Appendix B works this out in full; the shape is:

Four rules for maintaining it, all consequences of earlier chapters rather than taste:

1. Every guide carries a date and the failure it was added for. Chapter 2: guides age. Undated guides cannot be pruned, so they accumulate.
2. Prefer blocking to advisory, advisory to reporting. Figure 7.3. Each step rightward spends more of the constraint.
3. Prefer computational to inferential when the property is expressible. Chapter 1's rule: a linter that catches a defect every time beats a review agent that catches it four times in five — categorically, because you can build a policy on the first and only a hope on the second.
4. Every new control is a hypothesis. Chapter 2's iterative search scored below having no search at all. Controls can be iatrogenic. Chapter 14 makes this measurable; until then, at minimum, know when each control was added and what it was supposed to prevent.

7.9 What this pillar cannot do

As in Chapter 6, the honest close is the pillar's ceiling — three of them.

Guides cannot make intent exist. A guide transmits intent that someone articulated. Chapter 0's closing line stands: a harness cannot verify correctness against a requirement never stated. No quantity of guides substitutes for the specification, and Chapter 5 showed that intent can no longer be recovered afterwards by asking.

Sensors cannot check what they cannot express. The computational column is bounded by what is mechanically checkable. Misdiagnosis of the underlying problem, over-engineering, unrequested features, and correctness against an unstated intent are precisely the high-impact failures Böckeler notes that neither column reliably catches. This is Chapter 8's unsolved third of the harness.

A harness has no mechanism for keeping itself coherent. Guides accumulate, contradict each other, and go stale silently; sensors that never fire are indistinguishable from sensors that are blind. Böckeler poses both as open questions, and Chapter 8 takes them up as the steering loop's central problem, with Chapter 21 naming the failure modes — Harness Theatre, the Silent Sensor, Guide Sprawl.

Which is the handoff. This chapter described the components. Chapter 8 is about the loop that maintains them: how a harness grows without becoming incoherent, how to distribute controls across the change lifecycle, why some codebases are structurally easier to govern than others, and why the hardest regulation category — whether the software actually does what was wanted — remains, in the words of the person who named it, the elephant in the room.