Harness Engineering in Three Levels

Everything in Research, Plan, Implement quietly assumes a foundation: that when a fresh window opens, the agent already knows your conventions, your build commands, your architectural red lines — without anyone typing them in. Strip that assumption away and every research phase starts by rediscovering what the last one already found, and every implementation reinvents your standards from statistical averages of other people's codebases. The foundation has a name: the harness. Where context engineering decides what an agent should know, harness engineering builds the permanent machinery that delivers that knowledge — every session, automatically, whether or not anyone remembered to set it up.

The metaphor is older than the discipline: tack for a horse. The animal supplies all the power and none of the direction; the reins, saddle and fences are what turn strength into useful travel. The model is the horse. The harness is everything you build around it so that raw capability arrives pointed the right way.

A definition worth engraving

The sharpest definition of the practice comes from Mitchell Hashimoto — co-founder of HashiCorp, creator of Terraform — writing about his own AI adoption journey in February 2026. He describes it as the idea that “anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again.”

Sit with how demanding that sentence is. It reframes every agent failure as a harness bug. The agent used the wrong logging library: not an annoyance to correct in chat, but a missing constraint to encode. The agent ran the tests wrong: a missing documented command. Correcting the output fixes one session; engineering the fix into the harness repairs every future session at once. The compounding difference between teams that get steadily better results from agents and teams that stay stuck is almost entirely whether corrections die in the conversation or accumulate in the harness.

The vocabulary itself has looser origins — Dex Horthy, in the talk that first attached the label to the practice — a label he offered with his own caveat about it being a hype-y word — described harness engineering as the part of context engineering concerned with a tool's integration points: how you customise your codebase for whichever agent you run — Codex, Claude, Cursor (his talk is worth the hour). And if you want evidence that the layer matters independently of the model, LangChain supplied the cleanest experiment I know of: reworking only the scaffolding around a fixed model took their coding agent from 52.8 to 66.5 on Terminal Bench 2.0 — Top 30 to Top 5 — as they put it in their write-up, “We only tweaked the harness and kept the model fixed.”

When I teach this discipline, I split it into three levels, in ascending order of ambition. The levels are my framing; the practices inside them are the field's.

Level one - tool configuration

Every agentic coding tool exposes a configuration surface: a file it reads at startup, settings that shape its behaviour, registries of what it may touch. Claude Code reads a CLAUDE.md; Codex-style tools read an AGENTS.md; Cursor has its rules files. The filenames differ; the engineering act is identical — take the standards, constraints and commands that live in your head and encode them where the tool ingests them automatically.

The first version of this file writes itself: build command, test command, the three conventions you correct most often. The craft is in what happens next, because level one has a characteristic failure — the config file that grows a paragraph with every incident until it is two thousand lines the agent can barely attend to (part 6 explained exactly why length backfires). A configuration file is a budget, not a scrapbook. Mine hold the invariants: how to build, how to test, what must never happen, where to look for more. Everything else earns its place or gets evicted.

Level one is table stakes in the same way part 2 argued prompt craft is: necessary, quickly commoditised, and nowhere near sufficient. A tool configured this way knows how to behave. It still knows nothing about your system.

Level two - codebase onboarding

An agent meeting your repository is a new hire on day one, minus the luxury of asking the person at the next desk. Level two is onboarding infrastructure: structured context placed where the work happens, so the agent absorbs local knowledge exactly when it becomes relevant.

The root file carries the whole-system view — architecture in a paragraph, the stack, the load-bearing decisions. Directory-level files carry what is true only locally:

repo/
  CLAUDE.md            # the system: architecture, stack, commands
  src/
    api/
      CLAUDE.md        # endpoint conventions, auth, error contract
    billing/
      CLAUDE.md        # invariants, rounding rules, test fixtures
    frontend/
      CLAUDE.md        # component patterns, state, routing

An agent working in src/billing receives the root context plus the billing context and nothing about routing. This is progressive disclosure — the same instinct as the select pillar, implemented as directory structure — and it is what keeps onboarding compatible with the smart zone: relevant knowledge arrives layered by location instead of as one indiscriminate flood.

The discipline that decides whether level two ages well is choosing what these files describe. Constraints and conventions change slowly; implementations change with every commit. A context file that says “billing amounts are rounded once, at line level — see TaxCalculator” will still be true next quarter. One that narrates how TaxCalculator works internally is stale documentation waiting to happen — and part 6 already established what stale documentation does to a session. Write down the decisions the code cannot speak for itself; let the code speak for everything else.

Level three - workflow automation

The first two levels are static — words the agent reads and, mostly, honours. Level three stops relying on the honour system and makes the harness active.

Hooks are the archetype: scripts that fire on agent events, deterministically. A formatter that runs after every file edit. A linter whose failure actually blocks the step. A check that stops any commit touching a schema without a migration. The qualitative shift is from instruction to enforcement — a documented rule is a request, a hook is a fact, and the agent cannot drift past a fact. Whenever I find myself writing “always” or “never” into a context file, I ask whether a hook could make the sentence unnecessary.

The other automation surfaces extend reach rather than enforce rules. Connector servers give the agent live access to systems it would otherwise hallucinate about — the issue tracker, the database schema, internal APIs — replacing guessed context with fetched context. Skills package recurring procedures (“how we write a migration”, “how we cut a release”) as on-demand instruction modules, versioned in the repository like any other artefact. Custom tools wrap domain operations the built-in toolset cannot express. The statusline exercise I published earlier this year lives here too, at the humble end — proof that level three starts with an evening of scripting, not a platform team.

Three levels, one property

What the levels share is the property that makes harness work worth an engineer's time: persistence. Prompts evaporate with the session. Per-task context artefacts — research documents, plans, compaction files — live as long as the task. The harness alone compounds, because Hashimoto's loop deposits every lesson somewhere permanent. It deserves to be treated like the code it lives beside: versioned, reviewed, tested by watching what agents actually do with it, and updated in the same pull request as the change that invalidated it. For a longer treatment than mine, Birgitta Böckeler's pieces on martinfowler.com — her harness-engineering memo and the fuller article — are the best sustained writing on the discipline I have found.

The open question the three levels leave behind is one of judgement, not machinery: of all the things you could encode, what belongs in the harness — and what should you deliberately leave out? The field's clearest answer fits in three words. Next, constraints, not implementations.