Agent = model + harness. The model reasons; the harness decides whether the result can be trusted. Swap the model → marginal shift. Change the harness → whether the system works at all.
Harness: the complete operational environment an AI agent works inside — tools, constraints, memory, feedback loops, observability, failure recovery. Model = engine. Harness = the rest of the car. Nobody drives an engine.
Term coined by Mitchell Hashimoto (HashiCorp, Terraform, Ghostty), February 2026. OpenAI field report days later: “Harness engineering: leveraging Codex in an agent-first world.” Formal guides-and-sensors taxonomy from Martin Fowler and Birgitta Böckeler, April 2026. Now standard vocabulary at OpenAI, Anthropic, LangChain, and most serious agent teams.
Core discipline: agent makes a mistake → engineer a permanent fix into its environment so that mistake becomes structurally impossible to repeat. System change, not “do better next time.” Mindset shift underneath: “the model is bad at X” → “my system allowed X.”
Prompt → context → harness
| Wave | Years | Optimizes | Breaks at |
|---|---|---|---|
| Prompt engineering | 2022–24 | Phrasing of a single exchange | Multi-step agents, tool use, state |
| Context engineering | 2024–25 | What the model sees: retrieval, memory, window management | Autonomous runs across hundreds of decisions |
| Harness engineering | 2026– | The environment the agent acts in | Current frontier |
Progression, not replacement. Prompt and context engineering didn’t die — reclassified as components inside the harness. First two shape a single turn. Third shapes whether an agent runs for hours without supervision.
Six components of a harness
| Component | Job | Missing → |
|---|---|---|
| Tools | Act beyond text: search, code execution, database, files, APIs | Agent thinks, can’t act |
| Constraints | Hard boundaries, uncrossable regardless of what the model generates | One-module refactor rewrites the codebase |
| Memory | Persistence across sessions and runs, at the right layer | Every conversation is the first conversation |
| Feedback loops | Verify output before it reaches the user | Most expensive failures — also the most-skipped part |
| Observability | Logs, traces, alerts per decision | 2am failure, nothing to reconstruct |
| Failure recovery | Defined behavior on timeout, API error, failed step | One bad call kills the whole workflow |
Guides and sensors
Fowler/Böckeler split, now the canonical vocabulary: every harness part is one of two things.
Guides
Feedforward — steer before the agent acts. System prompts, AGENTS.md / CLAUDE.md, tool definitions, constraint documents.
Sensors
Feedback — verify after it acts. Evals, linters, schema validators, tests, output parsers, drift detection.
Three layers of a harness
- Model interface — API calls, prompt templates, parameters, response parsing, API error handling. Table stakes; what most people mean by “AI engineering.”
- Runtime environment — tool definitions, memory stores, input validation, output guardrails, context management. The most-skipped layer; reliable products in 2026 engineer it deliberately.
- Orchestration — agent loops, task decomposition, conditional branching, approval gates, parallel execution. Decides whether multi-step work behaves predictably or catastrophically.
Known agent failure modes
Documented in Anthropic’s harness research. Inherent to models, solvable at the harness level.
| Failure mode | Looks like | Harness fix |
|---|---|---|
| Victory declaration bias | Task marked complete, outcome never verified | Verification loop: “done” = checks pass, not model says so |
| Context anxiety | Window fills → model rushes, cuts corners | Tight task scoping, context compaction, fresh session per task |
| One-shotting overreach | Whole problem in one pass → tangled, undocumented changes | Task decomposition, scope limits per run |
Build rules
1. Ratchet every mistake
Hashimoto’s founding rule. Every failure → one new rule, lint, or gate. AGENTS.md grows one line per incident. Harness only moves one direction: tighter where it actually failed. Fixing the session without fixing the system = the mistake comes back.
2. Enforce, don’t ask
“Follow our standards” in a prompt = probabilistic compliance. Linter that blocks the PR = deterministic. Hard checks — schemas, tests, linters, CI gates — beat instructions the model can ignore. OpenAI’s Codex experiment ran custom linters on every PR; no agent could bypass them.
3. Cap everything
Loop iterations, retries, tokens, spend, wall-clock time. A runaway loop discovered by the invoice = harness failure, not model failure. Every cap paired with an alert when hit.
4. Gate the irreversible
Human approval before deletes, deploys, sends, payments, migrations — anything that touches the outside world or can’t be undone. Reversible actions run free; irreversible ones queue for a person.
5. Fewer tools, sharper tools
Every tool = decision surface = failure surface. Trimming the tool list raises task success rates. Least privilege by default: an agent refactoring one module gets write access to that module, nothing else.
6. Trace every decision
Log inputs, tool calls, and outputs per step. Requirement: reconstruct any run after the fact, step by step. Debugging an untraced agent = guessing. Traces also feed evals — proof of whether a harness change actually helped.
Proof it works
- OpenAI, Aug 2025–Jan 2026: production product, zero human-written code. ~1 million lines, ~1,500 PRs merged, 3 engineers, ~3.5 PRs per engineer per day. Trust carried by enforced constraints, feedback loops, approval gates, full tracing — not by a smarter model.
- LangChain, March 2026: coding agent moved 30th → 5th on Terminal Bench 2.0. Model unchanged. Entire gain from harness optimization.
No code required
Same six components, buildable in Zapier, Make, or n8n:
- Validation step after every AI output before the workflow continues → feedback loop
- Defined branch for every failed tool call → failure recovery
- Hard cap on loop runs, alert when hit → constraint
- Assistant touches only the data its job requires → least privilege
- Human review on high-risk outputs → approval gate
- Action log kept for audit → observability
FAQ
No — reclassified. Prompts are one component inside the harness (the guides layer). Past a reasonable baseline, prompt gains plateau fast; harness gains keep compounding across every run.
No. Validation steps, fallback paths, loop caps, and review gates in no-code tools are harness engineering. The mindset transfers whole: treat every AI workflow as a system, and fix the system rather than the prompt.
An AGENTS.md or CLAUDE.md at the project root: structure, build and test commands, conventions. Add one rule per repeated failure. Then hard caps, then one deterministic check on output. Three moves, fastest practical return.
No. Framework = plumbing you build with. Harness = your rules, checks, constraints, and telemetry living in that plumbing. A framework can host a harness; it doesn’t ship one. Same with agents like Claude Code: the default harness is a starting point, your custom layer is the discipline.
Still settling. Listed today as AI infrastructure engineer, agent platform engineer, or AI systems engineer. Skill mix: software architecture + systems thinking + knowing how language models fail in practice. Already fluent in state, observability, and failure recovery → most of the way there.
Harness Audit Checklist
Run this against any AI agent or automated workflow to find the gaps before production does.
- Tools: can the agent act on everything it needs — and nothing it doesn’t?
- Constraints: what is structurally impossible, regardless of what the model generates?
- Memory: what persists across sessions, and where does it live?
- Feedback loops: what verifies output correctness before a user sees it?
- Observability: can you reconstruct any run, step by step, after the fact?
- Failure recovery: what happens on a timeout, an API error, a failed step?
Tags: agents, harness, audit, checklist, reliability, production
AGENTS.md Starter Template
Drop this at the root of a repo to give coding agents their first harness, then grow it one rule per failure.
# AGENTS.md
## Project
[ONE-LINE DESCRIPTION]. Key directories: [DIRS].
## Commands
- Build: [BUILD_CMD]
- Test: [TEST_CMD]
- Lint: [LINT_CMD]
Run tests before declaring any task done.
## Conventions
- [CONVENTION 1]
- [CONVENTION 2]
## Anti-patterns
One rule per real incident. Never delete, only add.
- [DATE]: [WHAT WENT WRONG] -> [RULE THAT PREVENTS IT]Variables: [ONE-LINE DESCRIPTION], [DIRS], [BUILD_CMD], [TEST_CMD], [LINT_CMD], convention and anti-pattern entries
Tags: agents.md, claude.md, coding agents, harness, template
Harness Review Prompt
Point an AI at any agent workflow you have built and have it find the harness gaps for you.
You are reviewing the harness around an AI agent, not the agent itself.
Here is the setup: [DESCRIBE WORKFLOW: what the agent does, which tools
it can call, what checks exist, what limits are set, what gets logged]
Assess it against six components: tools, constraints, memory, feedback
loops, observability, failure recovery. Mark each present, partial, or
missing.
Then give the three highest-risk gaps. For each: the concrete failure
it enables, and the cheapest structural fix. Assume the agent will
eventually do the worst thing its permissions allow.Variables: [DESCRIBE WORKFLOW]
Tags: prompt, agents, harness, review, audit, risk
No-Code Harness Moves
Five structural fixes that harden any Zapier, Make, or n8n automation without writing code.
- Validation step after every AI output — criteria check before the workflow continues
- Fallback branch on every external call — failure routes somewhere defined, never a dead end
- Hard cap on loops and retries — set a max, alert when hit
- Least-privilege access — the automation touches only the data its job requires
- Human approval before anything irreversible — sends, deletes, payments, publishing
Tags: no-code, zapier, make, n8n, automation, harness, reliability