Harness Engineering: Designing the Scaffolding for Agentic Coding

For many developers, the first instinct when an AI agent fails is to blame the model. We wait for the next version of Claude or GPT, hoping a larger parameter count will solve the "skill issue" . However, a growing consensus among AI engineers suggests that the model is only one part of the equation. The true lever for performance is the harness—the entire system of prompts, tools, context policies, and execution logic that wraps around the model .

In fact, the impact of the harness can be dramatic. Data from Terminal Bench 2.0 indicates that changing only the harness while keeping the model fixed can move a coding agent from roughly 30th place into the top five . This shifts the engineering challenge from model selection to harness engineering: the practice of treating the agent's scaffolding as a first-class software artifact .

The Anatomy of a Modern Coding Harness

A harness is essentially the runtime scaffolding that transforms a raw language model into a functional agent . At its most basic, an agent can be defined as Model + Harness . While the model provides the reasoning engine, the harness provides the state, the tools, and the constraints necessary to perform real work .

Most professional harnesses converge on several core components:

The Agent Loop: Usually a ReAct (Reason + Act) loop where the model reasons, calls a tool, observes the result, and repeats .
Sandbox Abstraction: To avoid destructive actions like rm -rf on a host machine, harnesses use isolated environments—such as Docker containers or remote VMs—to execute code and manage files .
Context Management: Because context windows are finite and "context rot" can degrade reasoning, harnesses implement compaction techniques like summarization, truncation, or full session resets .
Tooling and Skills: This includes general-purpose tools like bash and grep, as well as specialized "skills"—reusable, multi-phase workflows (e.g., a TDD implementation loop) that are loaded only when needed to save token space .

Commentary: What this means in practice is that the model is essentially a stateless CPU, and the harness is the operating system. The most overlooked implication here is that as models improve, the harness doesn't become obsolete; it simply evolves. When a model gains a new capability (like a larger context window), the harness shifts its focus to higher-ceiling problems, such as coordinating multiple specialized agents or managing long-term memory across several days of work .

Designing the Steering Loop: Guidance and Guardrails

To prevent agents from mirroring the worst patterns in a codebase, a harness must regulate the agent's output through a combination of feedforward and feedback controls .

Feedforward: The Guides

Guides steer the agent before it acts. This is often achieved through guidance files like CLAUDE.md or AGENTS.md placed in the project root . These files act as a "pilot's checklist," defining architectural preferences, prohibited patterns, and tech stack conventions . Advanced harnesses use path-scoped rules, where specific guidance (e.g., React component rules) is only injected into the context when the agent is editing files in a corresponding directory .

Feedback: The Sensors

Sensors observe the agent after it acts to facilitate self-correction . These fall into two categories:

Computational Sensors: Deterministic tools like linters, type checkers, and unit tests . These are fast and cheap, allowing the harness to automatically inject error messages back into the loop for the agent to fix .
Inferential Sensors: LLM-based judges or security reviewers that provide semantic analysis . Because these are more expensive, they are often deployed as separate "reviewer agents" that run in parallel to the main implementation agent .

Commentary: The data suggests that the most effective harnesses treat every agent mistake as a permanent signal . Instead of simply retrying a failed prompt, the engineer should "ratchet" the harness by adding a new rule or sensor to prevent that specific error from ever recurring . This turns the harness into a living repository of the team's tribal knowledge, externalizing a human developer's experience into a machine-readable system .

Implementing Executable Workflows

High-performing agents rarely move straight from a prompt to a final pull request. Instead, they follow structured, multi-stage workflows that decompose complex goals into manageable tasks .

One widely adopted pattern is the Research $\rightarrow$ Plan $\rightarrow$ Implement (RPI) loop :

Research: The agent explores the codebase and produces a research artifact (e.g., spec.md) .
Plan: The research is broken into a structured task list (e.g., plan.json) .
Human Review: The human annotates the plan, creating a "shared mutable state" between the user and the agent before any code is written .
Implement: The agent executes the plan using TDD, verifying each task through the harness's sensors .

To manage these horizons, some harnesses employ a "Planner / Generator / Evaluator" split . By separating the agent that writes the code from the agent that grades it, harnesses avoid the common bias where agents grade their own work too leniently .

Commentary: Contrary to popular belief, adding more autonomy to an agent often decreases reliability. The most successful implementations actually increase the number of gates—such as requiring human approval for the plan or blocking destructive shell commands . The goal isn't to eliminate the human, but to move the human's input to the highest-leverage points: the planning and verification stages .

Summary and Key Takeaways

Building a harness is an iterative engineering discipline, not a one-time configuration task . The strength of the harness is fundamentally limited by the quality of the code it governs; if a codebase is inconsistent, the agent will likely propagate those inconsistencies .

Key Takeaways:

Prioritize the Harness over the Model: A mediocre model in a great harness will typically outperform a frontier model in a poor harness .
Build a Feedback Ratchet: Every mistake should result in a new rule in your guidance files or a new sensor in your guardrails .
Separate Planning from Execution: Use an RPI (Research, Plan, Implement) loop to align with the agent before committing tokens to implementation .
Enforce Mechanical Checks: Use computational sensors (linters, tests) as a mandatory back-pressure signal that the agent cannot bypass .
Isolate the Execution: Always wrap agent tool-calling in a sandbox to ensure safety and reproducibility .

This article was generated with AI assistance and has not been independently fact-checked. Readers should verify claims against the listed sources.