Harness Engineering: Build the Scaffolding Around an AI Model

A raw model is not an agent; it only becomes one when a harness provides state persistence, tool execution, and enforceable constraints. The fundamental equation of modern AI systems is Agent = Model + Harness. Performance gains now come from engineering the environment where a model operates rather than waiting for higher-parameter weights.

What is harness engineering?

Harness engineering is the design of the environment that lets AI agents operate stably and autonomously. It is the set of tools, hooks, sandboxes, and logic that guide a powerful but unpredictable model toward a specific goal.

A technical metaphor is horse tack: the reins, saddle, and bridle. You do not make the horse smarter; you design the equipment that makes its raw strength useful. From a systems perspective, the operating-system analogy is the most accurate architectural model:

• Model: the CPU (raw processing power).
• Context: the RAM (volatile, limited working memory prone to leakage).
• Harness: the operating system (manages resources, inputs, boundaries, and I/O).

Harnessing shifts the developer's role from "requesting" behavior (hoping for a good output via prompts) to "enforcing" behavior (creating an environment where the agent is constrained from failing).

Why the harness decides performance more than the model

Data from Terminal Bench 2.0 proves that the harness is the primary performance lever. On this benchmark, the same model (e.g., Claude Opus 4.6) saw its score jump from 52.8% to 66.5% simply by moving from a generic environment to a custom harness.

• The "skill issue" reframe: most failures attributed to "dumb" models are configuration problems. If an agent fails a convention, the harness engineer doesn't wait for GPT-6; they add the rule to an AGENTS.md file or wire a linter into the loop to force correction.
• The model–harness training loop: modern models like GPT-5.2 and Opus 4.7 are post-trained specifically to use the tools provided by developer harnesses (e.g., str_replace, bash). A custom harness that provides sharper back-pressure unlocks latent capabilities that generic environments leave on the floor.
• The 22x cost/quality gap: benchmarks show a solo agent costing ~$9 often produces broken software. A harnessed agent, despite costing ~$200 due to verification loops, produces a functional, production-ready product. This reflects the investment required for autonomous reliability.

How harness, prompt, and context engineering differ

AI engineering has moved through three phases:

1. Phase 1: Prompt Engineering (early 2023). Focus on instructions and personas. Artifacts like CLAUDE.md acted as "style guides" but were merely requests with no enforcement.
2. Phase 2: Context Engineering (2024). Focus on facts and grounding. Introduced RAG, tool-calling, and MCP (Model Context Protocol) to manage the 4k-token bottleneck.
3. Phase 3: Harness Engineering (2025–2026). Focus on execution, verification, and state. This phase introduces the "sprint contract"—a negotiation between a Planner and an Evaluator agent to define "done" before a single line of code is generated.

The first two stages help the model think better; harness engineering ensures it acts reliably over time. The harness does not replace prompt engineering or context engineering—it contains both and adds an enforcement layer the agent cannot skip.

What a harness is made of

A production harness consists of six architectural layers:

1. Information Boundaries: defining cognitive scope to prevent focus loss and "context anxiety."
2. Tool Systems: restricted actuators (bash, filesystem). Tool descriptions are a vector for prompt injection; third-party MCP servers must be treated as untrusted text.
3. Execution Orchestration: managing routing between Planner, Generator, and Evaluator.
4. Memory/State: maintaining continuity via durable files and append-only event logs.
5. Evaluation/Observability: independent sensors that verify output against the real world, not the model's internal representation.
6. Constraints/Recovery: hard-coded gates (e.g., blocking rm -rf) and automated retry logic.

The core artifacts a harness keeps

A good harness uses structured artifacts to maintain state across sessions where the context window would otherwise reset. An AGENTS.md file turns conventions and past incidents into machine-readable constraints:

# AGENTS.md — Engineering Constraints
- Architecture: Next.js 15 App Router.
- Constraint: All API routes must use AuthErrorHandler.
- Constraint: Never use 'rm -rf' or 'git push --force' (Ref: Incident #402).
- Historical Failure: Agent previously deleted .env files; hooks now block all .env writes.

A feature list doubles as a project spec and a progress tracker that both agents and humans can read:

{
  "feature": "OAuth PKCE Flow",
  "verification": [
    "Verify redirect to provider",
    "Confirm JWT is stored in encrypted SharedPreferences"
  ],
  "status": "failing"
}

Core principles for building a harness

• Context over instructions: grounding an agent in real file paths and code patterns outperforms abstract commands.
• Separation of planning and execution: decouple the "Planner" from the "Generator" to prevent cascading logic errors.
• Feedback loops: use computational sensors (linters, type-checkers) for millisecond-latency feedback and inferential sensors (LLM-based reviewers) for semantic quality.
• Deterministic enforcement: "Success is silent, failures are verbose." Only inject error text into the model loop when constraints are violated.
• Incrementalism: enforce a "one unit of work, one commit" policy to prevent context rot.

Solving the 4k-token bottleneck

When context windows fill, models lose reasoning depth. A harness manages this via:

• Context Reflect: restarting the agent entirely with a compressed hand-off summary to clear the "RAM."
• Tool-call offloading: moving large logs or data structures to the filesystem rather than keeping them in the prompt.

Claude Code and harnesses in production

Tools like Claude Code and Cursor are primarily harnesses that manage the lifecycle of a model.

Nguồn: I built an autonomous harness for Claude Code — r/ClaudeAI

• The Sora Android case study: four engineers at OpenAI used a Codex-based harness to ship one million lines of code in just 28 days. They consumed ~5 billion tokens to maintain a 99.9% crash-free rate. The engineers focused on the harness architecture, while the agents handled implementation.
• Ralph Loops: an autonomous pattern where a hook intercepts a model's exit, re-injects the goal into a fresh context, and forces continuation until all verification sensors pass.

Where harness engineering is heading

• Harness-as-a-Service (HaaS): moving from raw LLM APIs to harness APIs (OpenAI Agents SDK, Claude Agent SDK) that provide loops, sandboxes, and registries out of the box.
• Harness decay: the "build to delete" philosophy. Components that were load-bearing for Opus 4.5 (like complex planning steps) become redundant overhead for Opus 4.7. Optimizing the Opus 4.6 harness has already shown a 38% cost reduction by removing unnecessary scaffolding.
• Agents as compilers: the harness is evolving into a "fuzzy compiler" that takes high-level constraints and "builds" artifacts through multiple optimization passes.

FAQ

Doesn't a larger context window make harnesses obsolete? No. Larger windows increase "context anxiety" and reasoning dilution. A harness uses Context Reflect to maintain a pristine cognitive state, which is required regardless of window size.

Is a harness just a complex system prompt? No. A prompt is a request; a harness is a runtime environment. A prompt cannot execute a git commit, run a linter, or manage a sandbox. The harness is the code that executes those actions.

What is the "build to delete" philosophy? It is the practice of regularly disabling harness components. If GPT-5.4 can follow a convention without an explicit AGENTS.md rule, that rule should be deleted to save tokens and reduce latency.

References

• Harness Engineering: What Every AI Engineer Needs to Know in 2026 — Yanli Liu
• Agent Harness Explained in 8 Minutes — Caleb Writes Code
• Harness Engineering: Make Your AI Agent Perform Better Than 80% of Others — Nick T.
• Building Claude Code with Harness Engineering
• How to Build Harness 2.0: Better Than 99% of People — Gao Dalie
• Agent Harness Engineering — Addy Osmani
• Harness Engineering: How to Build Software When Humans Steer, Agents Execute — Ryan Lopopolo, OpenAI