An agent harness is the code you write around a model — not the prompt, the tools, the memory files, and the pass/fail checks that turn a capable LLM into an agent that reliably finishes long tasks. In practice that means four concrete pieces: a persistent spec the agent can't wander from, a way to remember progress across context windows, verification loops that catch mistakes before they compound, and a habit of turning every failure into a permanent fix. This post walks through building each piece, using the patterns OpenAI, Anthropic, and Cursor have published from their own production harnesses.
Why the harness, not the prompt, is where reliability comes from
Cursor's internal benchmarking found the same underlying Claude model scoring 46% on one harness configuration and 80% on another — a 34-point swing from wrapper design alone, with no change to the model. Anthropic's engineering team reached a similar conclusion while building agents meant to run for hours or days: the open problem wasn’t model capability, it was getting an agent to make consistent progress across multiple context windows without losing the plot. For the conceptual case of why this shift happened, see our companion piece on harness engineering as a discipline. This post is the practical follow-up: how to actually build one.
Step 1: Give the agent a persistent spec it can't drift from
The single biggest failure mode in long-running agent work is an agent deciding it's "done" when it isn't, or quietly rewriting the definition of done to match whatever it managed to finish. Anthropic's long-running agent harness fixes this with a two-phase structure: an initializer agent that runs once and produces a feature list — a JSON file with 200+ entries, each one a category, a description, a step-by-step test procedure, and a boolean passes field, all initialized to false. A second coding agent then works through that list session by session, and is instructed with deliberately blunt language — Anthropic's own harness uses the line "it is unacceptable to remove or edit tests" — specifically to stop the agent from editing the spec to make its own work easier.
The generalizable version of this for your own harness: never let the same agent that's doing the work also own the definition of success. Generate the spec once, treat it as close to immutable, and make deviations from it loud.
Step 2: Give the agent memory across context windows
A single agent session runs out of context. A harness has to hand off state to the next session the way a human engineer hands off to the next shift. Anthropic's pattern uses three artifacts, all created at initialization and updated every session:
- An
init.shscript that starts the dev environment identically every time, so the agent never burns a session rediscovering how to run the project - A
progress.txtfile logging what was attempted, what passed, and what's currently broken - Git commits with descriptive messages, used as the ground-truth record of what state the code is actually in
The coding agent's startup sequence is the same every session: check the working directory, read recent git log and the progress file, pick the next incomplete feature, run init.sh, and run the existing test suite before touching anything — so a session never starts by building on top of a broken state it doesn't know about.
Step 3: Build verification loops, not just guardrails
Thoughtworks' framework for harness controls splits them into two directions: guides, which steer the agent before it acts (system prompt rules, style guides, architecture constraints), and sensors, which catch problems after it acts (tests, linters, type checkers, an AI-based reviewer). It further splits sensors by execution type:
| Check type | Examples | Speed | Reliability |
|---|---|---|---|
| Computational | Unit tests, linters, type checkers, compilers | Milliseconds to seconds | Deterministic — high |
| Inferential | An LLM reviewing a diff, browser-driven end-to-end checks | Seconds to minutes | Non-deterministic — richer but needs its own verification |
The practical rule is to run cheap, deterministic checks first and expensive, semantic checks later — the same "shift left" principle from traditional CI, applied to agent output instead of human commits. Anthropic's harness leans on this directly, using a Puppeteer-driven browser as an inferential sensor to confirm a feature actually works end-to-end, not just that the code compiles.
Step 4: Spend reasoning effort where it actually pays off
OpenAI's harness engineering write-up, describing a team that shipped a production application without hand-writing code, found that maxing out reasoning effort at every step of a task was worse than what they called a "reasoning sandwich": high reasoning effort for planning, reduced reasoning effort for the mechanical work of building, then high reasoning effort again for verification. LangChain's own harness testing on Terminal-Bench 2.0 found the same base model improving from 52.8% to 66.5% purely from restructuring how and when reasoning was applied — no model change. If your harness calls the model the same way for every phase of a task, this is one of the cheapest structural changes available.
Step 5: Turn every mistake into a permanent fix
The term "harness engineering" traces back to a February 2026 post by HashiCorp co-founder Mitchell Hashimoto, and the discipline he described is simpler than the architecture above: anytime an agent makes a mistake, you don't just correct the output — you engineer a change to the harness so that specific mistake becomes structurally impossible to repeat. A wrong assumption about a file path becomes a guide in the system prompt. A skipped test becomes a blocking sensor. A repeated hallucinated API becomes an entry in a lint rule. The feature list, the progress file, and the verification loop in this post are what that habit looks like once it accumulates over dozens of fixes — the harness isn't designed up front so much as grown one failure at a time.
A minimal harness checklist
- A spec file the agent can read but is discouraged from silently editing (feature list, ticket, or test suite)
- A startup script that reproduces the working environment identically every run
- A progress log and git history the next session reads before doing anything else
- At least one fast computational check (tests, types, lint) that runs before any inferential one
- An explicit reasoning-effort plan across plan / build / verify phases, instead of one flat setting
- A standing habit of converting every observed mistake into a rule, check, or file the harness carries forward
FAQ
Do I need a multi-agent system to build a harness?
No. Anthropic's long-running harness uses two agent roles (initializer and coding agent), but the core ideas — a persistent spec, a progress log, and verification before continuing — work with a single agent as long as you externalize state into files instead of relying on the model to remember it.
What's the difference between a harness and a system prompt?
The system prompt is one input inside the harness. The harness also includes the tools the agent can call, the files it reads and writes for state, the checks that run on its output, and the permission rules that decide what it's allowed to do without asking. A strong system prompt with no verification loop around it is not a harness.
Should the coding agent be allowed to edit its own feature list or tests?
Anthropic's harness explicitly discourages this with blunt language in the prompt, because an agent under pressure to finish will otherwise mark a hard feature as done by loosening its own test rather than fixing the code. If the spec must change, that should be a separate, deliberate step — not something the same session does mid-task.
Is harness engineering the same thing as context engineering?
They overlap but aren't identical. Context engineering is about curating what goes into a given context window — system prompt, tools, retrieved files, message history. Harness engineering is the larger system around that: the scripts, state files, and checks that persist across context windows and sessions, which is what lets an agent work on a task longer than one window can hold.
What's a "reasoning sandwich" and do all models support it?
It's the pattern of using high reasoning effort for planning and verification but a lower setting for the mechanical building step in between, described in OpenAI's harness engineering write-up. It requires a model with an adjustable reasoning-effort parameter, which is now common on frontier reasoning models but not universal — check your specific model's API options before assuming it's available.
How big should a feature list or spec file be before it's useful?
Anthropic's own example used over 200 discrete, independently testable entries for a long-running build. The right size depends on your project, but the principle is granularity: each entry should be small enough that "passes" or "fails" is unambiguous, not a vague milestone the agent can partially satisfy.
Does a good harness mean I can use a cheaper or smaller model?
Often, yes, within limits. Cursor's benchmark showing a 46%-to-80% swing on the same model from harness changes alone implies the inverse also holds — a well-built harness narrows the gap between a strong model and a weaker one. It doesn't eliminate the gap; verification loops still depend on the model being able to act on the feedback they produce.
Further reading: