What is Harness Engineering? Designing the Layer Around the LLM in the AI Agent Era

Harness engineering is a term that took off in February 2026. On February 5, 2026, Mitchell Hashimoto (creator of the Ghostty terminal and co-founder of HashiCorp) used it for a habit: every time an agent makes a mistake, you engineer a fix so it never makes that mistake again. Six days later, OpenAI put it in the title of a report from its Codex team. Anthropic had already been publishing designs for the machinery around long-running agents under the name "harness." If 2025 was the year people said context engineering comes after prompts, harness engineering covers the layer beyond that.

This article lays out what harness engineering actually is, how it differs from prompt and context engineering, the six components that make up a harness, real harnesses that OpenAI and Anthropic have published, a practical design checklist, and a comparison of today's leading tools — the foundation you need if you're serious about using or building AI agents.

1. What is Harness Engineering?

"Harness" originally refers to the gear and tack used on a horse — the rig that channels the animal's power in the direction you want. The term in AI works as exactly the same metaphor: the full set of equipment that puts a powerful but unruly LLM to productive work.

Concretely, that includes:

• Tools: file operations, web search, code execution — the means by which the LLM can take action.
• Context management: the strategy for what goes into the prompt and what gets compressed or discarded.
• Memory systems: persistent knowledge and user preferences that survive across sessions.
• Agent loop: the perceive → reason → act → observe cycle.
• Guardrails: permissions, sandbox, Hooks, approval flows.
• Output format: markdown, JSON, citations, streaming.

Designing all of that together is what we call harness engineering. Rather than training or improving the LLM itself, it's the craft of raising real-world utility by engineering everything around the LLM. Claude Code, Cursor, Devin, Codex CLI — they all run on roughly the same models, yet their behavior and performance diverge sharply because of the difference in their harnesses.

For where the word "harness" starts and stops, Birgitta Böckeler of Thoughtworks put it neatly on martinfowler.com (April 2, 2026): the harness is everything in an agent except the model, or Agent = Model + Harness. Anthropic uses the same word for its own cloud service: Claude Managed Agents is described as a configurable agent harness.

2. Harness Engineering vs Prompt Engineering

Prompt engineering hasn't gone away — but the scope is fundamentally different.

If prompt engineering is the craft of "what to say to the LLM," harness engineering is the craft of "what to give the LLM and how to operate it." The two aren't competing — they're layered. The prompt is just one component within the harness.

The other term people mix up is context engineering. In a September 29, 2025 post, Anthropic called it the natural progression of prompt engineering. Böckeler describes building a harness for a coding agent as one specific form of context engineering. Put together, they nest: prompt (what you say) ⊂ context (what the model sees) ⊂ harness (what it is given, how its work is checked, and how it is stopped). What is specific to the harness is the part that checks results mechanically and hands failures back to the agent — linters and tests, for example.

3. The 6 Components of a Harness

1. Tool Use

The LLM's means of acting on the world: reading and writing files, executing code, searching the web, calling APIs. Get the tool interface wrong — names, arguments, return values — and the LLM can't use it correctly. Concretely:

• Verb-based, unambiguous names (e.g. read_file).
• Required vs. optional arguments made explicit, with defaults.
• Structured error messages on failure (tell the model what to do next).
• Explicit warnings on side-effecting (destructive) operations.

2. Context Management

The LLM's attention is finite — what you show it determines what it says. Concretely:

• Relevance filtering: pull only the parts relevant to the task, not whole files.
• Compaction: summarize long conversations to retain them.
• RAG integration: fetch what's needed via vector search.
• Caching: trim cost on repeated system prompts using tools like Anthropic's prompt cache.

Related: What is RAG?

3. Memory System

Holding knowledge across sessions. Claude Code's CLAUDE.md, Cursor's .cursor/rules, and Codex's AGENTS.md are all examples of project memory. Beyond that:

• Short-term memory: recent conversation history.
• Long-term memory: user profile, past decisions.
• Factual knowledge: domain-specific knowledge bases.

