October 22, 2026 · Harness Engineering · Coding Agents · How-to · EN

Harness Engineering for Coding Agents: The Operational Workflow

Harness engineering turns coding-agent work into a controlled loop: specify outcomes, ground decisions in repository authority, bound execution, verify claims, hand off evidence, and encode what the team learns.

Harness Engineering for Coding Agents: The Operational Workflow

Harness engineering for coding agents is the design of the repository workflow, tools, boundaries, feedback, state, and evidence that help an agent select the right work, execute it safely, verify the result, and hand it back for review.

It changes the unit of engineering. The model is still important, but the model is one component inside a larger operating system.

A capable coding agent can still fail when:

• the task does not say whether editing is authorized;
• two documents appear equally authoritative;
• the visible file is generated rather than editable;
• “run the tests” does not name a covering command;
• a long task loses state between sessions;
• two green branches violate a shared contract when integrated;
• a retry repeats an external side effect;
• the final summary claims success without reproducible evidence.

A repository harness reduces those failures before they reach review.

The short answer

A practical harness loop has eight stages:

1. Specify the outcome, scope, authority, acceptance criteria, and proof.
2. Ground the task in current repository sources of truth.
3. Plan around boundaries, dependencies, risk, and stop conditions.
4. Execute inside a bounded workspace with safe tools and explicit authority.
5. Checkpoint durable state when work must survive a session or failure.
6. Integrate dependent changes in contract order, not arrival order.
7. Verify and review one exact candidate against the claims it makes.
8. Learn by encoding repeated corrections into repository controls and retesting cleanly.

That loop is more durable than a clever prompt because it lives in versioned repository state and executable checks.

Harness engineering, context engineering, and orchestration

These terms overlap, but they are not interchangeable.

Context engineering is a foundation of the harness. It makes local authority discoverable and proof paths explicit.

Orchestration sits above or beside the harness. It can schedule one worker or fifty. It cannot make an ambiguous task safe. Parallelism amplifies the quality of the operating contract—for better or worse.

Stage 1: specify the work before delegating it

A topic is not a task contract.

“Add avatar upload” leaves the agent to invent product behavior, file scope, security policy, compatibility expectations, and proof. A useful task contract resolves the material choices the agent should not make alone.

## Outcome
A signed-in user can upload a JPEG or PNG avatar from profile settings.

## Authority
Repository changes are allowed. Production deployment is not allowed.

## In scope
- validate type and a 2 MB limit;
- resize to 200 × 200 before storage;
- preserve the existing profile response shape.

## Out of scope
- authentication changes;
- media-library redesign;
- production bucket configuration.

## Acceptance
- valid upload succeeds without a page reload;
- invalid type and oversize files fail with useful messages;
- existing profile clients remain compatible.

## Proof
- `npm test -- avatar`
- `npm run typecheck`
- `npm run build`

## Stop conditions
Stop and request a decision if the existing storage abstraction cannot enforce
both size and type before upload.

The task contract should scale with risk. A typo may need one sentence and a lint command. A migration or release workflow needs preconditions, identity, rollback, recovery, and explicit approval boundaries.

Stage 2: ground decisions in repository authority

The agent should not begin by searching for a convenient file. It should begin by identifying the controlling sources.

A small repository authority map might name:

AGENTS.md                  operating entry point and global boundaries
docs/ARCHITECTURE.md       subsystem map and dependency direction
docs/VALIDATION.md         change type → proof command
docs/decisions/            accepted tradeoffs and reopening conditions
api/openapi.yaml           API source of truth
src/generated/             derived output; never edit directly
.github/workflows/         CI and release execution

Grounding has three checks:

1. Discovery: can a fresh agent find the controlling source before editing?
2. Precedence: if sources disagree, which one wins?
3. Freshness: does the source still match code, scripts, and CI?

A correct document that no agent discovers is operationally missing. A detailed document that conflicts with current tests is worse than missing because it looks authoritative.

Use root instructions as a router, not as a documentation landfill. Put package-specific rules at the narrowest useful scope. Link to one source of truth instead of copying the same command into several files.

Stage 3: plan around dependencies, boundaries, and risk

