Harness engineering vs loop engineering

Two terms have taken over agent design conversations in 2026, and most teams use them interchangeably. They are not interchangeable. They describe different halves of a production agent, they fail in different ways, and — this is the part that costs teams weeks — they produce almost identical symptoms when they break.

An agent that loops forever and an agent that cannot stop looping look the same from the outside. One is a loop bug. One is a harness bug. Fixing the wrong one is how a two-day debug becomes a two-week rewrite.

Key takeaways

• Loop engineering designs behaviour: what the agent does each iteration, and when it stops.
• Harness engineering designs environment: what the agent can touch, and what happens when a tool fails.
• The clearest test: if you can fix it by changing a prompt or a stopping condition, it is the loop. If you need to change what the agent is able to do, it is the harness.
• The two terms come from different communities three months apart and were never designed as a pair. That is why their definitions overlap and why published build-order advice contradicts itself.
• Loop design drives token cost far more than harness design. An unbounded loop is the single most expensive mistake in agentic AI.

Where did these two terms actually come from?

Most explainers present harness and loop engineering as two neat halves of one taxonomy. They are not. They are two separate coinages, from two separate communities, roughly three months apart — and understanding that explains almost every inconsistency you will hit.

Harness engineering came from the platform and infrastructure side. LangChain’s Vivek Trivedy published The anatomy of an agent harness on 10 March 2026, defining a harness as every piece of code, configuration and execution logic that is not the model, and using the formula Agent = Model + Harness. Thoughtworks’ Birgitta Böckeler extended it in a guide on martinfowler.com on 2 April 2026, developing an earlier February memo and crediting LangChain for the formula. Attribution is genuinely contested — a number of secondary write-ups credit HashiCorp co-founder Mitchell Hashimoto with popularising it in February 2026. For a term this influential, nobody can quite agree who said it first, which tells you how new it is.

Loop engineering came from the coding-agent practitioner side. Its ancestor is Geoffrey Huntley’s 2025 “Ralph Wiggum” technique — a bash loop that simply re-runs an agent until the goal is met. Anthropic’s Boris Cherny, who leads Claude Code, and Peter Steinberger both argued publicly that you should stop prompting agents and start designing the systems that prompt them. Google Chrome’s Addy Osmani gave that idea a name in June 2026. Gergely Orosz surveyed the practice for The Pragmatic Engineer on 14 July 2026, collecting responses from around 210 developers — one had shipped 13 pull requests fixing flaky tests from a single loop. By May 2026, Claude Code, Codex and Hermes had all shipped /goal-style commands that turned the hand-rolled Ralph loop into a platform feature.

So: one term was coined by infrastructure people describing what they build, the other by practitioners describing what they stopped doing by hand. They were never reconciled. Keep that in mind for the two sections where they collide.

What is harness engineering?

The harness is everything around the model except the model itself. It is the runtime: the tool definitions the agent sees, the sandbox its code executes in, the permission gates on destructive actions, the state that survives between calls, and the way a tool failure gets described back to the model so it can recover.

The useful implication of Agent = Model + Harness is that the same model in two different harnesses is effectively two different products. Claude Code, Cursor and Codex run on largely the same frontier models. The gap between them is harness.

Harness work is ordinary software engineering, and it looks like it:

• Tool surface. Which tools exist, what they are named, how their descriptions are written. A badly described tool is a capability the agent will never use correctly.
• Execution environment. Sandboxing, filesystem scope, network access, resource limits.
• Permissions and approval gates. Which actions run freely, which need a human, which are refused outright.
• State and persistence. What survives a crash, a restart, or a context compaction — the role memory plays in agentic systems is a harness question before it is a model one.
• Error surfacing. Whether a failed tool call returns a structured message the model can reason about, or throws and kills the run.
• Observability. Traces, logs, token accounting — the ability to answer “what did it actually do?” See LLM observability and monitoring for what to instrument.

Böckeler’s framing is worth borrowing here: she splits harness controls into guides, which are feedforward rules that prevent a problem before generation, and sensors, which are feedback mechanisms that catch it afterwards. A linter config is a guide. A test suite the agent runs and reads is a sensor. Most teams over-invest in guides and under-invest in sensors, which is why their agents produce plausible code that nothing ever checks.

