Agent harnesses: a design guide for turning a model into a working system

What a harness is and why it is needed

The LangChain post source defines an agent as 'model + harness'. The harness is all the code, configuration and execution logic that is not the model itself. The post sums this up as "if it's not the model, it's the harness," and explains that a raw model is not an agent; it becomes one only when the harness provides state storage, tool execution, feedback loops and enforceable constraints.

The reason is simple. A model only takes inputs such as text and images and produces text. According to the same post source, a model by default cannot keep state across conversations, run code, access real-time information, or set up a working environment and install packages. Even the 'chat' we use every day is really the simplest harness: a loop wrapped around the model that remembers previous messages and appends new ones.

Research has also confirmed the effect of the harness. SWE-agent paper improved performance without changing model weights, only by designing the interface through which the model operates a computer (the authors call it the ACI, Agent-Computer Interface). Built on GPT-4 Turbo, it solved 12.47% of SWE-bench test tasks, well above the 3.8% of the previous best, a non-interactive retrieval-augmented approach. This is evidence that harness design matters as much as model choice.

For coding agents, it helps to separate two layers. A post on Martin Fowler's site source distinguishes the parts already built into the product, such as the system prompt and code search method, from the 'outer harness' that users layer on top to fit their own repository and use case. The application steps in this guide mainly deal with this outer harness.

Components: what a harness is made of

The LangChain post source lists the following harness components: the system prompt; tools, skills and MCP along with their descriptions; bundled infrastructure (filesystem, sandbox, browser); orchestration logic (spawning subagents, handing off work, model routing); and deterministically executed hooks and middleware (context compaction, task continuation, lint checks). This guide also treats verification mechanisms, which check results, as a separate component.

On the execution environment side, the same post source treats the filesystem as the most fundamental element. It serves as the workspace where the agent reads data, code and documents, offloads content that does not fit in the context, and stores state that persists after a session ends. Adding git makes it possible to track and roll back work. Giving bash and code execution as general-purpose tools has become the default strategy, and sandboxes (isolated execution environments) are used to run generated code safely, optionally with command allowlists and network isolation.

Context management and memory are also the harness's job. The drop in reasoning ability as the context window fills up is called Context Rot, and the harness keeps work going through compaction, which summarizes and moves existing content source. Memory files such as AGENTS.md are injected into the context when the agent starts, carrying knowledge across sessions.

Subagents are a mechanism for handling independent subtasks in parallel, each in its own separate context source. The orchestrator-workers pattern in Anthropic's post on building agents source has the same structure: a central LLM splits the work, delegates it to worker LLMs and combines the results. The post says this fits coding tasks where the number of files to change cannot be known in advance.

Design principles: what the sources agree on

First, start simple. Anthropic's post on building agents source recommends finding the simplest solution and adding complexity only when needed. Frameworks make it easy to get started but can hide the actual prompts and responses and make debugging harder, so the post advises starting with the LLM API directly and, if using a framework, understanding what it does under the hood.

Second, context is a resource to use sparingly. Anthropic's post on context engineering source says to find 'the smallest set of high-signal tokens' that maximizes the likelihood of the desired outcome. It recommends writing the system prompt at the 'right altitude', between brittle if-else-style hardcoding and vague generalities, testing a minimal prompt with a good model, and then adding instructions and examples based on failure cases. The same post also advises choosing diverse, representative examples rather than cramming in a list of edge cases.

Third, design tools as interfaces for the model. Instead of bash commands with dozens of options, SWE-agent paper gave a few simple commands such as viewing, searching and editing files, along with guardrails against common mistakes and short, specific feedback every turn. It also points out that while humans can ignore unnecessary information, for a model everything is a cost. Anthropic's post on writing tools source and its context post source likewise stress a minimal set of tools with no overlapping functions, clear namespacing, token-efficient responses and well-crafted tool descriptions, saying "if a human engineer can't definitively say which tool should be used, an agent can't either."

Fourth, pair guides with sensors. The post on Martin Fowler's site source distinguishes guides (feedforward), which set direction before an action, from sensors (feedback), which observe after an action so the agent can correct itself. With only feedback, the agent repeats the same mistakes; with only guides, you never learn whether the rules worked. It also notes that computational mechanisms such as tests, linters and type checks are fast and deterministic, making them good to run on every change, while inferential mechanisms such as AI code review or LLM-as-a-Judge are slow and non-deterministic but add semantic judgment.

Steps for applying a harness to a coding agent

Step 1 is to start with a minimal setup. Give a good model, a short system prompt and basic tools such as bash and file editing a few real tasks, and record where it gets stuck sourcesource. Do not write lots of rules from the start.

Step 2 is to build a 'map' in the repository. The OpenAI post source says a single giant AGENTS.md failed: it ate up context, when everything is important nothing is, it quickly went stale, and it was hard to verify mechanically. Instead, they kept an AGENTS.md of about 100 lines as a table of contents and placed design docs, execution plans and product specs in a structured docs/ directory as the 'system of record'. This is progressive disclosure: the agent starts from a small entry point and learns where to look next.

Step 3 is to wire up verification mechanisms. Let the agent run tests, linters and type checks itself, and put computational sensors in place first, such as a pre-commit hook that checks for module boundary violations source. The same post also suggests that if linter error messages include how to fix the problem, the model can read them and fix it right away. For a web app, have the agent check end to end like a human using a browser automation tool source.

