Harness Engineering

An agent writes a call to an API that does not exist. It edits the wrong file. It runs for forty minutes, crashes, and starts again from nothing. Every time, the same reflex: the model was not good enough.

It usually was. What the agent could see, act on, remember and recover from was decided long before the model produced a token — by the system wrapped around it. That system is the harness, and most of the time it is the thing that broke.

The discipline now has a name. Mitchell Hashimoto popularised "harness engineering" in February 2026, and the vocabulary has spread quickly, which matters more than it sounds: you cannot file a bug against a layer you have no word for.

The stakes are not theoretical. Practitioners at QCon London in early 2026 cited reports that as many as 80% of firms see no tangible benefit from their AI initiatives. That number is not a verdict on model capability — models got dramatically better across the same period. It is a verdict on everything else.

We spent a chunk of last year writing HarnessArch, a public specification for this system: four pillars, 29 sheets, and four maps you can open and inspect. This piece is the short version of the first pillar.

The model is the engine. The harness is the machine.

A language model does one thing: given a context, produce the next tokens. Everything else an agent appears to do — reading a file, running a test, remembering yesterday, asking permission, trying again — is the harness doing it.

That reframing has a practical consequence. "Was the model good enough?" is nearly unanswerable and leads to swapping models and hoping. "Which layer ran out of road?" is answerable, and the answer points at something you can change.

The eleven primitives

The harness decomposes into eleven layers. Each one prevents a specific class of failure, and each one you skip is a failure mode you have accepted.

The four groups are a reading aid, not part of the spec. What the spec insists on is that all eleven are decisions — including the ones you make by omission.

What it knows

01 Instructions — who the model is, the work it does, the tone, the constraints. Skip it and the model operates without boundaries.

02 Context delivery — the relevant file, the failing test, the stack trace, put in front of the model at the moment it needs them. This is the layer behind most hallucinated APIs. The model did not invent a function because it was stupid; it invented one because nobody showed it the real interface.

03 Context management — protecting the model's attention through retrieval and re-ranking, summaries, compaction, prompt caches. Note that this is a different job from delivery. Delivery gets material in; management decides what earns the room. Teams that conflate the two build a retrieval pipeline and then wonder why quality falls as the context window fills.

This distinction is where "context engineering" as a term has landed more broadly — the practice of deciding what the full context contains, of which retrieval is only one input. A team can run a state-of-the-art RAG pipeline and still ship an agent that fails because it has no memory layer, an overloaded tool set, or bad token-budget hygiene.

What it can do

04 Tool interfaces — name, description, schema. Function calling, MCP, bash, grep. Without them the model can only ever propose; it cannot act.

05 Execution environment — where tool calls become bounded reality: sandboxes, containers, worktrees, filesystem scope, network and secrets. This is the layer that decides whether a mistaken command is an inconvenience or an incident.

How work survives and moves

06 Durable state — the workbench that survives the turn: plan files, checkpoints, branches, logs, memory stores. An agent that loses forty minutes of work to a crash does not have a model problem.

07 Orchestration — how work moves: lifecycle hooks, retries, approval gates, heartbeats, human handoff. Unmanaged retries and missing decision points live here.

08 Sub-agents — bounded loops with a narrower job, narrower context and narrower tools. The point is not parallelism for its own sake. It is that a sub-agent's context stays small because its job is small.

09 Skills and procedures — reusable know-how loaded at the right time: skills, slash commands, playbooks, runbooks. Without this layer every agent rediscovers the same patterns.

How it gets better

10 Verification and observability — the harness asks for receipts: tests, type checks, screenshots, evals. And it records the run. This is the layer most commonly deferred and most expensive to add late, because retrofitting observability means changing every other layer to emit something.

11 Evolution — failures become infrastructure. A missed context becomes a retrieval rule. Skip this and you will fix the same failure repeatedly, by hand, forever.

Finding the layer that failed

The practical output of the model is a diagnostic. Start from the symptom, not the model.

None of these rows say "use a better model." That is the point. Each one names something you can build.

Memory is four things, not one

Two of the eleven primitives — context management and durable state — hide a whole second system behind them. "Give the agent memory" sounds like one feature. It is four, and they fail differently.

Working memory is the desk. The current request, the visible conversation, tool results from this turn. Every token in the prompt is active state, and it runs on a budget. When the session ends, it is gone unless something else caught it.

Episodic memory is the diary. Timestamped events: what happened, and when. Last Friday's check found no approval comment on issue #9. This is what lets an agent resume an investigation rather than restart it. Its limit is strict and worth stating out loud: the past session says what happened last time. It cannot say what is true right now.

Semantic memory is the fact sheet. Timeless claims with no timestamp attached — repository layout, project rules, ID mappings, user preferences. The app root is meteor/league. The failure mode here is subtle and expensive: facts go stale and contradict. Without conflict handling, an old truth sits next to a new one as an equal, and the model has no way to tell which one to trust.

Procedural memory is the runbook. Not knowing that, but knowing how — checklists, skills, tool schemas, orchestration code.

Storing all four buys you nothing on its own. Durable stores are a filing cabinet; none of it matters until the right slice reaches the context window at the right moment. That retrieval, ranking and assembly step is the actual engineering, and it is where most memory implementations quietly stop.

The counterintuitive half is forgetting. A system that remembers everything eventually remembers too much: temporal decay, contradiction handling, compression and manual curation exist so that obsolete information stops outranking current truth. Teams build the write path first and the forget path never, then wonder why quality degrades as the memory store grows.

Not every harness needs every layer

The obvious misreading of an eleven-part model is that a good harness fills all eleven slots. It does not.

The HarnessArch teardowns apply the same grid to two real shipped coding agents. OpenCode answers all eleven primitives inside its core infrastructure — a power plant with many outlets. Mario Zechner's pi deliberately constrains itself to under 1,000 tokens of system prompt and core tooling, and leaves roughly half the slots empty on purpose. It is a hand tool, and it is better for the refusal.

Both are good harnesses. The difference between an empty cell and a gap is whether anyone decided.

Where this leaves you

If you are running agents in production and something is going wrong, the useful next move is not a model upgrade. It is an inventory: for each of the eleven layers, what did we build, what did we deliberately skip, and what have we simply never thought about?

The third column is where the failures live.

The full specification — four pillars, 29 sheets, the memory model, the agentic SDLC and the interactive maps — is public at harnessarch.com. It is free, and there is nothing to sign up for.

• AI
• Agents
• Architecture