Harness Engineering: Shape the Environment, Not the Model

Harness engineering is improving a coding agent's output by shaping everything around the model instead of the model itself. You hold the model constant and work on the two levers you control: the context the agent gets and the tools it can use, including the tests, linters, and sandboxes that tell it whether it's done. When the agent makes the same mistake twice, you don't write a longer prompt. You change the harness so the mistake becomes unlikely, or catchable before a person sees it.

The shorthand that stuck is Agent = Model + Harness. The model is the part you rent from Anthropic, OpenAI, or someone else. The harness is the part you own.

This guide covers where the term came from, what a harness is made of, what OpenAI learned shipping a product with no hand-written code, and how to build one harness that works for every agent on your team. We checked every product claim against first-party sources on October 9, 2026.

A harness at a glance#

Layer	What it does	Examples
Instructions (guides)	Tell the agent what it would otherwise guess	AGENTS.md, CLAUDE.md, skills, specs, architecture notes
Tools	Let the agent act on the real system	CLIs, MCP servers, a browser, simulators, database access
Sensors (feedback)	Tell the agent whether it got it right	Tests, type checks, linters, structural tests, review agents
Environment	Give each run a clean, reproducible place to work	Worktrees, containers, setup scripts, seeded databases, unique ports
Guardrails	Limit what a run can damage	Sandboxes, approval modes, network rules, secrets handling
Observability	Show what happened and what it cost	Logs, transcripts, traces, usage and cost data

Where the term came from#

On February 11, 2026, OpenAI published Harness engineering: leveraging Codex in an agent-first world by Ryan Lopopolo. His team built and shipped an internal product with zero lines of manually written code. Five months in, the repository held on the order of a million lines, and roughly 1,500 pull requests had been opened and merged by a team of three engineers driving Codex: about 3.5 PRs per engineer per day. Throughput rose as the team grew to seven.

The post's central claim is about the job, not the model: the team's work became designing environments, specifying intent, and building feedback loops that let Codex do reliable work. Lopopolo keeps an anthology of his writing on the subject, which defines the practice as improving agent output by shaping the environment around a model you treat as a black box.

Birgitta Böckeler's Harness engineering for coding agent users on martinfowler.com brought the idea to everyone who uses Claude Code or Codex rather than building them. Since then the term has spread into research papers, courses, and vendor blogs, including Lilian Weng's Harness Engineering for Self-Improvement and Google's The Anatomy of Harness Engineering.

Inner harness and outer harness#

Böckeler draws a useful line. Every coding agent ships with a harness built in: Claude Code and Codex each have a system prompt, a way to find code, and an agent loop you don't control. Around it, you build an outer harness for your codebase.

A good outer harness does two things. It raises the odds the agent gets it right the first time, through guides that feed forward: instructions, examples, conventions. And it catches what still goes wrong, through sensors that feed back: tests, linters, type checks, and review. The human job becomes steering: when a problem happens more than once, improve a guide or add a sensor so it stops happening.

Böckeler sorts sensors by what they protect:

• Maintainability: linters, formatters, complexity limits, and dead-code checks.
• Architecture fitness: structural tests that fail when a module imports something it shouldn't.
• Behavior: unit, integration, and end-to-end tests, plus scenario checks that compare the result with the spec.

What OpenAI's experiment taught#

Three lessons from Lopopolo's post carry over to almost any team:

1. Make the repository teach the agent. Knowledge that lives in people's heads or chat threads doesn't exist for the agent. Put conventions, architecture decisions, and "we don't do it this way because of that incident" into the repository, close to the code.
2. Turn taste into checks. The team captured preferences once (shared utility packages over hand-rolled helpers, validated boundaries instead of guessed data shapes) and enforced them on every change.
3. Collect garbage continuously. Background Codex tasks scan for drift, update quality grades, and open small refactoring pull requests, most reviewable in under a minute. Paying technical debt down daily beats tackling it in painful bursts.

The harness is also the agent#

People use "harness" in a second sense: the agent program around the model. "The Codex harness" means Codex's own loop, tools, and context management, and OpenAI's Agents API runs hosted agents on that open-source harness. DeepSeek Harness, an open-source agent harness from DeepSeek built so that "everything is a plugin," passed 240,000 GitHub stars within two months of its August 2026 release. When someone compares "coding agent harnesses," they usually mean Claude Code, Codex, OpenCode, Pi, or DeepSeek Harness running the same model on the same task.

