Harness Engineering

The problem

When an AI agent does something impressive — builds a working web page, triages a hundred support tickets — you probably credit the model. When it deletes a file or reports finishing work it never finished, you probably blame the model too. Both instincts are mostly wrong. The model is a text-prediction engine that cannot remember yesterday, open a file, run a command, or check its own work. Everything you actually observe — the memory, the file access, the safety prompts, the ability to catch a mistake — is bolted on around it by software the vendor built and, increasingly, that you configure. That surrounding software now has a name, and it is the thing to understand.

What it is

A harness is everything wrapped around an AI model that lets it do real work. The cleanest definition comes from LangChain engineer Vivek Trivedy:

“Agent = Model + Harness. If you’re not the model, you’re the harness.” — Vivek Trivedy, LangChain, 2026

He expands it in The Anatomy of an Agent Harness:

“A harness is every piece of code, configuration, and execution logic that isn’t the model itself. A raw model is not an agent. But it becomes one when a harness gives it things like state, tool execution, feedback loops, and enforceable constraints.” — Vivek Trivedy, LangChain, 2026

Origin note. The idea is older than the word: Anthropic wrote about models-plus-their-environment as one system in 2024 and 2025 without calling it a harness. The named discipline crystallized in early 2026, when practitioners noticed the same model performed wildly differently depending on the scaffolding around it — LangChain moved a coding agent from outside the Top 30 to #5 on the Terminal Bench 2.0 benchmark by changing only the harness. Trivedy’s March 10, 2026 post supplied the definition; Anthropic Labs published its own harness case study two weeks later.

How it works

A harness is not one thing. It is seven recurring parts, and each exists because the model cannot do that job by itself.

1. The system prompt and instruction files. A written brief the model reads at the start of every single conversation — its role, the house rules, the commands to use. In Claude Code this is a file called CLAUDE.md. Anthropic’s Best practices for Claude Code describes it plainly: “CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context it can’t infer from code alone.” Short and opinionated beats long and thorough.

2. Tools and MCP servers. Tools are narrow functions the model can call — read a file, run a query, post a message. MCP (Model Context Protocol) is Anthropic’s open standard for plugging external services in as tools. Whatever the agent has no tool for, it simply cannot do.

3. Permissions and approval gates. The rules deciding what the agent may do unsupervised and what needs a human “yes”. This is the safety layer, and it is the single setting most likely to make an agent either useless or dangerous.

4. Skills. Saved instruction packs — usually plain markdown — that the harness loads only when relevant. A procedure too niche for the permanent brief but too repetitive to retype lives here.

5. Filesystem and version control. A place to write things down and a Git history to roll back. This is the agent’s working memory and its undo button. Without a filesystem, an agent is just a chat window with ambitions.

6. Hooks. Scripts that fire automatically at fixed moments — before a tool runs, after an edit, before a commit — to block a destructive action or force a test to run. Hooks are how “the agent should do X” becomes “the agent cannot fail to do X.”

7. The verification loop. Something the agent can run to find out whether it actually succeeded: a test suite, a build that either passes or fails, a screenshot comparison. Anthropic’s docs put the failure mode bluntly: “Claude stops when the work looks done. Without a check it can run, ‘looks done’ is the only signal available, and you become the verification loop: every mistake waits for you to notice it.” Boris Cherny, who built Claude Code, calls this the biggest single lever there is.

Underpinning all seven is one hard constraint: the model’s context window — its short-term memory — is small and fills fast. Anthropic’s Effective context engineering for AI agents frames it as a budget:

“Context, therefore, must be treated as a finite resource with diminishing marginal returns. Like humans, who have limited working memory capacity, LLMs have an ‘attention budget’ that they draw on when parsing large volumes of context.” — Anthropic Applied AI team, 2025

Most harness design is spending that budget well.

Where it works

• Long-running autonomous coding. Anthropic Labs built a harness splitting the job across three agents — one plans, one writes, one judges — producing full-stack applications across multi-hour sessions. An agent grading its own homework is a lenient grader.
• Any task where the agent can check itself. Cherny’s advice is the most practically valuable line in the whole field: “Probably the most important thing to get great results out of Claude Code — give Claude a way to verify its work. If Claude has that feedback loop, it will 2-3x the quality of the final result.” — Boris Cherny, Anthropic, 2026
• Operations agents touching real business systems. Renewal-risk briefs, support triage, CRM updates. These work when the harness gives read access broadly, drafting freely, and sending only with explicit approval.
• Analysis over data far bigger than the context window. An agent that samples files on demand — a few lines here, a keyword search there — can work across gigabytes of logs while keeping its memory nearly empty.
• Onboarding. A good instruction file encodes the conventions a senior colleague would otherwise repeat to every new hire.

Where it breaks

• Too many tools. Give an agent forty overlapping tools and it will pick badly. Anthropic’s test: “If a human engineer can’t definitively say which tool should be used in a given situation, an AI agent can’t be expected to do better.” Fix: ship the smallest tool set that covers your real workflow, and add one only when a failure proves you need it.
• Permissions set wrong in either direction. Too tight and your team drowns in approval prompts and turns them off. Too loose and something ships to production unsupervised. Fix: auto-approve reads and drafts, always gate sends, deletes and payments.
• A bloated instruction file. Past a certain length the important rules get lost and the model ignores the file altogether. Fix: delete any instruction the agent already follows unprompted; convert the rest into a self-enforcing hook.
• No verifier. Without a pass/fail signal, the agent reports success on broken work — and you become the quality control. Fix: wire up one automatic check before you scale usage, even a crude one.
• Assuming a smarter model removes the need for all this. It doesn’t. Anthropic’s own conclusion from their long-running harness work in Harness design for long-running application development: “Our conviction is that the space of interesting harness combinations doesn’t shrink as models improve. Instead, it moves, and the interesting work for AI engineers is to keep finding the next novel combination.” — Anthropic Labs, 2026. Fix: budget for harness maintenance as ongoing work, not a one-off setup.

The honest cost: a good harness takes weeks of iteration, and version one usually performs worse than the chatbot you started with. It also quietly ties you to one vendor, because modern agents are tuned alongside their harness — a Claude Code config copied into a different tool will not reproduce the same results.

What this article does NOT cover

• Configuration syntax, code samples, or step-by-step setup instructions for any specific agent.
• Benchmark methodology or how to reproduce the Terminal Bench 2.0 result cited above.
• Security hardening, prompt-injection defence, or compliance requirements for agents touching regulated data.
• Pricing, token costs, or vendor comparison between agent platforms.

Sources

• The Anatomy of an Agent Harness — Vivek Trivedy, LangChain (Mar 10, 2026)
• Harness design for long-running application development — Anthropic (Mar 24, 2026)
• Effective context engineering for AI agents — Anthropic (Sep 29, 2025)
• Best practices for Claude Code — Anthropic documentation
• How Boris Uses Claude Code — Boris Cherny tips, compiled by Carolina Cherry