Step 4 is to make the execution environment isolated and observable. The OpenAI post source made it possible to launch the app per git worktree and let the agent query the Chrome DevTools Protocol and logs, metrics and traces directly, handing it bug reproduction and fix verification. Step 5 is to refine tools through evaluation. Anthropic's post on writing tools source recommends building multi-step evaluation tasks close to real use and collecting tool call counts, token usage and tool errors along with accuracy to drive improvements.

Step 6 is to feed recurring mistakes back into the harness. The post on Martin Fowler's site source sees the 'steering loop', where repeated problems lead to fixing guides and sensors so they are less likely to recur, as the human's job. The OpenAI post source also says that when things failed, the fix was almost never 'try harder'; instead they asked "what capability is missing, and how do we make it legible and enforceable for the agent?"

Harnesses for long-running tasks

Tasks that take hours to days must span multiple context windows, and each new session starts with no memory of the previous ones. Anthropic's post on harnesses for long-running agents source compares this to engineers working in shifts where each new engineer remembers nothing of the previous shift. The post says compaction alone was not enough. Failures took two forms: trying to do too much at once and running out of context mid-implementation, leaving features half done; and later sessions seeing progress and prematurely declaring the job finished.

The solution is two prompts with different roles. In the first session, the initializer agent creates init.sh to start the development server, a progress file for logging work (claude-progress.txt) and the first git commit. It also writes a feature list that expands the user's request; in the claude.ai clone example, it listed more than 200 features, all marked as 'failing'. Later agents were only allowed to change the pass/fail field, and JSON was chosen over Markdown because the model was less likely to edit it carelessly source.

In later sessions, the coding agent gets its bearings in a fixed order. It checks the working directory, reads the git log and progress file, and picks the single highest-priority feature from the feature list that is not yet done. It starts the server with init.sh and runs a basic end-to-end (E2E) test first, then implements, and when finished leaves a descriptive commit message and progress summary, handing off in a 'clean state' source. With git in place, bad changes can also be rolled back.

The OpenAI post source points the same way. Complex work was kept in the repository as execution plan files containing progress and decision logs, and in-progress and completed plans, along with technical debt, were version-controlled together so the agent could work without outside context. The post says it is common for a single Codex run to work on one task for more than six hours.

Checklist

Setup check: Does the system prompt sit between excessive hardcoding and vague generalities source? Is the number of tools minimal with no overlapping functions, and can a human say definitively which tool to use in which situation sourcesource? Do tool responses return meaningful information while saving tokens source? Does agent code run inside a sandbox, with command allowlists and network isolation where needed source?

Context check: Does AGENTS.md act as a table of contents rather than an encyclopedia, and are stale docs caught by linters and CI source? Is there a strategy, such as compaction or offloading to files, for when the context fills up source? Do independent tasks delegated to subagents run in separate contexts source?

Verification check: Can the agent run tests, linters and type checks on its own and read the results sourcesource? Are fast checks placed before commit and expensive checks after integration source? For web features, does it check end to end with browser automation source? Do error messages explain how to fix the problem source?

Long-running task check: Are progress logs, a feature list and commit history left for the next session to read, does each session handle only one feature, and is the agent prevented from marking work complete without tests source? Finally, is there a loop that turns repeated mistakes into harness improvements source?

Common mistakes and limitations

The most common mistake is putting in too many instructions and tools. A giant instruction file crowds out the context the task needs and quickly goes stale source. A bloated tool set with broad functions and fuzzy boundaries is a typical failure named in Anthropic's context post source. Conversely, there is also a warning that stacking up harness frameworks without understanding them makes it easy to lose track of what happens inside source.

The second mistake is leaving verification to the model's own judgment. In Anthropic's post on harnesses for long-running agents source, Claude, without explicit instructions, only ran unit tests or curl checks and missed that features did not work end to end. Giving it a browser automation tool helped a lot, but parts invisible to the tool, such as native browser alert dialogs, still had many bugs.

Harnesses have limits too. The post on Martin Fowler's site source points out that computational sensors reliably catch structural problems such as duplicate code, complexity, test coverage and architectural drift, but neither computational nor inferential mechanisms catch bigger problems such as misdiagnosis of the problem, overengineering and unneeded features, or misunderstood instructions reliably enough to reduce oversight. In the end, a harness reduces the burden of human review but does not eliminate it.

Another issue is evaluation design. Anthropic's post on writing tools source advises avoiding overly simple evaluation environments, as well as strict verifiers that reject correct answers for trivial reasons such as formatting differences. Since there may be several paths to a correct answer, it warns against overfitting to a specific sequence of tool calls.

Further study

To get the concepts first, start with the LangChain post source. It works backward from what models cannot do, deriving one by one why the filesystem, bash, sandboxes, memory and compaction are needed. Next, Anthropic's post on building agents source is a good way to learn the difference between workflows and agents and basic patterns such as prompt chaining, routing and orchestrator-workers.

For a deeper look at design principles, read Anthropic's post on context engineering source together with its post on writing tools source. The former covers system prompts, tools and examples from the perspective of a context budget; the latter shows the process of prototyping tools and refining them through evaluation. If you need research evidence, SWE-agent paper shows how interface design affects performance.

For practical application, three posts complement each other. The post on Martin Fowler's site source offers a mental model of guides and sensors and of computational and inferential mechanisms; the OpenAI post source offers examples of repository knowledge structure and an observable execution environment; and Anthropic's post on harnesses for long-running agents source gives a concrete file layout and session startup routine for work spanning multiple sessions.