We covered this layer on its own in harness engineering: what it is and why it matters. The short version: harness quality sets the ceiling on what any loop can achieve.

What is loop engineering?

The loop is the cycle the agent runs to finish a task: plan, act, observe, decide whether to go again. Loop engineering is the design of that cycle — and above all, the design of its exit.

Osmani’s own definition is the one most people quote: loop engineering is replacing yourself as the person who prompts the agent, and designing the system that does it instead.

Loop design answers four questions:

1. What happens in one iteration? Reason then act, as in the ReAct pattern? Generate then critique? Plan once then execute many? Anthropic’s Claude Code team groups these into four types of agent loop.
2. What triggers the next one? A failed test, a critic’s verdict, a schedule, a human reply.
3. What counts as done? This is the question teams get wrong most often. “The report is good” is not a stopping condition. “The report has an executive summary, three sections, and two citations per section” is.
4. What happens on failure? Retry the same way, retry differently, backtrack, escalate, or stop.

The patterns themselves — ReAct, Reflexion, maker/checker, plan-execute-verify, circuit breakers — are a topic of their own, and we have gone through them in 10 loop engineering design patterns and traced their history in agentic loops explained.

Harness engineering vs loop engineering: The difference at a glance

	Harness engineering	Loop engineering
Designs	The environment	The behaviour
Core question	What is the agent able to do?	What does the agent do, and when does it stop?
Artifacts	Tool definitions, sandbox config, permission policy, state store	Stopping criteria, retry policy, verification steps, plan structure
Scope	The whole system, all agents	One task trajectory
Changes	Rarely, and deliberately	Often, per task type
Typical failure	Agent cannot do the thing at all	Agent does the thing forever, or stops too early
Owned by	Platform / infrastructure engineers	Whoever owns the task’s quality
Cost impact	Indirect but permanent	Direct and large
Lineage	LangChain, Thoughtworks, March–April 2026	Huntley → Osmani → Cherny, 2025–June 2026

Where do the two overlap?

At exactly one place: every action the loop wants to take has to pass through the harness.

That single junction explains most of the confusion. The loop decides to run the test suite; the harness decides whether a Bash tool exists, whether it is sandboxed, and what the agent sees when it exits non-zero. Both disciplines have a legitimate claim on the outcome.

Context compaction is the clearest case. What to summarise when history gets long is context engineering. When compaction fires is a loop decision. Whether compaction is even possible is a harness capability. One behaviour, three owners.

The practical consequence: you cannot design a stopping condition the harness has no way to evaluate. “Stop when the tests pass” requires a harness that can run tests and report structured results. Teams routinely write loop logic that assumes harness capabilities they have not built.

Which layer is your agent actually failing in?

This is the question the existing literature mostly skips, and it is the one that matters at 2am. Symptoms overlap heavily. Use what fixes it as the classifier, not what it looks like.

Symptom	Loop bug if…	Harness bug if…
Agent never finishes	No stopping condition, or one it cannot evaluate	It can’t observe the signal that would tell it to stop
Agent stops too early	Completion criteria too loose	Verification tool missing or silently failing
Same error, over and over	No retry differentiation — it retries identically	Tool error returns an opaque string it can’t act on
Wrong tool for the job	Plan step chose badly	Tool description is misleading, or the right tool isn’t exposed
Works once, fails on rerun	Loop assumes clean state	No state isolation between runs
Great in dev, fails in prod	—	Almost always harness: permissions, sandbox, timeouts
Burns tokens with no progress	Unbounded iterations, no circuit breaker	Context not compacting, so every turn re-sends everything
Destructive action slipped through	Loop never planned an approval step	No approval gate existed to catch it

The one-line test: if you can fix it by changing a prompt, a stopping condition, or a retry rule, it is the loop. If you have to change what the agent is able to do or able to see, it is the harness.

The rerun test: run the same task twice from a clean state. Same failure both times points at the harness — deterministic environment problems reproduce. Different failures point at the loop, because the model took a different path.

Three worked examples

“The agent says the tests pass, but they don’t.” Looks like a lying model. Check what the test tool returns on failure. If it returns exit code 0 with the failure in stderr, or truncates output above some length, the agent is reading a success signal that isn’t one. That is a harness bug, and no amount of prompt hardening fixes it. If the tool reports correctly and the agent stopped anyway, the completion criteria were loose — a loop bug.

“It fixed the bug, then broke something else, then fixed that, forever.” Looks like an unbounded loop, and teams usually respond by adding an iteration cap. The cap is a good idea, but the cause is often harness: the agent has no way to run the full suite, only the file it touched, so it genuinely cannot see the regression it is causing. Give it the whole suite and the loop terminates on its own.

“It works on my machine and fails in CI.” Almost never the loop. The model is the same; the trajectory differs because the environment differs. Missing credentials, a read-only filesystem, no network, a tighter timeout. Diagnose the harness first, and only look at the loop if the environments are genuinely identical.

Should you build the harness or the loop first?

Here the published advice openly disagrees, and the lineage above explains why.

MindStudio says build the loop first — prove the core behaviour works, then invest in the harness to make it deployable. Exemplar says the opposite for single-task agents: establish policies, boundaries and approval gates first.

Neither is wrong. They inherited opposite defaults from opposite communities. The loop-engineering lineage grew out of developers running agents on their own machines, where the harness already existed and the loop was the only thing left to build. The harness-engineering lineage grew out of platform teams shipping agents to other people, where nothing can run until the environment is safe.

The variable neither names is how long the agent runs unsupervised.

• A human reviews every action → build the loop first. The human is the harness. Approval gates, sandboxing and rollback are all being provided by a person watching the output. Spending a sprint on permission policy before you know the agent can do the task is wasted work.
• The agent runs unattended for minutes or hours → build the harness first. There is no human to catch the destructive action, and the cost of a missing guardrail is now unbounded. You need the sandbox before you need the clever retry logic.
• The agent runs continuously in production → build both together, because at that point every loop change has harness implications and vice versa.

Most teams start in the first category and quietly move to the second without revisiting the decision. That transition — the day you stop watching every run — is the moment harness debt becomes urgent.

How does each one affect cost?

Almost nobody writing on this covers cost, and it is where the two layers differ most sharply.

Loop design drives token spend directly. Cost is roughly iterations × context size per iteration, and the loop controls both. An agent with no iteration cap and a vague stopping condition can burn a hundred times what a bounded one does on the same task. The three loop controls that matter most for spend:

• A hard iteration cap, always. Not a suggestion — a limit.
• A no-progress detector, so an agent repeating itself gets stopped rather than funded.
• A verification step that is cheap. If checking costs as much as doing, the loop doubles your bill.

Harness design affects cost indirectly but structurally. A harness that returns 40,000 tokens of raw log for a failed test is charging you for every subsequent turn in that trajectory. Truncating tool output, compacting history, and returning structured errors instead of stack traces are harness decisions with a permanent effect on the bill.

The asymmetry is worth internalising: a bad loop produces a spike you notice. A bad harness produces a tax you pay forever.

Is loop engineering just part of harness engineering?

Honestly — it is defensible to say yes, and the primary sources are split on it.

LangChain’s anatomy piece treats the loop as part of the harness outright: orchestration logic, hooks and continuation all sit inside its component list, and loop design is never separated as its own concern. Databricks takes the same line. By strict containment they are right — the harness implements the loop, and the loop cannot do anything the harness does not permit.

The reason practitioners split them anyway is that they are different kinds of decision with different change rates. Harness decisions are infrastructure: made once, changed carefully, shared by every agent on the platform. Loop decisions are policy: tuned per task, changed often, owned by whoever cares about that task’s output. Collapsing them into one term loses that distinction, and the distinction is what tells you who fixes the bug.

Analytics Vidhya adds a third axis — graph engineering, making control flow explicit as nodes and edges — which quietly concedes the point. “The loop” is a spectrum from implicit to fully declared, not a single thing.

Treat the split as useful rather than true. It earns its keep as a diagnostic, which is exactly how the table above uses it.

Where do prompt and context engineering fit?

