Harness Engineering: The Part of the Agent You Own
You do not train the model. You do not control its next release. You do control everything around it: what it reads, what it may touch, how its work is checked, and what it learns from your reviewers. That is the harness. Here is what it is, how to build one, and how to put it into your delivery process with Claude, OpenAI or open-weight models.
Two teams use the same model. One team ships agent-written code to production every day. The other team turns the agent off after a month because it "makes things up". The model is not the difference. The difference is the system around the model. This year, that system got a name: the harness.
A new name for an old job
We went through three names in three years. First it was prompt engineering: find the right words. Then context engineering: put the right information in the window. Now it is harness engineering: design the whole environment the agent works in, and make the environment catch the mistakes.
The term took hold in February 2026, when OpenAI published how a small team built a product with Codex and wrote zero lines of code by hand. Their summary of the new job was short: humans steer, agents execute. Birgitta Böckeler then gave the idea a clean frame on Martin Fowler's site. LangChain and HumanLayer published the same equation from two directions:
coding agent = model + harness
If you lead engineers, this equation matters for one reason. You cannot change the model. You can change the harness on Monday morning, and you can version it, test it and review it like any other code.
Select a part to see what it does, the failure it stops, and where it lives in a real harness.
The evidence that the harness matters
The strongest public reports this year agree on one point. Teams got their biggest gains from the environment, not from a better model.
Look at what each team changed. OpenAI replaced a large instruction file with a short AGENTS.md of about 100 lines that works as a map, and moved the real knowledge into a versioned docs/ folder. They added custom linters whose error messages tell the agent how to fix the problem. They gave the agent local logs, metrics and traces so it could check its own work. Their rule: if the agent cannot see it, it does not exist.
Anthropic described a harness for agents that work across many context windows. An initializer agent writes a feature list with more than 200 items, each one marked as failing. A coding agent then takes one feature per session, tests it end to end in a browser, commits, and writes a progress file for the next session. The two failures it was designed to stop: the agent declares the job done too early, and the agent leaves the codebase in a state the next session cannot understand.
LangChain added three pieces of middleware: a checklist the agent must pass before it may finish, a loop detector that warns after repeated edits to one file, and a step that loads local context at the start. The model did not change. The score went up by 13.7 points.
Guides and sensors
Böckeler's frame is the most useful one I have found for designing a harness. Every control is either a guide or a sensor.
- Guides act before the agent acts. They are feedforward: instructions, maps, examples, skills, the plan.
- Sensors act after the agent acts. They are feedback: test results, linter output, type checks, review comments.
Each one can be computational (a program decides) or inferential (a model or a person decides). Computational controls are cheap, fast and give the same answer every time. Inferential controls catch what programs cannot, but they cost more and they can be wrong. A good harness uses computational controls wherever it can and keeps inferential ones for judgment.
Select a cell to see examples and when to use it.
(a program decides)
(a model or person decides)
(before)
(after)
Böckeler also sorts harness work by what it protects. A maintainability harness keeps the code clean: linters, formatters, size limits. An architecture fitness harness keeps the structure right: dependency rules, layer checks. A behaviour harness keeps the product correct: tests and end-to-end checks. Most teams start with behaviour, because a failing test is the clearest signal an agent can get.
The failures every harness must stop
When you read agent traces long enough, the same failures repeat. Each one has a mechanical fix. This is the core of the craft.
The last control is the one most teams miss. Every send-back from a human reviewer is a free lesson. If it lives only in a pull request comment, the agent never sees it again. If the harness stores it and feeds it forward, the agent improves from your reviews without any model training.
How to build one
You do not need a framework to start. A working harness has seven parts. Build them in this order, because each one depends on the one before it.
- The loop. Send the conversation and the tool list to the model. Run the tool calls it returns. Add the results to the conversation. Repeat.
- Tools. Read, write, edit, list, search, run a command, and finish. Keep the set small. Return errors as tool results so the model can read them and change approach.
- Policy. Resolve every path inside the workspace. Block writes to
.gitand secrets. Run commands without a shell, from an allowlist. - Guides. Build the system prompt from a short contract, your
AGENTS.md, recent progress and past review lessons. - Sensors and the gate. When the agent calls finish, run your tests and linters. If a required check fails, send the failure back and continue the loop.
- Memory and traces. Write a progress line per run, a record of every review decision, and a full trace of every model call and tool call.
- Budgets. Stop at a maximum number of steps, input tokens and seconds. A harness without budgets is a bill without a limit.
The loop itself is small. This is the core of the open-source harness I built, with the details removed:
while True:
check_budgets() # steps, tokens, wall clock
reply = model.complete(system, messages, tools)
messages.append(reply.message)
if not reply.message.tool_calls:
messages.append(nudge("use tools, or call finish"))
continue
results, finished = run_tools(reply.message.tool_calls) # policy applies here
if finished:
checks = run_sensors() # tests, lint, types
if gate_passed(checks):
return "verified"
if retries_used_up():
return "finished_unverified"
results = replace_finish_with(failure_report(checks))
messages.append(tool_results(results))
Everything interesting happens in the lines marked with comments. The gate is three lines, and it removes the most common failure. Try it below. Turn the gate off and watch what reaches your reviewer.
Press Step to advance one event, or Play to run it. Change the gate setting and run it again.
Pick the model, keep the harness
A good harness does not care which model sits inside it. Two wire formats cover almost every model you can use today. The Anthropic Messages API serves Claude. The OpenAI Chat Completions format with tool calls serves OpenAI models, and also most open-weight servers: Ollama, vLLM, LM Studio and gateways like OpenRouter all speak it. Ollama serves it at http://localhost:11434/v1 on your own machine.
So the harness needs two small adapters, and everything else stays the same: the same tools, the same policy, the same checks, the same review loop. That is the real portability. You can run a cheap local model for small tasks, a frontier model for hard ones, and compare them on the same gate.
Select a model family to see the config change and the trade-offs. The rest of the harness does not change.
A note on open-weight models. They need a server with tool calling turned on, and a model trained to use tools. Smaller models stall more often and give up earlier. The harness helps more here, not less: give them a higher step budget, very specific checks, and a short map. The gate is what makes a smaller model safe to try, because a wrong answer cannot pass it.
Put it into your development lifecycle
A harness is not a tool one engineer runs on a laptop. It is a part of how the team delivers. Each stage of the lifecycle has a harness piece, an owner and a signal you can measure.
Select a stage.
In practice, teams run three workflows on the same harness.
- The inner loop. An engineer runs the harness locally on a small task, reviews the diff, and accepts it or sends it back with a reason. This is where the team learns what the agent can do.
- The issue loop. A maintainer labels an issue. CI runs the harness on the issue text in a container. If the run is verified, CI opens a pull request. A human still reviews and merges. Only maintainers can add the label, because issue text is untrusted input.
- The gardening loop. A scheduled job asks the agent to fix lint debt, update stale docs, or remove dead code. OpenAI calls this garbage collection. It keeps the codebase clean enough for the agent to keep working in it.
The metric I would track first is the send-back rate: of the runs a human reviewed, how many went back. It tells you if the harness is improving, and the reasons tell you what to fix next. A falling send-back rate with a stable test suite is the clearest sign that the investment works.
harnesskit: an open harness you can run today
To make this concrete, I built harnesskit, an open-source harness under the Apache 2.0 license. The code goes public on GitHub shortly. It is about 1,400 lines of Python with one dependency, small enough to read in one sitting. It has every part in this essay: the loop, the tools, the policy, guides, sensors with a verification gate, a loop detector, budgets, progress and send-back memory, and full traces. It works with Claude, OpenAI models, and open-weight models through Ollama, vLLM, LM Studio or OpenRouter.
# install from the repository once the code is public, then: cd your-repo harness init --provider ollama # or anthropic, openai, vllm, lmstudio, openrouter harness verify # run your checks without the agent first harness run "add a test for parse_date and make it pass" harness review # accept, or send back with a reason harness report # runs, reviews, send-back rate
harness run returns success only when the run is verified, so CI can trust the exit code. The repository includes a GitHub Action, an example workflow for the issue loop, a Dockerfile, ready configs for each model family, and a demo with a scripted model so you can watch the gate work with no API key. The adapters are tested against the wire formats with a mocked network. If a live endpoint behaves differently, open an issue.
One honest warning. The policy layer stops honest mistakes. It is not a security sandbox. When the stakes are real, run the agent in a container or a throwaway machine, and give it only the secrets the task needs.
What this means if you lead engineers
The leverage in your team is moving. It used to sit with the engineer who wrote the most code. It now also sits with the engineer who designs the environment where code gets written: the checks, the maps, the boundaries, the review loop. That work looks like platform work, and it should be owned like platform work: versioned, reviewed, measured and staffed.
The good news is that this is a skill your senior engineers already have. They have built CI pipelines, linters, test suites and runbooks for years. A harness is the same discipline, pointed at a new kind of contributor.
The model will keep getting better without your help. The harness will not. It is the part of the agent you own, and the part that decides whether the agent is a demo or a teammate.
Sources
- Ryan Lopopolo, OpenAI, Harness engineering: leveraging Codex in an agent-first world, Feb 2026.
- Justin Young, Anthropic, Effective harnesses for long-running agents, Nov 2025.
- Birgitta Böckeler, Harness engineering for coding agent users, martinfowler.com, Apr 2026.
- LangChain, Improving Deep Agents with harness engineering, Feb 2026, and Vivek Trivedy, The anatomy of an agent harness, Mar 2026.
- HumanLayer, Skill issue: harness engineering for coding agents, Mar 2026.
- Galster et al., a study of agent configuration across 2,853 GitHub repositories, arXiv 2602.14690, 2026.
- Linux Foundation, the Agentic AI Foundation, Dec 2025: AGENTS.md, MCP and goose under neutral governance. The AGENTS.md convention.
- Ollama, OpenAI compatibility.
Haseeb Afsar