4. Agent Loop

The core that makes an "AI agent" actually work. The base form is the perceive → reason → act → observe cycle:

1. Receive the user's goal.
2. Analyze the current state (gather information with tools if needed).
3. Plan the next action.
4. Act via a tool.
5. Observe the result; check whether the goal is met.
6. Loop if not, terminate if yes.

How smart your agent gets depends on whether you bake in replanning, self-critique, and subgoal decomposition.

5. Guardrails

The mechanisms that prevent runaway behavior. As Why AI Ignores Your .md Rules covers, enforcing behavior through the environment is far more reliable than asking nicely in prose:

• Approval mode: a human confirms before dangerous operations run (e.g. Claude Code's permission settings, Codex CLI's approval modes).
• Sandbox: restrict filesystem and network access.
• Hooks: arbitrary checks before and after tool calls.
• Rate limiting: minimize damage if something goes off the rails.

6. Output UX

Presenting results in a form the user can understand and verify. Markdown rendering, source citations, syntax-highlighted code blocks, streaming output, visible reasoning (thinking), structured output (JSON), and so on. Producing the "right answer" isn't enough — it's the harness's job to deliver it in a form the user can trust and verify.

4. Why Harness Engineering, Why Now?

Three forces are driving the surge of interest in harness work.

1. It has been shown that the same model produces very different results depending on what surrounds it. In an experiment Anthropic published on March 24, 2026, the same Claude Opus model got a one-sentence request to build a 2D retro game maker. A single agent finished in 20 minutes for $9, but the level it produced could not be played. A harness split into a planner, a generator and an evaluator ran for 6 hours and cost $200 — and produced a game where you could actually move your character (the physics were still rough). The cost was more than 20x, but so was the gap in quality. Choosing between quality and cost is now as much a harness decision as a model decision.

2. Problems prompts alone can't solve are stacking up. "Too many tools, the model picks the wrong one." "The context is so packed the important signal is buried." "On long-running tasks, the agent loses the thread halfway through." These aren't problems you fix with cleverer wording in a single turn — they're design problems.

3. The engineer's job itself has started to change. OpenAI's Codex team reported building an internal product for five months with zero lines of hand-written code, reaching about a million lines and about 1,500 merged pull requests (February 11, 2026). Their conclusion: the main job moved from writing code to designing environments, specifying intent and building feedback loops. Claude Code, Codex, Cursor, Devin and the other major products are all competing on the design outside the model.

5. Published Examples: Three Real Harnesses

Harness engineering easily turns abstract. Here are three examples whose builders published the details, described at the level of what they actually did.

1. OpenAI's Codex team: AGENTS.md as a map, rules enforced by linters

• They kept AGENTS.md to a roughly 100-line table of contents and made a docs/ directory in the repository the system of record for design, plans and quality notes. One giant file crowded out the task, went stale quickly and could not be checked mechanically.
• To keep the docs fresh, linters and CI check cross-links and structure, and a recurring agent looks for descriptions that no longer match the code and opens fix-up PRs.
• Layering, dependency direction, structured logging, file size limits and more are enforced by custom linters and structural tests. The error messages spell out how to fix the problem, so the agent can read them and repair its own work.

2. Anthropic: designing the hand-off for long-running agents

When development spans many context windows, agents tried to build too much at once or declared the job done halfway through. Anthropic (November 26, 2025) handled it like this:

• Only the first session runs an initializer agent with its own prompt. It sets up a feature list (feature_list.json), a progress log (claude-progress.txt), an init.sh that starts the dev server, and an initial git commit.
• Every later session reads the progress log and git log to get oriented, implements only one feature, and ends with a commit and a progress update.
• The feature list is JSON rather than Markdown, because the model was less likely to rewrite it inappropriately. The only field it may change is the pass/fail field (passes).
• A feature is marked done only after it has been tested end to end through browser automation, the way a user would.