The two senses meet in your repository. Whatever agent you run is the inner harness; AGENTS.md, skills, tests, and setup scripts are the outer harness you bring to all of them. That's the argument for writing the outer harness once and keeping it agent-neutral. See how to compare coding agents for why the harness often matters more than the model.

A harness for parallel agents#

One agent in one checkout is forgiving. Five agents at once expose everything a harness leaves implicit. These controls matter most when you run agents in parallel:

• A workspace per task. Each agent gets its own git worktree, so edits, build output, and untracked files can't collide. Escalate to a container when a task needs its own services, packages, or network rules, and to a remote machine or cloud VM when it needs to keep running after the laptop sleeps.
• A setup script. A setup script such as .agentastic/setup.sh makes a fresh worktree ready to build: install dependencies, copy env files, pick a free port, seed a database. See agent worktree setup for ports and databases.
• Fast, local checks. If the test suite takes 20 minutes, agents skip it or stall on it. Split a fast suite the agent runs on every change from the slow one CI runs.
• A second opinion. A review pass by a different agent or model is a sensor too. Agentastic can run code review with Claude, Codex, CodeRabbit, or Greptile on any diff before you read it.
• One set of instructions. Codex reads AGENTS.md; Claude Code reads CLAUDE.md, which can import AGENTS.md. Keep one source of truth so every agent follows the same rules.

A starter checklist#

1. Keep a running list of what the agent gets wrong. Each repeat is a harness bug.
2. Put build, test, and lint commands at the top of AGENTS.md, with the one command that proves a change works.
3. Add a linter rule or structural test for every convention you have corrected twice.
4. Make every new worktree ready to run with a setup script.
5. Give the agent the tools a person would use to check their work: a browser, a simulator, logs, a staging API.
6. Add a review agent as a sensor before human review.
7. Track cost and time per merged change, so you can tell whether a harness change helped.

Once the harness can verify work on its own, you can let agents run more of it unattended. That's loop engineering, the next floor up, and the step after that is an AI software factory.

Sources#

• OpenAI, Harness engineering: leveraging Codex in an agent-first world (February 11, 2026); Ryan Lopopolo, harness engineering anthology
• Birgitta Böckeler, Harness engineering for coding agent users (martinfowler.com)
• Lilian Weng, Harness Engineering for Self-Improvement; Google Developers, The Anatomy of Harness Engineering
• OpenAI, Introducing the Agents API; DeepSeek Harness on GitHub
• Agentastic docs: setup and teardown scripts, containers, code review, cloud agents
• On this site: loop engineering, context vs harness vs loop engineering, agentic engineering vs vibe coding

Frequently asked questions#

What is harness engineering?#

Harness engineering is improving a coding agent's output by shaping everything around the model instead of the model itself: the instructions it reads, the tools it can call, the tests and linters that check its work, and the sandbox it runs in. The model stays fixed; the environment gets better every time a mistake repeats.

What is an agent harness?#

An agent harness is everything in an AI agent except the model: the loop that calls the model, its tools, how it manages context, its permissions, and the checks around it. Claude Code, Codex, OpenCode, and DeepSeek Harness are harnesses. The parts you add to a project, such as AGENTS.md, skills, tests, and setup scripts, form an outer harness of your own.

Who coined harness engineering?#

The term spread after OpenAI's February 11, 2026 post by Ryan Lopopolo, Harness engineering: leveraging Codex in an agent-first world, which described shipping a product with zero manually written lines of code. Birgitta Böckeler's article on martinfowler.com then framed it for people who use coding agents rather than build them.

Is Claude Code harness engineering?#

Claude Code is a harness: Anthropic's agent loop, tools, and context management around Claude models. Harness engineering is what you do with it, such as writing CLAUDE.md and skills, adding hooks that run your linters, giving it MCP servers, and isolating each session in its own worktree.

What is the difference between harness engineering and context engineering?#

Context engineering decides what the model sees. Harness engineering is broader and includes context, plus tools, sensors such as tests and linters, permissions, and the runtime environment. Martin Fowler's article calls building a user harness a specific form of context engineering.

How do I start harness engineering?#

Write down what the agent keeps getting wrong, then turn each lesson into the cheapest control that prevents it: a line in AGENTS.md, a skill, a linter rule, a structural test, or a setup script. Make the repository's checks fast enough that the agent runs them on every change.