Your Coding Agent Is Dumb Without a Proper Harness

Your AI coding agent just broke a file it wasn't supposed to touch. Again.

You blamed the model. Switched to the newer one. Same chaos, different day.

Here's the part most developers miss: it was never the model's fault.

What Is Harness Engineering?

Harness engineering is the discipline of designing everything around an AI model — system prompts, tools, feedback loops, guardrails, sandboxes, and memory management — that turns it into a reliable, controllable coding agent.

The formula is simple:

AI Coding Agent = Model + Harness

The model provides raw intelligence. The harness determines whether that intelligence does useful, predictable work in production — or keeps failing the same way twice.

The term was coined by Mitchell Hashimoto — co-founder of HashiCorp and creator of Terraform — in his personal blog post "My AI Adoption Journey," published in February 2026. His core principle: "Anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again."

That one principle, consistently applied, is what separates teams shipping reliable AI-assisted work from teams babysitting their agents session after session.

The Four Phases of AI Engineering (Where Harness Engineering Fits)

If you've been working with AI coding tools for any length of time, you've lived through at least two of these phases:

Phase 1 — Prompt Engineering (2022–2023): The craft was in the wording. Write a better prompt, get a better output.

Phase 2 — Context Engineering (2024): Smarter teams started managing what the model sees, not just what they ask for. Context windows, RAG pipelines, and document structuring became the levers.

Phase 3 — Agent Engineering (2025): Agents started taking multi-step actions autonomously. The question shifted from "what do I show it?" to "how do I let it run?"

Phase 4 — Harness Engineering (2026–present): The current frontier. Now that agents can act, the challenge is making them act reliably, within real-world constraints, without blowing up your codebase. The model is no longer the primary variable. The harness is.

Why Your Agent Failures Are Configuration Failures, Not Model Failures

Here's a pattern playing out on engineering teams every week.

The agent does something dumb. The team blames the model. They file it under "wait for the next version." The next version ships. The agent does something different and equally broken.

Harness engineering rejects this loop. Here's what's actually happening:

• When your agent ignores a project convention — that's a missing AGENTS.md entry, not a model failure.

• When it runs a destructive command unprompted — that's a missing hook, not a hallucination.

• When it marks broken code as done and moves on — that's a missing feedback sensor, not a reasoning failure.

• When it rushes and cuts corners near the end of a long task — that's context anxiety, not sloppiness.

Every one of those is a configuration problem. And configuration is something you can fix today.

The Case That Proved It at Scale

In February 2026, OpenAI engineer Ryan Lopopolo published a field report that put hard numbers behind the harness engineering argument. His team built and shipped a production application with zero lines of manually written code. The codebase reached one million lines, managed across roughly 1,500 automated pull requests — built by a small team in approximately one-tenth the time it would have taken to write the code by hand.

The codebase didn't hold together because of the model. It held together because the team had engineered the system around the model: verification loops, structured handoff artifacts, defined context management, and iterative guardrails built from each prior failure.

That's harness engineering in production. It's not theoretical.

The 6 Layers of a Production-Grade AI Agent Harness

A harness isn't a single setting or a prompt tweak. It's a stack of intentional layers working together. Here's what each one does and why it matters.

1. Instruction Files — AGENTS.md, CLAUDE.md, Project Guides

This is your agent's institutional memory: everything it needs to know about your specific codebase that isn't in its training data.

What goes here: project conventions, off-limits paths, preferred libraries, build commands, test runners, dependency direction rules, edge cases the agent has already tripped over.

Mitchell Hashimoto maintains a living AGENTS.md for his Ghostty project — each line in it represents a past agent mistake that is now structurally prevented. That's the ratchet in action: every failure becomes a permanent fix, compounding over time.

What breaks without it: The agent treats every session like it's the first time it's seen your codebase.

2. Tools and MCP Servers — Capabilities the Agent Can Actually Use

Agents are only as useful as the tools they can call: file systems, browsers, test runners, APIs, databases, external services.

What goes here: carefully scoped tool access. Wider toolsets mean wider reach — and more surface area for things to go wrong. Define what the agent can call and what it cannot.

What breaks without it: Either the agent can't complete legitimate tasks (under-tooled) or it has access to things it shouldn't touch (over-tooled).

3. Hooks and Middleware — Deterministic Guardrails

This is where chaos gets contained. Hooks fire before or after model actions, deterministically — they don't ask the model to decide. They just run.

What goes here: blocks on dangerous commands, mandatory lint checks before committing, test runs before task sign-off, confirmation gates for irreversible actions.

What breaks without it: The model has the judgment of a very capable intern with no one looking over its shoulder. Some days that's fine. Some days it's not.

4. Feedback Loops and Sensors — How the Agent Knows If It's Correct

This is the most underbuilt layer in most agent setups. A feedback sensor is any structured signal that tells the agent whether its output actually worked: a test run, a linter pass, a type check, a format validation.

What goes here: automated tests that run after each significant action. The agent reads the results and continues or corrects — rather than declaring victory and moving on.

What breaks without it: Agents have a well-documented tendency to mark broken work complete. Anthropic's research identifies this as the self-evaluation problem — when asked to assess work they've just produced, agents reliably skew positive, treating their output as finished even when it isn't. A feedback sensor closes that loop structurally, replacing the agent's biased self-assessment with an independent, verifiable signal.