3. Mitchell Hashimoto: never let the same mistake happen twice

The person who named it works at a smaller scale. When the agent makes a simple mistake, he adds a line to AGENTS.md; in his Ghostty terminal project, each line of that file maps to a past bad behavior, and that almost completely resolved them. When prose is not enough, he builds actual scripts — to take screenshots, to run filtered tests — and hands them to the agent.

What the three share is that the weight sits on mechanisms that check and send work back, more than on asking in prose. The checklist below helps decide how much to turn into mechanism.

6. A Practical Harness Design Checklist

7. Comparing the Major Harnesses

Each of these harnesses runs on more or less the same LLMs (Claude / GPT / Gemini), yet their strengths diverge sharply because of differing harness design philosophies. "Which harness?" matters more than "which LLM?" — that's the real battleground of the agent era.

8. Anti-Patterns

1. Adding too many tools

The more tools you add, the easier it is for the LLM to pick the wrong one. Anthropic's documentation says Claude's tool selection accuracy degrades once more than 30–50 tools are available, and offers tool search to load only the relevant tools on demand. Its guide to writing tools also says more tools do not always mean better outcomes: rather than wrapping every API endpoint as a tool, consolidate similar functions.

2. Stuffing everything into context

"Just show it everything, to be safe" is counterproductive. Run things through a relevance filter and include only what's necessary. Context is a device for surfacing the important signal — not a storage closet.

3. Implementing safety with prompts alone

"Please don't perform dangerous operations" gets ignored sooner or later, depending on the situation. The right answer is to make it physically impossible at the environment level — sandbox, Hooks, permission limits.

4. Never revisiting what you added

Every piece you add makes a harness heavier, slower and more expensive. After the experiment above, Anthropic removed components one at a time and compared the results, keeping only what still helped (the planner and the evaluator). Its point: every component of a harness encodes an assumption about what the model cannot do on its own, and those assumptions go stale quickly as models improve. When you switch models, check one by one whether each check and split you added still pulls its weight.

Summary

Harness engineering is the craft of designing the layer "outside" the LLM. Prompt engineering is just one component within the harness. Treating the six elements deliberately — tool definition, context management, memory, loop, guardrails, output UX — can transform real-world performance from the same underlying LLM.

As of 2026, the main battleground for production AI agents has clearly moved to the harness. Building "smart harnesses" — not just writing "smart prompts" — will be the differentiator for the next generation of engineers.

FAQ

Q1. So we don't need prompt engineering anymore?

Wrong. It's still essential — as one component within the harness. Tool descriptions, system prompts, error messages — all of those are prompt design surfaces. What's outdated is the mindset of "I'll fix this with a better prompt."

Q2. What's the first step to learn harness engineering?

Take Claude Code or Cursor and don't just use it — change its behavior by tweaking its config. Turned into steps, Hashimoto's approach looks like this:

1. Write down each agent failure (which instruction, what went wrong).
2. For simple failures, add one line to CLAUDE.md / AGENTS.md / .cursor/rules.
3. For repeated failures, or ones that would hurt, stop them mechanically with Hooks, linters or tests — and write the fix into the error message.
4. Have the agent do the same task again and confirm the failure is gone.

Q3. Are harnesses the same as frameworks like LangChain?

Close, but not the same. A framework is an implementation toolkit; a harness is a design discipline and mindset. LangChain, LlamaIndex, the Claude Agent SDK, and the like are tools for building harnesses.

Q4. Build my own harness vs. use an existing one?

For most cases, an existing harness (Claude Code, Cursor, etc.) plus customization is enough. Building one from scratch only makes sense for enterprise requirements, niche domains, or extreme cost optimization.

Q5. Will "harness engineer" become a real job title?

There is no settled job title yet. Hashimoto himself wrote that he did not know whether a broadly accepted industry term existed. But OpenAI's Codex team reports that the engineer's main work has moved to designing environments, specifying intent and building feedback loops — the substance of the job is changing before any title settles.