# Agent Harness Checklist: Build the Minimum Viable Harness > An agent harness checklist in six layers: what each layer holds, which agent failure it prevents, and when to skip it. Build the smallest layer first. Source: https://capitalandcompute.net/blog/agent-harness-checklist/ Published: 2026-10-18 Updated: 2026-10-18 A minimum viable agent harness has six layers: a bounded task, a legible environment, controlled tools, durable state, evidence of completion, and recovery. Build them in that order, and add each one only when you see the failure it prevents. That rule is not a style preference. A 2026 source-code study of eleven coding agents found the floor is very low: the open-source Mini-SWE-Agent covers every harness subsystem in roughly 100 lines, with self-reported benchmark results in the same range as systems a thousand times its size. Everything production harnesses add on top is about safety, recovery and cost, not raw task completion. The checklist below orders the build in six layers and ties each item to what Anthropic, OpenAI and that study actually published. Key takeaways * A harness is everything around the model: the loop, tools, context, permissions, state and checks. Most agent failures that look like reasoning failures are missing harness layers. * Reliability compounds. At 95% per step, a 20-step task finishes cleanly about 36% of the time (0.95 to the 20th power, computed, not measured). Verification gates are how you raise the per-step number. * The minimum viable harness in the Barbaste et al. study is about 90 lines: a linear loop, four tools, Markdown context discovery and threshold compaction. It leaves out sandboxing, multi-agent and MCP on purpose. * Completion is a fact about the environment, not a claim by the model. Run deterministic checks first and use a separate evaluator only where code cannot decide. * Every harness component encodes an assumption about what the model cannot do. Re-test them after each model upgrade and delete the ones that no longer earn their cost. ## Why do AI agents fail when the model is fine? Most agent failures are environment failures. The agent read the wrong files, called the right tool with the wrong arguments, forgot a decision from the last session, retried a half-finished write, or declared victory without running the tests. None of those is a reasoning problem. Each is a missing piece of the system around the model. That is the case for engineering the harness rather than rewriting the prompt. A better prompt fixes the run in front of you. A hook, a check or a state file fixes that failure for every run after it. The arithmetic explains why small gaps matter. If each step of a task succeeds independently with probability p, the whole run succeeds with probability p to the power of the step count. The curves below are computed, not measured. They show the shape of the problem, not any real agent’s numbers. __A small per-step gap becomes a large end-to-end gap__ | Steps | 95% step + check (= 99%) | 95% per step | 90% per step | | ----- | ------------------------ | ------------ | ------------ | | 1 | 99.0% | 95.0% | 90.0% | | 5 | 95.1% | 77.4% | 59.0% | | 10 | 90.4% | 59.9% | 34.9% | | 20 | 81.8% | 35.8% | 12.2% | | 30 | 74.0% | 21.5% | 4.2% | Illustrative arithmetic by Capital & Compute (October 2026): end-to-end success is p^n for n dependent steps. The top line assumes a 95% step plus a check that catches and fixes 4 of every 5 errors, which works out to 99% per step. At 30 steps, a 95% agent finishes cleanly about one run in five. Swapping in a better model might move 95% to 96%. A check that catches most errors before the next step builds on them moves it much further, which is why the expensive work in 2026 moved from prompts to harnesses. [Harness engineering in 2026](/blog/harness-engineering-techniques-2026/) covers the named techniques; this page is the build checklist. ## What is the minimum viable harness? The term comes from a July 2026 arXiv preprint, [_Harness Engineering: Anatomy, Architecture, and Evolution of Coding Agents_](https://arxiv.org/abs/2609.00006) (Barbaste, Darrigol, Vu and Wiltberger). The authors read the source code of eleven coding harnesses, including Claude Code, Codex CLI and Gemini CLI, and mapped seven subsystems every one of them implements in some form: | Subsystem | What it does | Smallest version seen | | ---------------------- | -------------------------------------------------------- | ----------------------------- | | Agent loop | Alternates model calls with actions; owns stop and retry | A plain while loop over bash | | LLM integration | Builds the prompt, talks to the provider | One API call, one template | | Tools and actions | What the agent can do, file editing above all | Bash only | | Memory and context | Rations the window; carries knowledge across sessions | An unbounded message list | | Safety and permissions | What runs, what asks, what is forbidden | A cost limit and a step limit | | Orchestration | Spawns and coordinates sub-agents | None (single agent by design) | | Extensibility | Config, hooks, skills, plugins, MCP | Python protocols | At the other end, the same table records Claude Code with 43 typed tools loaded on demand, and Codex with policy rules, a model-based approval reviewer and an OS sandbox on three platforms. The paper closes with a roughly 90-line Python scaffold. It has a linear loop, middleware-style policies, four tools (bash, read, write and search-and-replace), automatic discovery of Markdown context files up the directory tree, and compaction when the context passes a threshold. It deliberately leaves out sandboxing, multi-agent orchestration and MCP or skills. The authors’ advice is the rule this whole page follows: start there, measure, and add the minimum your observed failures demand. ## The agent harness checklist, layer by layer The table puts the six layers in build order and maps every item to the failure it prevents and the case where you can skip it. | Layer | What goes in it | Failure it prevents | Skip it when | | ------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------ | | 1\. Bounded task | Objective, scope, what must not change, acceptance checks, actions that need approval | Busy work that never reaches the goal | Never; this is a paragraph, not a project | | 2\. Legible environment | A short project map, build and test commands, local rules, known dependencies | Editing the wrong files; guessing commands | The task touches one file you name | | 3\. Controlled tools | Typed tool schemas, argument validation, path and domain limits, timeouts, risk levels | Bad arguments; runaway or destructive calls | The agent only reads and a human applies changes | | 4\. Durable state | Run state outside the transcript, checkpoints, decisions, lessons | Lost decisions between sessions; repeated half-done writes | The work fits in one session and is idempotent | | 5\. Evidence | Deterministic checks first, an independent evaluator for judgment calls, a change receipt | “Done” claims with nothing behind them | A human inspects every output anyway | | 6\. Recovery and learning | Failure classes, retries that change something, budgets, escalation, harness updates | The same failure, billed again | Failure is cheap and a human reruns it | Three of these layers have a primary-source pattern worth copying directly. **Layer 1 is a contract, and Anthropic uses one.** In [_Harness design for long-running application development_](https://www.anthropic.com/engineering/harness-design-long-running-apps) (March 2026), Prithvi Rajasekaran of Anthropic Labs describes a generator and an evaluator “agreeing on what ‘done’ looked like for that chunk of work before any code was written.” That is the task contract: outcome, scope and the evidence that proves it, written before work begins. **Layer 2 is a map, not a manual.** OpenAI’s [_Harness engineering: leveraging Codex in an agent-first world_](https://openai.com/index/harness-engineering/) (Ryan Lopopolo, February 2026) describes an internal product built with no hand-written code. Adobe’s open-source [AI repo harness guide](https://opensource.adobe.com/ai-repo-harness-guide/READING/) summarizes its context advice as treating AGENTS.md as a table of contents rather than an encyclopedia. The agent gets a small map and fetches detail when the task needs it. Loading the whole repository up front buries the few lines that matter. **Layer 4 lives outside the model.** Anthropic’s [_Scaling Managed Agents: Decoupling the brain from the hands_](https://www.anthropic.com/engineering/managed-agents) (Lance Martin, Gabe Cemaj and Michael Cohen, April 2026) splits an agent into three parts: the brain (model and harness), the hands (sandbox and tools) and the session (an event log). “Because the session log sits outside the harness, nothing in the harness needs to survive a crash.” A crashed run resumes from the log instead of starting over. The same separation is what [durable execution engines like DBOS](/blog/dbos-durable-execution-agent-harness/) sell as a product. ## How do you build an agent harness step by step? Build it in the order failures show up, not the order a diagram suggests. A practical sequence for a coding or research agent: 1. **Write the contract.** Five lines: the outcome, what is in scope, what must not change, the command or check that proves completion, and which actions need a human. Put it in the task, not the system prompt. 2. **Give it a map.** A rules file of under a page, listing where things live and how to build and test. Point to deeper docs instead of pasting them. The [Claude Code harness guide](/blog/claude-code-harness-guide/) shows what each layer costs in context. 3. **Shrink the tool list.** Start with read, write, search-and-replace and a shell, like the 90-line scaffold. Validate arguments, restrict paths, set timeouts, and mark anything with a side effect as needing approval. 4. **Add one deterministic check.** The test suite, a type check, a schema validation. Run it automatically after every edit, and make a failure block the agent rather than inform it. 5. **Persist state to disk.** A progress file and a decisions file that the next session reads first. Anthropic’s earlier post [_Effective harnesses for long-running agents_](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) (November 2025) used a JSON feature list with a pass or fail status per feature, precisely because a summary cannot garble a boolean. 6. **Set budgets.** Maximum attempts, wall-clock time, spend and the scope of anything destructive, with a named escalation when a budget runs out. 7. **Stop and watch it fail.** Only now add the next layer, aimed at the failure you actually saw. Whether to build this yourself or rent it inside Claude Code or Codex is a separate decision; [build vs buy an agent harness](/blog/build-vs-buy-agent-harness/) works through the cost, and the [agent harness comparison](/best-ai-agent-harnesses/) lists the open-source options. ## How should an agent prove the work is done? An agent saying “done” is another model output. Completion is a change in the environment that something other than the agent can observe: a test passing, a file existing with the right schema, a query returning the expected row. Order the checks by cost. A compiler, a schema validator, a checksum or a test answers in milliseconds and never hallucinates. Use a model only where the question is a judgment call that code cannot settle, such as whether a design is readable or a summary is faithful. When you do use a model, do not let the worker grade itself. Rajasekaran’s post is blunt: “agents reliably skew positive when grading their own work,” and separating the agent doing the work from the agent judging it “proves to be a strong lever.” The evaluator should get the contract, the artifact and a rejection rubric, and it should be allowed to reject without fixing. Its job is to find the reason the work fails, not to offer a second draft. End every run with a change receipt: what changed, which checks ran and their results, what was not verified, and what risk remains. That is what a reviewer reads instead of a transcript, and what the next session starts from. A receipt lists proof A summary repeats what the model said it did. A receipt lists only what the system can prove: files touched, commands run with exit codes, checks passed and failed. If a line cannot point to evidence, it belongs under unresolved risk. ## What should a retry change? A retry that changes nothing buys the same failure again. Classify the failure first, then change the condition that caused it. | Failure class | Typical sign | What the next attempt changes | | -------------------------- | -------------------------------------- | -------------------------------------------------- | | Transient | Timeout, rate limit, flaky network | Wait and retry the same call, idempotently | | Bad input to a tool | Validation error, wrong path | Fix the arguments; tighten the schema if it recurs | | Missing context | Edits the wrong module, invents an API | Add the file or doc to the map, then retry | | Wrong approach | Checks fail the same way twice | Re-plan from the contract with a fresh context | | Policy or permission block | Denied action | Escalate to a human; never route around the block | Rules that must hold every time belong in code, not in the prompt. A model can forget an instruction on turn 40\. A permission check that runs before every tool call cannot. Anthropic’s Managed Agents post gives the strongest example: rather than telling the model to handle credentials carefully, “the structural fix was to make sure the tokens are never reachable from the sandbox where Claude’s generated code runs.” Put the rule where the model cannot reach it. ## When do you not need a harness? A single model call with a person reading the answer needs no harness. The same holds when the output is easy to check by eye, failure costs little, and nothing outside the conversation changes. Add harness layers when work spans several tools or sessions, when actions have real side effects, when completion is hard to judge by hand, when the same failure keeps coming back, or when review time is the bottleneck. A multi-agent setup is the last thing to add, not the first. The arXiv authors’ corpus includes Aider, a widely used coding agent with no orchestration at all, by design. ## How do you know the harness still earns its keep? Harnesses decay. Rajasekaran’s post puts it in one line: “every component in a harness encodes an assumption about what the model can’t do on its own.” When the model improves, some of those assumptions stop being true. Anthropic’s Managed Agents post shows it happening. Sonnet 4.5 needed context resets to stop it wrapping up tasks early. When the same harness ran on Opus 4.5, the behavior was gone, and in the post’s words, “the resets had become dead weight.” The safeguard had turned into overhead. So treat each router, evaluator, memory layer and retry rule like production code with an owner. After each model upgrade, ask which failure the component prevents, how often that failure still happens, and what it costs in tokens and latency. Then try removing it. Measure the system on accepted work, not activity: * first-pass acceptance rate * unsupported “done” claims per run * human interventions per task * repeat failures of the same class * time from request to verified result * harness overhead by component, in tokens and seconds A high task count means little if every result needs a careful human review. Count results a reviewer accepted, per hour of reviewer time, and the [real cost of running an agent in production](/blog/ai-agent-production-cost/) is mostly that attention. ## Frequently asked questions What goes in a minimum viable agent harness? A loop that alternates model calls and tool calls, a small typed tool set (read, write, search-and-replace and a shell), a short context file the agent loads at start, a compaction rule for long sessions, and step and cost limits. The July 2026 arXiv study by Barbaste et al. fits this in about 90 lines of Python and leaves out sandboxing, multi-agent and MCP on purpose. What is an agent harness checklist? A layered list of what to build around a model before giving it autonomy: a bounded task contract, a legible environment, controlled tools, durable state, evidence of completion, and recovery with budgets. Each layer maps to a failure it prevents, so you add it only after seeing that failure. How many tools should an AI agent have? As few as the task needs. The minimum viable harness in the 2026 Barbaste et al. study uses four. Claude Code exposes 43 typed tools but loads them on demand rather than all at once. Every exposed tool is another way to make a mistake, so hide tools that are irrelevant to the current task. Should the same agent check its own work? Not for judgment calls. Anthropic reported in March 2026 that agents reliably skew positive when grading their own work, and that a separate evaluator with explicit criteria is a strong fix. Run deterministic checks such as tests and schema validation first, and use a separate evaluator only where code cannot decide. ## Sources * Barbaste, P., Darrigol, T., Vu, G. and Wiltberger, T. (2026). _Harness Engineering: Anatomy, Architecture, and Evolution of Coding Agents: A Source-Code Study of Eleven Systems_. arXiv (preprint). * Martin, L., Cemaj, G. and Cohen, M. (2026). _Scaling Managed Agents: Decoupling the brain from the hands_. Anthropic Engineering. * Rajasekaran, P. (2026). _Harness design for long-running application development_. Anthropic Engineering. * Anthropic (2025). _Effective harnesses for long-running agents_. Anthropic Engineering. * Lopopolo, R. (2026). _Harness engineering: leveraging Codex in an agent-first world_. OpenAI. * Adobe (2026). _AI repo harness guide: reading list_. Adobe Open Source (secondary summary of the OpenAI post).