Agent Harness Engineering: The Model Is Only Half the System

We spent two years arguing about models. Which one writes the cleanest React, which one hallucinates less, which benchmark just got cracked. The conversation is not wrong, but it is incomplete. The model is one input into a running agent system. The rest is the harness: the prompts, tools, context policies, hooks, subagents, feedback loops, and recovery paths wrapped around the model so it can actually ship something.

A decent model with a great harness beats a great model with a bad harness, and the gap is closing from the harness side faster than from the model side. Viv Trivedy, who coined the term harness engineering, moved a coding agent from Top 30 to Top 5 on Terminal Bench 2.0 by changing only the harness, not the model. Same weights, different scaffolding, completely different results.

What a Harness Actually Is

Viv's one-liner does most of the work: Agent = Model + Harness. If you are not the model, you are the harness.

Concretely, a harness includes six categories of stuff:

• Prompts and rules: system prompts, CLAUDE.md, AGENTS.md, skill files, subagent prompts. Every word that lands in context before the model takes a turn.
• Tools and execution: shell access, file operations, MCP servers, code execution. The set of actions the model can take.
• Infrastructure: filesystem, sandbox, browser, network. Where the agent runs and what it can reach.
• Orchestration: subagent spawning, context handoffs, model routing. How work gets split and coordinated.
• Hooks and middleware: compaction, lint checks, typecheck back-pressure, pre-commit guards. Deterministic enforcement wrapped around the model's actions.
• Observability: logs, traces, cost and latency metering. Signals to tell you your agent is doing something dumb before the user does.

Claude Code, Cursor, Codex, Aider, Cline, Hermes -- these are all harnesses. The model underneath is sometimes the same, but the behaviour you experience is dominated by what the harness does. Claude Opus 4.6 running inside Claude Code scores differently from the exact same model in a custom harness, because each harness makes different choices about context injection, tool access, and feedback.

The Skill Issue Reframe

There is a pattern I watch engineers fall into repeatedly. The agent does something dumb, the engineer blames the model, and the fix gets filed under "wait for the next version."

Harness engineering rejects that default. The failure is usually legible. The agent did not know about a convention, so you add it to AGENTS.md. The agent ran a destructive command, so you add a hook that blocks it. The agent got lost in a 40-step task, so you split it into a planner and an executor. The agent kept finishing broken code, so you wire a typecheck back-pressure signal into the loop.

HumanLayer frames this as: it is not a model problem. It is a configuration problem. Harness engineering is what happens when you take that seriously.

The data backs this up. On Terminal Bench 2.0, Claude Opus 4.6 inside Claude Code scores far lower than the same model inside a custom harness optimized for the codebase. Viv's team proved this directly: changing only the harness moved them from Top 30 to Top 5. Models get post-training coupled to the harness they were trained against. Moving them into a different harness, with better tool descriptions, tighter prompts, and sharper back-pressure can unlock capability that the original harness left on the floor.

This is the opposite of the "just wait for GPT-6" narrative. The gap between what today's models can do and what you see them doing is largely a harness gap.

The Ratchet: Every Mistake Becomes a Rule

The most important habit in harness engineering is treating agent mistakes as permanent signals. Not one-off stories to laugh about, not bad runs to retry. Signals.

If the agent ships a PR with a commented-out test, that is an input. The next version of AGENTS.md says "never comment out tests; delete them or fix them." The next version of your pre-commit hook greps for .skip and xit in the diff. The next version of your reviewer subagent flags commented-out tests as a blocker.

You only add constraints when you have seen a real failure. You only remove them when a capable model has made them redundant. Every line in a good AGENTS.md should be traceable back to a specific thing that went wrong.

This is why harness engineering is a discipline rather than a framework. The right harness for your codebase is shaped by your failure history. You cannot download it.

Patterns Worth Stealing

Let the model orchestrate its own actions. A common assumption is that every tool result should flow back through the context window. But processing massive tool outputs as tokens is wasteful when the model only needs a slice. Giving the model a code execution tool lets it write scripts to filter, pipe, and transform results without paying token cost for irrelevant data. On BrowseComp, giving Opus 4.6 the ability to filter its own tool outputs lifted accuracy from 45.3% to 61.6%.