Planning is not writing a longer to-do list. It is choosing work units that can be independently verified and safely integrated.

For one agent, the plan should identify:

• the first controlling source to inspect;
• editable and non-editable surfaces;
• acceptance criteria and covering checks;
• approval and stop boundaries;
• the earliest risky decision;
• the checkpoint required before an irreversible action.

For multiple agents, add:

• shared foundations that must stabilize first;
• producer-consumer dependencies;
• path or contract ownership;
• isolated workspaces;
• integration order;
• combined validation after merge.

The task-decomposition guide explains how to split work by outcome and dependency rather than by arbitrary file count. The multi-agent repository guide connects decomposition, worktree isolation, handoff, integration, CI, review, and conflict repair.

Stage 4: execute inside explicit authority

“Agent can edit the repo” is still too broad for high-risk work.

A harness should distinguish:

• autonomous actions: reversible, repository-local changes inside the agreed scope;
• approval-gated actions: public posts, production deploys, secrets, payments, destructive migrations, or broad remote writes;
• forbidden actions: credential disclosure, deleting evidence, bypassing required checks, or rewriting shared history without authorization.

The safe fallback should be useful. When a public action is gated, produce the reviewed artifact, patch, command kit, or release draft instead of stopping before the reversible work is complete.

Hard boundaries need hard controls. Prose can explain policy, but permissions, hooks, CI, sandboxing, branch protection, and isolated credentials enforce it.

Stage 5: checkpoint work that must survive interruption

Short tasks can end in one session. Long tasks need durable state.

A useful checkpoint contains:

## Baseline
Commit: 2e6c3f1

## Outcome
Move avatar storage behind the media service without changing the public API.

## Completed
- compatibility contract captured;
- media adapter implemented;
- focused tests pass.

## Remaining
- consumer migration;
- combined integration suite;
- rollback rehearsal.

## Changed contracts
- media service now owns image normalization.

## Evidence
- `npm test -- media-adapter` — 24 passed
- `npm run typecheck` — success

## Risks and omissions
- mobile-web flow not exercised;
- production migration not authorized.

## Next verifiable action
Run the consumer contract suite against commit 2e6c3f1 before editing clients.

A checkpoint is not a diary. It preserves the minimum state another clean session needs to resume without repeating exploration or inventing progress.

For a reusable structure, use the coding-agent handoff template.

Stage 6: integrate by contract order

Two branches can be individually green and jointly wrong.

Integration should follow dependency order:

1. stabilize the shared contract;
2. integrate the producer;
3. regenerate or update derived consumers;
4. integrate dependent behavior;
5. run boundary checks;
6. validate one exact combined candidate.

Do not treat “mergeable” as “correct.” Git can combine files while the result violates API compatibility, schema order, generated-output freshness, migration sequencing, or authority boundaries.

Classify conflicts before resolving them:

Use the dependency-aware integration workflow and the merge-conflict runbook for the detailed repair process.

Stage 7: verify claims on one exact candidate

A strong harness maps every important completion claim to evidence.

Verification should be progressive:

1. run the fastest focused check while editing;
2. run subsystem checks before handoff;
3. integrate and test the combined candidate;
4. run release-only or destructive checks only at the appropriate gate.

The CI gates for multiple coding agents guide shows how to separate worker proof, producer-consumer proof, candidate identity, and release-specific risks.

Independent verification matters

The agent that made the change may carry assumptions from its own recovery path. A reviewer or clean environment should rerun the critical proof from the stated baseline.

Record:

• exact command;
• exact candidate identity;
• result summary;
• checks not run;
• environment-specific assumptions;
• residual risk.

“Tests pass” is not enough when the reviewer cannot reproduce which tests passed against which candidate.

Stage 8: review evidence, then improve the harness

Human review should begin with the claim graph:

• What outcome does the change claim?
• Which contracts changed?
• Which evidence covers each claim?
• What was intentionally not checked?
• What residual risk remains?
• Did the change stay inside authority and scope?

Only then should review descend into individual diff lines.

The claim-first code-review guide provides a full workflow for challenging evidence, checking seams, and independently verifying the candidate.

