What Is Harness Engineering? Agent Harness Explained
Updated November 9, 2026 — Re-checked every claim against OpenAI, Anthropic, LangChain and Cursor sources; added Anthropic's March 2026 harness-design post, current Claude Code and Cursor behaviour, and removed outdated or unsupported claims.
Harness engineering is designing everything around an AI model so that it works reliably as an agent: the tools it can use, the context it sees, the rules that limit it, and the checks that catch its mistakes. The model is the engine; the harness is the rest of the car.
This page is the short explainer: the definition, where the term came from, the parts of a harness, and real examples. For a hands-on walkthrough of setting one up, read our harness engineering guide.
Harness Engineering Meaning
The cleanest definition comes from the tools themselves. Anthropic's Claude Code documentation says an agent runs on two components, models that reason and tools that act, and that Claude Code is "the layer around the model that provides the tools and manages the context the model sees. This surrounding layer is what the term agentic harness refers to" (source).
Birgitta Böckeler of Thoughtworks, writing on Martin Fowler's site, puts it as a formula: Agent = Model + Harness, where harness is "everything in an AI agent except the model itself" (source). Harness engineering is then the deliberate work of shaping that layer for your codebase or product.
The word itself comes from horse tack: a horse is strong and fast, but reins and a bridle decide where that strength goes. The model is the horse. The harness channels it. A good harness does more than restrain the agent, though. It also makes the agent more capable by giving it the right context, tools and feedback at the right time.
Not to be confused with: in manufacturing and automotive jobs, "harness engineer" usually means someone who designs wire or cable harnesses. That is a different field. In AI, the term only took off in 2026.
Where the term came from
- February 2026: OpenAI published "Harness engineering: leveraging Codex in an agent-first world," describing a product built over five months in which every line of code was written by Codex agents (source). This post made the term mainstream.
- February 2026: LangChain showed a coding agent jumping from 52.8% to 66.5% on Terminal Bench 2.0 by changing only the harness, with the model (gpt-5.2-codex) held fixed (source).
- March 2026: Anthropic published "Harness design for long-running application development," following its November 2025 post on harnesses for long-running agents (source).
- April 2026: Böckeler's article on martinfowler.com replaced her earlier February memo with a fuller model of a coding-agent harness (source).
The Problem Harness Engineering Solves
A bare model in a loop makes a good demo and an unreliable product. The harness exists because of a few predictable failures.
Agents start every session with no memory. Anthropic's long-running-agent post puts it directly: agents "must work in discrete sessions, and each new session begins with no memory of what came before." Their fix was a harness with an initializer agent that sets up an init.sh script, a progress file, a JSON feature list and an initial git commit, plus a coding agent that works on one feature at a time and leaves clear notes for the next session (source).
Agents grade their own work too kindly. Anthropic found that "agents reliably skew positive when grading their own work," and that splitting the builder from the judge is "a strong lever to address this issue" (source). LangChain saw the same pattern: agents wrote a solution, re-read it, decided it looked fine, and stopped without testing (source).
Tool access without limits is risky. An agent with an open shell can delete files, touch production data or leak secrets. Sandboxes and permission rules are part of the harness.
Projects drift. Without enforced structure, agent-written code slowly loses its shape. OpenAI's team found that "the constraints are what allows speed without decay or architectural drift" (source).
The Five Parts of an Agent Harness
Most harnesses, simple or complex, are built from the same pieces.
1. Tools and context
What the agent can do and what it knows. This includes file, shell, web and API tools, plus instruction files such as AGENTS.md or CLAUDE.md that tell the agent how a repository works. OpenAI's lesson was to keep AGENTS.md short (about 100 lines) and use it as "the table of contents" pointing into a structured docs/ folder, rather than one giant instruction file (source).
2. Guardrails and constraints
Deterministic rules the agent cannot talk its way around:
- Sandboxes and permissions that limit which files, commands and network access are allowed
- Linters, type checkers and tests that reject bad output
- Architecture rules, such as allowed dependency directions between layers
OpenAI enforced its architecture "mechanically via custom linters (Codex-generated, of course!) and structural tests," and wrote the lint error messages so they tell the agent how to fix the problem (source).
3. Feedback and verification loops
Ways for the agent to find out it is wrong before a human does: running tests after each change, a separate reviewer or evaluator agent, a checklist before the agent is allowed to finish, and loop detection when it keeps editing the same file. LangChain's 13.7-point Terminal Bench gain came largely from changes like these: a pre-completion checklist, a loop-detection middleware and a plan-build-verify-fix prompt (source).
4. Observability
Logs, traces and metrics that both humans and the agent can read. OpenAI gave Codex a local logging and metrics stack per git worktree, queryable with LogQL and PromQL, so prompts like "ensure service startup completes in under 800ms" became checkable tasks (source).
5. Human checkpoints
Where people still decide. OpenAI's engineers "prioritize work, translate user feedback into acceptance criteria, and validate outcomes," and treat every agent struggle as a signal that a tool, guardrail or doc is missing (source). The aim is human judgment at the expensive decisions, not approval of every keystroke.
Harness Engineering Examples
OpenAI Codex
OpenAI's team started from an empty repository in late August 2025. Five months later it held "on the order of a million lines of code," with roughly 1,500 pull requests merged by three engineers driving Codex, an average of 3.5 PRs per engineer per day. Throughput rose as the team grew to seven (source). Their harness included the short AGENTS.md map, an app instance bootable per git worktree with Chrome DevTools access for UI checks, the per-worktree observability stack, and custom linters for architecture and "taste" rules.
The product side follows the same idea. Codex reads AGENTS.md files from your home directory and project before starting work (source), runs commands inside an OS-level sandbox with an approval policy for anything outside it (source), and OpenAI describes the shared agent loop behind the Codex web app, CLI, IDE extension and desktop app as "the Codex harness" (source).
Anthropic: Claude Code and long-running agents
Claude Code's harness shows up as permission modes, checkpoints, hooks and memory files. Before Claude edits a file it snapshots the contents, so edits can be rewound. Permission modes range from Manual (asks before edits and shell commands) and Accept edits to Plan and Auto, where a classifier reviews actions in the background and blocks risky ones; on recent versions Auto is the default starting mode for interactive sessions (source). Hooks run your own commands at points in the agent's lifecycle, for example a PreToolUse hook that blocks destructive shell commands (source). CLAUDE.md holds project instructions, and Claude Code can read an existing AGENTS.md instead.
Anthropic's March 2026 post goes further: a planner, generator and evaluator agent working together over multi-hour sessions. A solo run took 20 minutes and cost $9; the full harness took 6 hours and $200, and the author wrote that the output quality difference "was immediately apparent." The central lesson: "every component in a harness encodes an assumption about what the model can't do on its own," so those parts should be re-tested as models improve (source).
Cursor rules
Cursor's project rules live in .cursor/rules as version-controlled .mdc files. Each rule can apply always, when the agent judges it relevant, to matching file patterns, or only when @-mentioned. Cursor also reads AGENTS.md files in the project root and subfolders (source).
Your First Agent Harness, in Brief
You do not need a million-line codebase to start. The short version:
- Write the instruction file.
AGENTS.md(read by Codex, Cursor and others) orCLAUDE.md: how to build, test and lint, plus the conventions that matter. Keep it short and link to deeper docs. - Close the loop. Make the agent run tests or a checker after every change and fix failures before it reports success.
- Set limits. Use the tool's sandbox or permission settings; block destructive commands; start strict and loosen later.
- Turn repeated mistakes into rules. When the agent makes the same error twice, add a lint rule, test or hook rather than another line of prompt.
- Decide where humans approve. Production data, infrastructure and security settings are good places to start.
For full examples of each step, see our harness engineering guide.
Harness Engineering vs. Related Terms
vs. prompt engineering. Prompt engineering is about the wording of one model input. Harness engineering is the system around many calls: tools, state, verification, permissions and monitoring. Prompts are one part of a harness.
vs. context engineering. Context engineering decides what information goes into the model's context window. Böckeler calls engineering a user harness for a coding agent "a specific form of context engineering" (source), but a harness also includes things that are not context at all, such as sandboxes, linters and tests.
vs. MLOps. MLOps manages the life cycle of models: training, deployment, monitoring, retraining. Harness engineering usually leaves the model untouched and shapes how an agent behaves while it runs.
vs. DevOps. Harness engineering borrows CI, reproducible environments and monitoring from DevOps, but points them at agent behaviour rather than at shipping software.
Tools and Frameworks
- OpenAI Codex (web, CLI, IDE extension, desktop app):
AGENTS.md, sandboxing and approvals, and the Codex App Server for embedding the harness in your own product (source). Note that OpenAI's older Assistants API was sunset on August 26, 2026; new integrations use the Responses API (source). - Claude Code and the Claude Agent SDK: the SDK gives you "the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript" (source).
- LangChain Deep Agents: LangChain describes Deep Agents as "the agent harness for complex, multi-step work," adding planning, a virtual filesystem, subagents and long-term memory on top of LangChain and LangGraph (source).
- CrewAI: multi-agent crews plus Flows, which CrewAI describes as "structured, event-driven workflows" for connecting tasks and managing state (source).
- Cursor: project rules and
AGENTS.mdsupport inside the editor (source).
What Harness Engineers Do
"Harness engineer" is becoming a real job focus at teams that ship agent products, though it is rarely a formal title yet. The day-to-day work:
- Writing and pruning instruction files (
AGENTS.md,CLAUDE.md, rules) - Building tools and APIs that agents can call reliably
- Adding tests, linters, hooks and evaluator agents that catch mistakes
- Reading agent traces and logs to find recurring failures
- Setting sandboxes, permissions and approval points
- Removing harness parts that newer models no longer need
OpenAI summed up the shift: the team's primary job is "no longer to write code, but to design environments, specify intent, and build feedback loops that allow Codex agents to do reliable work" (source).
The Bottom Line
Harness engineering answers one question: how do you make an AI agent reliable enough to trust with real work?
The published evidence points the same way. LangChain moved a coding agent from just outside the Terminal Bench top 30 into the top 5 without changing the model. OpenAI's three-to-seven-person team shipped a million-line product with Codex writing the code. Anthropic got far richer apps from a planner-generator-evaluator harness than from a single agent, at higher cost.
The principles are settled even though the term is new: give the agent clear context, limit what it can do, check its work mechanically, and keep humans at the high-stakes decisions. If you use Codex, Claude Code, Cursor or your own agent loop, you are already doing harness engineering. The question is whether you are doing it on purpose.
Sources
- Harness engineering: leveraging Codex in an agent-first world - OpenAI
- Unlocking the Codex harness: how we built the App Server - OpenAI
- Custom instructions with AGENTS.md - OpenAI Codex docs
- Sandbox - OpenAI Codex docs
- Assistants migration guide - OpenAI
- Effective harnesses for long-running agents - Anthropic
- Harness design for long-running application development - Anthropic
- How Claude Code works - Claude Code docs
- Hooks reference - Claude Code docs
- Agent SDK overview - Claude Code docs
- Rules - Cursor docs
- Improving deep agents with harness engineering - LangChain
- Deep Agents overview - LangChain docs
- Flows - CrewAI docs
- Harness engineering for coding agent users - Birgitta Böckeler, martinfowler.com