Strip what you can stop doing. Every component in a harness encodes an assumption about what the model cannot do on its own. As models improve, those assumptions go stale. Claude Sonnet 4.5 exhibited context anxiety, wrapping up work prematurely as it approached its context limit. Anthropic added context resets to compensate. Opus 4.5 eliminated that behaviour entirely, making the resets dead weight. The question to ask repeatedly is not "what should I add?" but "what can I stop doing?"

Separate generation from evaluation. When asked to evaluate their own work, agents reliably skew positive. The problem is particularly pronounced for subjective tasks like design, but even on verifiable tasks, self-evaluation produces lenient assessments. Anthropic's generator-evaluator pattern, inspired by GANs, uses a separate evaluator agent that is tuned to be skeptical. On frontend design tasks, this produced creative leaps a single-pass generator never achieved: one iteration scrapped a clean dark-themed museum landing page and rebuilt it as a 3D room with CSS-perspective gallery navigation.

Negotiate sprint contracts. Before any code gets written, the generator and evaluator agree on what done looks like. The generator proposes what it will build and how success will be verified. The evaluator reviews that proposal. They iterate until they agree, then the generator builds against the contract. This catches scope drift before it costs tokens.

Hooks as enforcement, not suggestions. A hook runs at a specific lifecycle point and either passes silently or injects failure text into the agent loop. Typecheck after every edit. Block destructive bash commands. Auto-format on write. The principle from HumanLayer that sticks: success is silent, failures are verbose. When typecheck passes, the agent hears nothing. When it fails, error text enters the loop and the agent self-corrects.

Skills with progressive disclosure. Loading every tool and instruction into context at startup degrades performance before the agent takes a single action. Skills let the harness reveal context only when the task calls for it. The YAML frontmatter provides a short description in the context window; the full skill is loaded on demand when the model reads it.

Keep AGENTS.md short and earned. The flat markdown file at the root of your repo is still the single highest-leverage configuration point because it lands in the context every turn. Keep it under 60 lines. Every line competes for attention. Rules should trace to a specific past failure or a hard external constraint. Ratchet, do not brainstorm.

Where Teams Mess It Up

Building the harness before seeing the failures. The right harness is shaped by your actual failure history. Adding safety rails before you know what goes wrong creates noise, not signal. Start with a bare agent loop and tighten it as you watch it break.

Over-engineering the orchestration. Not every workflow needs a planner, generator, and evaluator. A single agent with good context engineering and a few hooks handles most tasks. Add subagents when you hit a specific ceiling you can name.

Treating the harness as a one-time config. A harness is a living system. The model improves, and scaffolding that was essential six months ago becomes dead weight. Anthropic explicitly removed context resets from Opus harnesses because the behaviour that motivated them disappeared. If you are not periodically removing harness components, you are running with a system designed for a weaker model.

Ignoring tool surface area in the prompt. Every tool's name, description, and schema gets stamped into the prompt on every request. Ten focused tools outperform fifty overlapping ones because the model can hold the menu in its head. A sloppy MCP server can prompt-inject your agent through its own tool descriptions.

The Model-Harness Feedback Loop

Something subtle is happening under the surface. Today's agent products are post-trained with their harnesses in the loop. The model gets specifically better at actions the harness designers emphasised: filesystem operations, bash, planning, subagent dispatch. That is why Opus 4.6 feels different inside Claude Code than inside someone else's harness. Co-training creates overfitting between the model and its default scaffold.

The practical implication: the best harness for your task is not necessarily the one the model was trained inside. Viv's Top 30 to Top 5 jump is the cleanest proof. And as the industry moves from LLM APIs to harness APIs (the Claude Agent SDK, Codex SDK, OpenAI Agents SDK, Hermes), you are no longer building agent infrastructure from scratch. You are tuning a configuration surface that is already well-factored, which makes the skill-issue reframe tractable for the first time.

The Ceiling Moves, It Does Not Disappear

A naive take is that better models make harnesses obsolete. If the model can plan, no planner. If the model is coherent at long horizons, no context resets. And yes, Opus 4.6 largely killed context anxiety, which means a class of scaffolding from six months ago is now dead code.

But the ceiling moved with the model. Tasks that were unreachable are now in play, and they bring their own failure modes. The anxiety scaffolding goes away, and in its place you need multi-day memory policies, three-agent orchestrators, or evaluators for design quality. The assumptions shift, and so does the scaffolding that encodes them.

Harnesses do not shrink. They move.