When review uncovers a repeated failure, do not stop at correcting the current diff. Trace the first wrong decision and improve the environment.

symptom
  ↓
first wrong decision
  ↓
missing or misleading controller
  ↓
smallest durable repository repair
  ↓
executable detector
  ↓
clean-session rerun

Examples:

• agent edited a generated client → name the source, generator, and dirty-tree check;
• agent crossed a package boundary → add a scoped authority rule and architecture test;
• agent claimed completion without integration proof → add the required candidate gate;
• agent retried an external mutation twice → add idempotency identity and recovery reconciliation;
• agent reopened a settled tradeoff → add a decision record with a reopening condition.

The harness improves only when the next fresh session behaves differently.

Recovery is part of correctness

Forward success does not prove safe recovery.

Any workflow that mutates external state, releases artifacts, updates managed files, or spans sessions should answer:

1. What durable fact proves whether the mutation happened?
2. What state is written before and after the mutation?
3. Can the next invocation reconcile reality with the checkpoint?
4. Is retry idempotent or deduplicated?
5. Can abort distinguish staged work from committed work?
6. Does recovery converge without duplicating side effects?

Test the dangerous boundaries by injecting failures:

prepare → checkpoint → mutate → checkpoint → verify → finalize
             ↑           ↑          ↑
          fail here   fail here   fail here

After each injected failure, reload persisted state and run recovery again. The test passes only when the workflow can determine what happened and continue safely.

This is where a repository harness becomes more than instructions. Critical operating rules become state machines, checks, and reproducible evidence.

What a minimum viable harness contains

A useful first version can be small:

repository/
├── AGENTS.md                    # operating router and authority boundaries
├── docs/
│   ├── ARCHITECTURE.md          # repository and source-of-truth map
│   ├── VALIDATION.md            # change category → proof command
│   ├── decisions/               # accepted choices and reopening conditions
│   └── tasks/active/            # durable state only for long-running work
├── scripts/
│   ├── verify.sh                # supported aggregate validation entry point
│   └── smoke-install.sh         # behavior-level proof where relevant
└── .github/
    └── pull_request_template.md # evidence handoff

The filenames are examples. The required properties are:

• one discoverable entry point;
• one source of truth per important decision;
• scope and authority before mutation;
• exact proof for common change types;
• durable state for work that must survive interruption;
• an evidence handoff another person can reproduce;
• a feedback loop from repeated failure to repository repair.

Do not install empty process for hypothetical failures. Add mechanisms when a real task, risk, or repeated correction justifies them.

What repository-harness provides—and what it does not

repository-harness is an open-source implementation of a small repository protocol and a safe updater.

Its current core is intentionally bounded. It provides a compact AGENTS.md entry point, repository navigation, optional locations and templates for durable plans and decisions, explicit-only discovery and improvement skills, and maintenance commands for status, health checks, dry-run updates, conflict staging, continuation, and abort.

It does not install application architecture, product policy, validation commands, credentials, schemas, a task database, an agent orchestrator, or an application runtime. The consumer repository remains the system of record.

That boundary matters. A generic installer cannot truthfully invent the commands, contracts, and acceptance criteria that belong to your application. It can install a protocol for discovering and maintaining them.

For the adjacent build-time decision, see repository harness vs app template: application scaffolds choose initial code and dependencies, while a harness governs how work proceeds after the repository becomes real.

Use the repository-harness project page for the current install and maintenance flow, or follow the brownfield migration guide for a staged adoption path.

Measure outcomes, not instruction volume

Do not use the number of instruction lines, documents, agents, or generated tokens as the success metric.

Leading indicators

• time to identify the correct subsystem and source of truth;
• human corrections before the first edit;
• percentage of tasks with explicit authority and acceptance criteria;
• percentage of claims mapped to exact proof;
• time from failed check to useful diagnosis;
• percentage of long tasks with resumable checkpoints.

Outcome indicators

• fresh-session success rate;
• scope leakage per task;
• validation escapes found during review or after merge;
• review time per accepted change;
• successful resume rate after interruption;
• duplicate side effects during recovery;
• recurrence rate of previously repaired failure classes.

