Harness Engineering: Building Systems Instead of Prompts

In the last article of this series I argued that the real lever isn't how you phrase a prompt, it's the context the agent has access to: what it knows, what it can touch, what boundaries it must respect.

But context that only lives in your head, or that you have to patch by hand every time something breaks, is fragile. It depends on you remembering. It depends on you being there.

That's where Harness Engineering comes in: not writing better prompts, not even writing better context files, but building the actual system that keeps that context alive, up to date, and stable — with or without you paying attention in the moment.

The moment I realized I'd built a harness without naming it

After writing the previous article, I started doing exactly what I described in it: every time a Coding Agent got something wrong, instead of just re-explaining it in the chat, I went and fixed the root cause — updated a rule in CLAUDE.md, edited a Skill, tightened a permission, added a check to a hook.

A few weeks of that, and I looked at what I actually had: a set of project instructions, a folder of Skills for the procedures I run often, a short list of MCP servers with specific permissions, hooks that run validations automatically, and a rule that nothing ships without me reviewing it first.

None of that was planned as "a system". It was just me fixing one problem at a time. But that's exactly what a harness is — it just usually gets built by accident before anyone names it on purpose.

A harness is not a prompt. It's an environment.

Think about the difference between telling someone what to do once, and giving them an environment where doing the right thing is the default.

A prompt is the first. It's a one-off instruction, valid for one conversation, gone the moment the session ends.

A harness is the second. It's the durable environment an agent operates in, session after session, that makes good behavior the path of least resistance instead of something you have to ask for every time.

Concretely, a harness for a Coding Agent is made of things that already have names in this ecosystem:

• Project instructions (CLAUDE.md, AGENTS.md) — the architecture, conventions, and constraints the agent should already know without being told.
• Skills — packaged procedures for things you'd otherwise have to re-explain every single time.
• MCP servers — the external tools and data sources the agent is allowed to reach, and nothing more.
• Hooks — automated checks that run regardless of whether the agent remembers to run them.
• Permissions — an explicit boundary of what the agent can do without asking, and what it can't do at all.
• Tests — the objective definition of "done" that doesn't depend on the agent's own judgment.
• Human review gates — the points where nothing moves forward until a person says so.

None of these pieces is new. What's new is treating them as one system instead of a pile of unrelated files you occasionally remember to update.

Instructions are the walls, not the whole building

A CLAUDE.md or AGENTS.md file is usually the first thing people write, and for good reason — it's the cheapest way to give an agent architecture, conventions, and boundaries in one place.

But instructions only work if the agent reads them, follows them, and nothing overrides them by accident. They're the walls of the building. They're not the plumbing, the wiring, or the alarm system.

Treating a good instructions file as "I'm done with context" is the same mistake as thinking a style guide alone prevents bad code. It helps. It doesn't enforce anything.

Skills: turning "I already explained this" into a reusable unit

Every senior engineer has a mental list of "how we do X here" that gets repeated to every new hire, every contractor, every well-meaning teammate who does it a different way once.

Skills are that list, made executable. Instead of re-explaining a procedure to an agent every session — how to run a migration safely, how to structure a PR description, how to validate a feature before calling it done — you write it once as a Skill, and the agent picks it up when it's relevant.

The failure mode here isn't having too few Skills. It's having Skills that overlap, that go stale, or that the agent can't reliably tell apart. A harness needs precision as much as it needs coverage.

MCPs and permissions: what the agent is actually allowed to touch

An agent with fifteen tools it might theoretically use is not more capable than one with five it reliably knows when to use. It's just harder to predict.

MCP servers define what external systems an agent can reach — a database, a ticketing system, a deploy pipeline. Permissions define exactly what it can do with them: read but not write, propose but not merge, run in a sandbox but never in production.

This is the part of the harness that has nothing to do with intelligence and everything to do with blast radius. A well-scoped agent with narrow permissions is safer and, counterintuitively, more useful than a maximally capable one with no boundaries — because you can actually trust its output without re-checking everything by hand.

Hooks and tests: the parts that don't rely on the agent remembering

Instructions and Skills describe what should happen. Hooks and tests are what actually guarantee it did.

A hook that runs the linter automatically after every change doesn't care whether the agent "remembered" to run it. A test suite that has to pass before something is marked done doesn't take the agent's word for it.

This is the difference between hoping the agent follows the rules and making it structurally difficult for it not to. Everything in a harness that you can turn from a written rule into an automated check should be, because written rules get skipped and automated checks don't.

Human review gates: staying in the loop on purpose

None of this is about removing yourself from the process. A harness that runs fully unsupervised isn't more mature, it's just riskier.

The rule I use is simple: the agent doesn't move to the next step until I've reviewed and approved the current one. Not because I don't trust the system I built, but because the whole point of building it was to make my review faster and more focused, not to make it disappear.

Conclusion

Context Engineering told you what an agent needs to know. Harness Engineering is what makes that knowledge durable — instructions, Skills, MCPs, hooks, permissions, tests, and human review gates working as one system instead of scattered fixes you apply one session at a time.

This is how I see it now: a harness is the equivalent of the controlled environment where you let an agent work. You don't get more trust by hoping the agent behaves well. You get it by designing an environment where behaving well is the only path available.

In the next article of this series I'll look at how these pieces actually connect to each other — The Orchestrator: CI/CD Thinking Applied to AI Agents — and why the way you sequence Refiner, Implementation, and Verification steps looks a lot more like a deployment pipeline than a chat conversation.

Until then, the question worth asking isn't:

Did the agent do what I asked?

It's:

If I hadn't been watching, would the system around it have caught it anyway?

If you're building something similar, I'd like to hear how your harness looks — feel free to reach out.