Harness Engineering Explained: Prompt vs Context vs Harness
In 2023 everyone learned prompt engineering. In 2025 it was context engineering. In 2026 the word is harness engineering. It is not one more buzzword. It names the part of an agent setup that decides most of the result: everything around the model. This guide explains the three terms in one line each, shows the data that makes the harness matter, and maps each part to the OpenClaw settings that control it.
Bottom Line
- Prompt engineering is what you tell the model.
- Context engineering is what the model can see right now.
- Harness engineering is the system that runs the model: the loop, the tools, the checks, the permissions and the memory.
- The harness changes results as much as the model. The same model scored 58.0% in one harness and 76.4% in another on Terminal-Bench 2.0.
- In OpenClaw, the harness is your workspace and config:
AGENTS.md, skills, hooks, the sandbox, exec approvals and compaction.
The Three Layers in One Table
| Layer | Question it answers | Example |
|---|---|---|
| Prompt | What do I ask? | ”Fix the failing login test.” |
| Context | What can the model see now? | The test file, the error, the repo rules, recent messages |
| Harness | What lets the model do the job? | The loop, tools, tests, linters, sandbox, approvals, memory, compaction |
Each layer contains the one before it. The harness decides what goes into the context. The context holds the prompt.
Anthropic’s engineering team gives the cleanest definitions:
- Context engineering is “the set of strategies for curating and maintaining the optimal set of tokens” (September 2025).
- The harness is “the loop that calls Claude and routes Claude’s tool calls” (April 2026).
Birgitta Böckeler’s article on martinfowler.com puts the common meaning in seven words: “everything in an AI agent except the model itself”.
Where the Word Came From
Two posts made the term popular in February 2026:
- Mitchell Hashimoto (5 February) wrote a step called “Engineer the Harness”. When the agent makes a mistake, you change the setup so it cannot make that mistake again.
- OpenAI (11 February) published “Harness engineering: leveraging Codex in an agent-first world”. A team of 3, later 7, engineers built an internal product where Codex wrote the code.
The OpenAI numbers are why people paid attention:
| Fact | Value |
|---|---|
| Lines of code | About 1 million |
| Pull requests merged | About 1,500 |
| Lines written by hand | 0 |
| Pull requests per engineer per day | 3.5 on average |
| Longest single Codex runs | Often more than 6 hours |
The team’s summary: “Humans steer. Agents execute.” The engineers did not write code. They built the harness: a short AGENTS.md (about 100 lines) used as a map, a structured docs/ folder, custom linters, structural tests, a bootable app per worktree, and local logs and metrics the agent could query.
OpenAI also warns that this result “should not be assumed to generalize without similar investment”.
Why the Harness Matters: The Data
Same model, different score
The official Terminal-Bench 2.0 leaderboard lists the same models in many harnesses. Claude Opus 4.6:
| Harness | Score |
|---|---|
| Meta-Harness | 76.4% |
| Capy | 75.3% |
| Terminus-KIRA | 74.7% |
| Droid | 69.9% |
| Terminus 2 | 62.9% |
| Claude Code | 58.0% |
That is an 18.4-point spread with no change to the model. Gemini 3.1 Pro shows the same pattern: 80.2% in TongAgents and 61.4% in Gemini CLI.
Same model, different cost
FrontierHarness Eval (September 2026) ran one model, Kimi K3, through 9 harnesses on 30 tasks:
| Harness | Pass rate | Median cost per pass |
|---|---|---|
| Exo Harness | 53.3% | $1.05 |
| Pi | 60.0% | $2.43 |
| DSH Creator | 63.3% | $3.28 |
| Codex | 66.7% | $3.47 |
| Claude Code | 63.3% | $18.34 |
Two harnesses passed the same 19 tasks at a 5.6x cost difference. The authors trace most of it to the prompt cache: 25% cache hits in Claude Code against 91.6% to 99.1% in the others. Claude Code is built for Anthropic’s cache rules, and this model uses a different one. One task took 381 turns in Claude Code and 90 in Pi.
The lesson is not “harness X is bad”. A harness is tuned for one model. Pair it with another and the cost or the score can move a lot.
A model upgrade can make harness parts useless
Anthropic found that Sonnet 4.5 needed context resets in a long task. On Opus 4.5, the problem was gone and “the resets had become dead weight.” A March 2026 Anthropic post says every harness part “encodes an assumption about what the model can’t do”.
So a harness is not done when it works. Check it again after each model change.
The Parts of a Harness
| Part | What it does | Fails like this when it is missing |
|---|---|---|
| Loop | Calls the model, runs tool calls, repeats | The agent answers once and stops |
| Instructions | Repo rules and a map of where things are | The agent guesses the build command |
| Tools | Shell, files, browser, APIs | The agent can describe a fix but cannot make it |
| Checks | Tests, linters, type checks | The agent says “done” and it is not |
| Permissions | What the agent may do without asking | One bad command runs on your real machine |
| Sandbox | Where commands run | The agent can reach your keys and files |
| Compaction | Shrinks old turns near the context limit | The session fails, or loses decisions |
| Memory | Notes that survive a new session | Each session starts from zero |
Böckeler sorts these into two kinds. Guides steer the agent before it acts, such as instructions. Sensors tell it what went wrong after it acts, such as test output. A good harness has both.
Where Each Part Lives in OpenClaw
OpenClaw is a harness. You do harness engineering when you change these files and settings:
| Part | OpenClaw feature | Setting |
|---|---|---|
| Instructions | AGENTS.md and the other workspace files, loaded each session | agents.defaults.workspace, bootstrapMaxChars (20,000), bootstrapTotalMaxChars (60,000) |
| Reusable procedures | Skills: folders with a SKILL.md | skills.entries, skills.load.extraDirs |
| Event code | Internal hooks on events such as /new and /reset | hooks.internal.entries.<name> |
| Sandbox | Runs tools in Docker, Podman, OpenShell or SSH. Off by default | agents.defaults.sandbox.mode: off, non-main, all |
| Tool policy | Which tools the agent has | tools.allow, tools.deny, tools.profile |
| Exec approvals | Which shell commands need your yes | tools.exec.mode: deny, allowlist, ask, auto, full |
| Compaction | Summarizes older turns, keeps recent ones | agents.defaults.compaction |
| Memory | Plain Markdown: MEMORY.md, memory/YYYY-MM-DD.md | agents.defaults.compaction.memoryFlush.enabled |
Two notes from the OpenClaw docs:
- Bootstrap files are cut when they pass the character limits. A long
AGENTS.mddoes not all reach the model. Keep it short, like OpenAI’s 100-line map. - Memory is only what is on disk. The docs say “there is no hidden state.”
How to Start Harness Engineering This Week
- Write down the last 3 mistakes your agent made. For each one, ask which harness part would have stopped it.
- Fix it in the harness, not in the prompt. A wrong build command goes in
AGENTS.md. A repeated bad edit gets a linter rule or a test. - Give the agent a check it can run. If it cannot run the tests, it cannot know it is done.
- Turn on the sandbox and exec approvals. Our security checklist has the settings.
- Cut your instructions. Move detail into
docs/files or skills and keepAGENTS.mdas a map. - Test again after a model change. Remove the parts the new model does not need.
Honest Caveats
- Leaderboard scores mix many things. Each harness entry was submitted separately, often by its maker. The spread shows that the harness matters, not by exactly how much.
- FrontierHarness is small. It used one model and 30 tasks, so one task is 3.3 points. The authors say this themselves.
- OpenAI’s result came from a team that built a lot of tooling. Do not expect it from a default setup.
- OpenClaw config keys change between versions. Older guides use
tools.exec.securityandtools.exec.ask. The docs sayopenclaw doctormigrates them totools.exec.mode.
Sources
- OpenAI: Harness engineering: leveraging Codex in an agent-first world (11 February 2026)
- Mitchell Hashimoto: My AI Adoption Journey (5 February 2026)
- Birgitta Böckeler: Harness engineering for coding agent users (April 2026)
- Anthropic: Effective context engineering for AI agents (September 2025)
- Anthropic: Scaling Managed Agents (April 2026): harness, sandbox and session definitions
- Anthropic: Harness design for long-running application development (March 2026)
- Terminal-Bench 2.0 leaderboard
- FrontierHarness Eval and the write-up (September 2026)
- OpenAI: Introducing the Agents API (September 2026): a hosted harness
- OpenClaw docs: agent workspace, skills, hooks, sandboxing, exec approvals, compaction, memory
See Also
- AGENTS.md vs CLAUDE.md: one source of truth for agent instructions
- Claude Code hooks vs skills: enforce or instruct
- MCP vs skills for agent tools: which one to use
- Why your Claude Code context window fills up: the context layer
- OpenClaw security checklist: the permissions and sandbox parts of the harness