The strongest unit of progress is a prevented repeat:

A failure occurred, the repository captured the missing controller and detector, and the next clean session completed the same class of work without the human correction.

A 30-minute harness-engineering audit

Choose one recent coding-agent change and answer:

Intent and authority

• Was the requested outcome explicit?
• Did the task distinguish analysis from permission to edit?
• Were out-of-scope and approval-gated actions named?

Grounding

• Did the agent find the controlling source before editing?
• Was there one source of truth for generated or derived outputs?
• Did current code and CI agree with the written instructions?

Execution and state

• Did the agent stay inside the assigned boundary?
• Could the work resume from a durable checkpoint if interrupted?
• Were external mutations idempotent or recoverable?

Verification and review

• Did each material claim have covering evidence?
• Was one exact integrated candidate tested?
• Did the handoff name checks not run and residual risks?

Learning

• Can the first wrong decision be identified?
• Is the correction encoded at the narrowest authoritative layer?
• Is there an executable detector?
• Did a clean session prove the repair?

For a broader repository score, use How to Audit a Repository for Agent-Readiness.

Start with one expensive repeated failure

Do not redesign the whole software-development process at once.

Pick one failure that is repeated, costly, or risky. Find the first wrong decision. Add the smallest controller that would have changed that decision. Connect the controller to executable evidence. Then rerun the original class of task in a clean session.

That is the harness-engineering loop:

specify → ground → plan → execute → checkpoint → integrate → verify → review → learn

The result is not an agent that never fails. It is a repository that detects failures earlier, recovers more safely, and gets better after each useful correction.

Related pages

• Context Engineering for Coding Agents — make repository knowledge discoverable, scoped, authoritative, and verifiable
• OpenAI Harness Engineering Explained — translate the agent-first framing into vendor-independent repository mechanisms
• Repository Harness Patterns — nine reusable controllers for reliable agent work
• How to Migrate an Existing Repository to a Coding-Agent Harness — staged brownfield adoption
• How to Manage Multiple Coding Agents in One Repository — the full cross-tool operating sequence
• CI Gates for Multiple Coding Agents — prove worker, integration, and release claims
• Coding-Agent Handoff Template — preserve outcome, state, evidence, omissions, and risk
• repository-harness project page — evaluate the current implementation
• repository-harness on GitHub — inspect and adopt the open-source protocol

FAQ

What is harness engineering for coding agents?

Harness engineering for coding agents is the design of the repository workflow, tools, boundaries, feedback, state, and evidence that help an agent select the right work, execute it safely, verify the result, and hand it back for review.

How is harness engineering different from context engineering?

Context engineering makes the right local knowledge discoverable, scoped, authoritative, and verifiable. Harness engineering uses that context inside an operational loop that also covers task authority, execution boundaries, validation, checkpoints, integration, recovery, review, and durable learning.

Is harness engineering the same as multi-agent orchestration?

No. Orchestration schedules or coordinates workers. Harness engineering defines the operating contract around the work. A queue can launch many agents, but it cannot repair ambiguous intent, conflicting sources of truth, weak validation, unsafe recovery, or evidence-free handoffs.

What is the minimum viable coding-agent harness?

A useful minimum is one operating entry point, a bounded task contract, a repository map, explicit authority and safety boundaries, exact validation commands, and an evidence handoff. Add durable checkpoints and recovery controls when work spans sessions or mutates external state.

Does harness engineering remove human code review?

No. It makes review more efficient by presenting a bounded change with reproducible evidence, explicit omissions, and residual risks. Humans still decide product intent, approve high-impact actions, judge tradeoffs, and choose what ships.

How do you measure whether a coding-agent harness works?

Measure fresh-session success, time to the correct subsystem, corrections before the first edit, scope leakage, percentage of claims backed by proof, validation escapes, review time, resume success after interruption, and recurrence of previously repaired failure modes.

Where should a team start with harness engineering?

Choose one recent expensive or repeated agent failure. Identify its first wrong decision, add the smallest repository controller and executable detector that would have prevented it, then rerun the same class of task in a clean session without replaying the correction.