5. Context Window Management — Preventing Context Anxiety

This is an emergent failure mode that most teams don't recognize until they've been burned by it several times.

Context anxiety is what happens when a model senses it's approaching the limits of its context window. It doesn't crash. It doesn't throw an error. Instead, it quietly starts cutting corners — rushing through steps, skipping validation, wrapping up tasks at 60% completion, and sometimes generating artifacts like SUMMARY.md to externalize its own state.

Anthropic's engineering team documented this specifically in their research on long-running agent harnesses. Cognition AI independently confirmed it while rebuilding their Devin agent on Claude Sonnet 4.5 — the model was consistently underestimating remaining tokens and taking shortcuts even when it had ample space left.

The harness fix: structured context resets between sessions with deliberate handoff artifacts, or context compaction for shorter tasks. With newer models (Claude Opus 4.6 and its one million token context window), context anxiety has become less of a daily problem — but it doesn't disappear entirely under sustained, multi-hour autonomous sessions.

What breaks without it: Reliable first 30 minutes, increasingly unreliable everything after.

6. Subagent Orchestration — For Complex, Multi-Step Work

For longer or more complex tasks, a single agent loop breaks down. The task grows beyond what one context window can reliably handle, and quality degrades with each step.

What goes here: a three-role architecture used by Anthropic's own engineering team during development: a planner to decompose the work, a generator to execute individual steps, and an evaluator to validate output before anything gets committed or handed to the next step.

Note: Anthropic's research found this architecture can be simplified as model capability improves. With Opus 4.6, they moved to a leaner planner + generator + end-of-run evaluator structure and achieved equivalent output quality with less orchestration overhead. The right architecture depends on your model, your task complexity, and how much reliability you need at each step.

What breaks without it: One agent trying to hold a complete application's context in its head while also generating, evaluating, and committing code. It can't, reliably.

The Ratchet Principle: Why the Harness Compounds

This is what makes harness engineering genuinely different from prompt tweaking or model switching.

Every time your agent makes a mistake and you engineer a fix into the harness, that mistake becomes structurally impossible to repeat. The AGENTS.md entry prevents it. The hook blocks it. The sensor catches it before it ships.

That fix doesn't degrade. It doesn't forget. It applies to every future session automatically.

This means each iteration of your harness is more reliable than the last — not because the model got smarter, but because the scaffolding got tighter. That compounding effect is what the teams shipping production AI-assisted work at scale are actually building. Not prompt libraries. Harnesses.

Where to Start: 4 Steps to Your First Harness

You don't need to build all six layers at once. Here's the practical starting point:

Step 1 — Write your AGENTS.md (or CLAUDE.md)

Document what your agent needs to know about your codebase: conventions, off-limits paths, build commands, preferred libraries, past failure patterns. Start small. Add to it after every session where something goes wrong.

Step 2 — Add one hook

Identify the most common failure mode in your recent sessions. Build one deterministic guardrail against it. A pre-commit test run. A block on a destructive command. One hook is enough to start.

Step 3 — Set up one feedback sensor

A test run, a linter, a type check — any structured signal your agent can read and act on. Give it something to verify its own output against, not just your word that it's done.

Step 4 — Review after every session

Where did it slip? What would have caught it? Update the harness. The review doesn't need to take long. The discipline of doing it consistently is what matters.

A Realistic Next Step

If you're building serious workflows with AI coding agents — not experiments, actual production systems — the harness is where the reliability lives. The good news is that you can start with exactly three things: an instruction file, one hook, and one feedback sensor. Build from there, iteration by iteration.

If your team is at the stage where you need structured help thinking through agent architecture, workflow design, or AI implementation strategy, Vovance is an AI consulting firm that works with engineering teams on exactly these kinds of decisions. They don't promise outcomes they can't control — they help you build systems that are designed to hold.

Frequently Asked Questions

What is harness engineering? 

Harness engineering is the discipline of designing the full environment around an AI coding agent — including instruction files, tools, guardrails, feedback loops, and context management — so the agent operates reliably and predictably in production. The term was coined by Mitchell Hashimoto in February 2026.

What is AGENTS.md? 

AGENTS.md (or CLAUDE.md in Claude Code projects) is a project-level instruction file that gives your AI coding agent institutional memory about your specific codebase — conventions, off-limits files, preferred libraries, build commands, and rules learned from past failures.

What is context anxiety in AI agents? 

Context anxiety is a documented failure mode where an AI model senses it's approaching the limit of its context window and begins rushing, cutting corners, or declaring tasks complete prematurely — even when ample context space remains. It was identified in Anthropic's research on long-running agent harnesses and independently confirmed by Cognition AI during Devin's rebuild on Claude Sonnet 4.5.

Why do AI coding agents keep making the same mistakes? 

Usually because the harness hasn't been updated after failures. The model has no persistent memory between sessions. Without a mechanism that encodes lessons from past failures — like a living AGENTS.md or a hook that blocks a known bad behavior — it has no way to avoid repeating them.

Is harness engineering the same as prompt engineering? 

No. Prompt engineering adjusts what you ask the model. Harness engineering redesigns the environment the model operates in — tools, feedback mechanisms, guardrails, context management, and multi-agent orchestration. Prompt engineering is one input to the harness. It's not the harness itself.