What’s a harness?

Harnesses are old news now.

This is no longer a new buzzword in agentic engineering, and it's for that reason that I think it's a good time to talk about them - from some level of experience. We have moved beyond the initial excitement so can ask a better question:

What does a harness actually mean for teams in AI-native engineering?

At a broad level, an agentic coding harness is the system around a coding agent that helps it do better work consistently.

It does this not by relying on the perfect prompt, but by giving the agent the right context, tools, feedback and checks as it works. That can include context, planning, tool use, testing, feedback loops, memory, safety controls, visibility into what happened, and a clear path from a code change to shipped work.

I like think about the harness as two layers: an inner harness and an outer harness.

The inner harness

The inner harness is provided by your agentic tool of choice, whether that be Claude Code, Codex, Kiro, Copilot or whatever else you're using.

Most of this is effectively a black box from the engineer's perspective. It sits between us and the model, communicating with it, managing context and providing tools that allow the model to inspect files, run commands and take actions on the local environment.

There is a huge amount of capability in this layer, but there is also only so much control we have over it, and that is where the outer harness becomes cruical.

The outer harness

The outer harness is what we add around that environment as engineers and teams.

Its purpose is to make the inner harness work more reliably and consistently within our environment. For how I work this includes conventions, standards, architectures, decisions, workflows and constraints.

At its simplest, that might be just an AGENTS.md file (although this is not effective).

At the other end it might include skills, hooks, evals, specifications and a context registry containing standards, patterns, conventions and workflows.

This layer has become increasingly important to how I get the most out of coding agents.

A powerful model can behave cleverly without behaving consistently.

I don't need to teach a frontier model what clean architecture is. It already has broad knowledge of common architectural approaches and software-engineering patterns. The harder problem is getting it to apply the right ones, at the right time, in the context of the system it is actually modifying. Without enough direction, I have seen even very capable models happily add another 100 lines of code to a 5,000-line file.

The change can be functionally correct, but functionally correct is not necessarily the same as correct for the codebase. The model has completed the task, while quietly adding to an architectural or maintainability debt that somebody else will eventually have to repay.

That is one of the jobs of the outer harness, not to make the model more knowledgeable (an easy slip-up), but to make its existing capability fit the environment in which it is working.

Specs are part of the harness

A key part of my outer harness is the process around specifications (SDD).

Get the spec roughly right (right-sized and directionally correct) and the model generally has a much better chance of producing the work you actually wanted.

That is why specification frameworks such as OpenSpec and my own OpalSpec, combined with an appropriate level of human oversight for the work being attempted, have become valuable parts of the workflow.

They give the agent a clearer definition of correct.

However, I found that a spec alone wasn't enough. Skills and a context registry help ensure that specs themselves are written with the right conventions and architectural context. That is already a significant improvement.

Hooks add another layer. They allow us to intervene while the agent is working, whether it is producing the specification or implementing the code. That turns the harness from something that simply provides information at the beginning into something that can guide behaviour throughout the task.

Some artefacts are for agents. Others need to be for humans.

One of my hooks instructs the agent, after it has produced a design.md, to ask whether I want a /human folder created within the spec.

There is a reason for that... Specs can be verbose.

For me, that makes sense, because their primary purpose is to give the agent (or in most cases another agent, e.g Opus specs, Sonnet builds) enough information to build effectively. Optimising every document for human readability can actually make it less useful to the agent doing the implementation.

However, there are points where human understanding matters more.

For a sufficiently complex change, I want a concise human-readable view of how the requirement will be implemented, how the architecture will change, where the complexity sits and what important decisions have been made.

I also increasingly apply the same idea to reviews. I run more pre-flight reviews today than i used to, this is through another agent before implementation begins. I do this now even on relatively straightforward work, it's relatively fast and a second agent can highlight gotchas, questionable assumptions or ineffective design choices that both the original agent and the human might otherwise miss.

The critique produced by a frontier model can be detailed and technically dense. As an experienced engineer I can work through it, but for higher-complexity changes I still find value in generating a human-oriented version before diving into all of the detail.

So the principle is simple:

Write for the agent when the agent needs precision. Write for the human when the human needs judgement.

Those are not always the same document.

Human judgement is part of the harness

This leads to what I think is the more important point.

The harness isn't only software. Effective human judgement over a specification, and questioning the model when it makes design decisions, challenging assumptions and deciding whether the proposed work actually belongs in the system is also part of the harness.

The harness extends into how we work. This matters because even with specifications, skills and good contextual information, models do not produce the right result every time. Often I will use a frontier model for specification work and a more cost-optimised model for implementation. The implementation model has the design, and it has the task list, it has the skills, and it has the context registry... yet it can still produce code that isn't "right" from the human perspective on the first attempt.

That doesn't necessarily mean the model failed - it means we need a system designed around the fact that first-pass generation is not the same as engineering correctness.

A good harness makes the wrong thing easier to detect

This is where hooks and automated fitness checks become particularly valuable.

Type checking and linting are the obvious examples, but the same idea can extend into architectural fitness controls and other checks specific to the system.

One of the checks I find particularly valuable is what I think of as a pragmatism check.

Most engineering checks ask some variation of:

Is this code correct?

The pragmatism check asks a different question:

Should this code exist at all?

• Has the model introduced a speculative abstraction?
• A helper that is only used once?
• Configuration nobody asked for?
• Defensive code for states that cannot actually occur?
• Functionality beyond the specification?

In my experience, models are particularly prone to this kind of unnecessary addition. They can produce solutions that are technically reasonable in isolation but larger, more abstract or more defensive than the problem requires.

We have options - we can correct that after the fact, or we can make it part of the harness. A hook can inject that instruction at specific checkpoints in the task, forcing the agent to reconsider what it has created before moving on. That doesn't guarantee the model will get everything right, but it does something more useful, it makes "wrong" easier to detect, challenge and correct before it becomes part of the system.

The harness is the engineering environment

That is increasingly what the harness is. It isn't just the software wrapped around a model, and it isn't a collection of prompt files, hooks or agent skills. It is the engineering environment we build around the model so that capability turns into repeatable, appropriate outcomes.

The model brings an extraordinary amount of knowledge and execution capability. The harness brings context, constraints, feedback, checks and the points at which human judgement needs to take over.

AI-native engineering is therefore not simply about putting a more capable model into the development lifecycle and asking it to write more code. It is about designing the conditions in which that capability can be trusted to produce work that actually belongs in the system.

The better the harness, the less we have to depend on prompt heroics or hope that the model makes the right decision by itself.

And perhaps that is the useful test of a harness, not whether it makes the agent look more capable, but whether it makes good engineering more repeatable.