The four terms form a scope ladder, each one containing the last:

Layer	Controls	Scope
Prompt	What you say	One message
Context	What the model sees	One model call, whole window
Loop	How often it runs, in what order	One task trajectory
Harness	What it can do, and where	The whole system

Each emerged as the one before it hit diminishing returns. Prompt engineering mattered most when models were fragile instruction-followers. Context engineering took over when agents started making dozens of calls and the window became the bottleneck. Loop and harness engineering arrived when agents began running unsupervised for long stretches.

For most teams building agents today, prompt engineering has the lowest ceiling of the four. It is table stakes, not a differentiator.

Who owns each on a team?

On a team of five, the same people own both, and that is fine.

The split appears somewhere around fifteen to twenty engineers, and it appears along the change-rate line. The harness becomes platform work — one team owning the tool surface, the sandbox and the permission model for every agent in the company. Loop design stays with the teams that own individual tasks, because only they know what “done” means for their output.

There is a second loop worth naming here, and Böckeler calls it the steering loop: the human cycle of watching agent failures and hardening the harness so each one becomes structurally impossible to repeat. That loop is not the agent’s. It belongs to the platform team, and it is the mechanism by which harness quality compounds.

The failure mode to watch: a platform team that owns the harness but has no visibility into loop failures will optimise for safety and generality, and ship a harness nobody can build a good loop on. Keep the diagnosis table shared between both groups.

How to get started

1. Classify your last three agent failures using the table above. If most were harness, stop tuning prompts. If most were loop, stop adding tools.
2. Write down your stopping condition for one agent, and check whether the harness can actually evaluate it. This exercise fails more often than teams expect.
3. Add an iteration cap and a no-progress detector if you have neither. This is the highest-value hour of loop work available to most teams.
4. Check what a failed tool call returns. If it is a stack trace or a truncated string, fix that before touching anything else — it degrades every loop you will ever run.
5. Audit your sensors, not just your guides. Most teams have linting and conventions. Far fewer have something the agent runs that can tell it that it is wrong.
6. Decide which category you are in — supervised, unattended, or continuous — and use that to pick the build order, rather than following generic advice.

Both layers run through the LLM bootcamp — five days, 40 hours, in Seattle or live online. Four of its twelve modules sit on the harness side: stateful applications with LangGraph, the Model Context Protocol, evaluation, and observability. The loop shows up in that same LangGraph module, which makes state something you design rather than a side effect of the prompt, and again in the reference architectures and the multi-agent capstone you deploy and keep.

The two disciplines are one system. But when something breaks, you have to name the layer before you can fix it, and that naming is the whole practical value of keeping the terms apart.

Frequently asked questions

Is loop engineering the same as agent orchestration?

No, though they overlap. Orchestration usually refers to coordinating multiple agents or services; loop engineering is about the iteration cycle of a single agent, including single-agent loops with no orchestration at all. An orchestrator has loops inside it.

Can you have a harness without a loop?

Yes, and it is common. A single-shot tool-calling assistant has a harness — tools, permissions, error handling — and no meaningful loop. It calls a tool, returns an answer, and stops. Loops become necessary when the task needs verification or multiple attempts.

Which one causes more production incidents?

Harness gaps cause more severe incidents; loop bugs cause more frequent ones. A missing approval gate is a harness gap and can be unrecoverable. An agent that retries forever is a loop bug and is usually just expensive.

Does the model choice change the answer?

It changes the loop more than the harness. Stronger models need fewer iterations and less rigid verification, so loop design gets simpler as models improve. Harness requirements are largely model-independent — sandboxing and permissions are needed regardless of which model is inside.

Where does graph engineering fit?

Graph engineering makes control flow explicit as nodes and edges rather than leaving it implicit in a loop. Treat it as a more declarative form of loop engineering, not a separate fourth discipline — it answers the same question about what runs when, in a different notation.

Who coined “harness engineering”?

It is genuinely disputed. LangChain published the Agent = Model + Harness formula in March 2026 without crediting anyone, Thoughtworks credits LangChain, and several secondary sources credit Mitchell Hashimoto in February 2026. The term is new enough that its own provenance has not settled.