August 6, 2026 · Harness Engineering · Coding Agents · How-to · EN

Repository Harness Patterns: A Pattern Language for Reliable Coding Agents

Nine reusable repository harness patterns for routing coding agents, bounding work, preserving decisions, validating changes, recovering safely, and producing evidence-based handoffs.

Repository Harness Patterns: A Pattern Language for Reliable Coding Agents

A repository harness pattern is a reusable arrangement of instructions, workflow state, validation, and evidence that helps coding agents make correct local decisions repeatedly.

The point is not to produce more documentation. The point is to shape the repository so that the right action becomes discoverable before a risky decision, mechanically checkable after a change, and recoverable when a session stops halfway through.

This pattern language extends the harness-engineering workflow into nine composable building blocks. Use it when a team knows its agent workflow is unreliable but “write a better prompt” is too vague to guide the repair.

For the broader agent-first framing behind this workflow, OpenAI harness engineering explained maps environment design, intent specification, and feedback loops onto repository-level mechanisms that work with Codex, Claude Code, Cursor, and other agents.

How to read a harness pattern

Each pattern has five parts:

• Context: the situation in which the problem appears
• Problem: the repeated failure the pattern addresses
• Forces: why the obvious fix is incomplete or creates another problem
• Pattern: the durable arrangement to add
• Evidence: how to prove it works without relying on the corrected session

Patterns are not templates to install blindly. They are responses to observed pressure. A small repository may need only three. A multi-package system with migrations and release automation may need all nine.

If you are applying these patterns to a codebase that already has established docs, tests, and tool-specific instructions, use the existing-repository migration guide to introduce one verified slice at a time instead of copying the full pattern set at once.

Pattern 1: Repository router

Context: A repository has multiple packages, services, generators, or validation paths. A fresh agent sees many plausible entry points.

Problem: The agent spends time rediscovering structure or starts in the wrong subsystem.

Forces: A full architecture document is too slow to scan before every task. A short root file cannot explain every package. Directory trees become stale when they are copied into several places.

Pattern: Make root AGENTS.md a router. Map representative change types to authoritative starting points, scoped instructions, and focused validation. Link to deeper maps instead of duplicating them.

## Repository map
- API behavior → `services/api/AGENTS.md` → `make test-api`
- Web UI → `apps/web/AGENTS.md` → `npm run test:web`
- Database schema → `db/README.md` → `make migration-check`
- Generated clients → edit `schema/`, then run `make generate`

Evidence: Ask a fresh agent where it would begin four representative changes. It should identify the correct package, source file family, and first validation command before editing.

Use the five layers of coding-agent context to keep routing facts in the repository layer instead of repeating them in task prompts.

Pattern 2: Task envelope

Context: A human requests a change in natural language.

Problem: The agent must infer the outcome type, scope, constraints, acceptance criteria, and proof.

Forces: A one-line prompt is fast but ambiguous. A heavyweight specification costs more than a small change deserves. The task must stay readable enough that both agent and reviewer use it.

Pattern: Wrap each non-trivial task in a compact envelope:

## Outcome
Add retry visibility to the import job without changing retry policy.

## In scope
- expose attempt count in job status
- add focused API and UI tests

## Out of scope
- changing backoff values
- replacing the queue library

## Acceptance
- attempt count is visible while running and after failure
- existing job-status clients remain compatible

## Proof
- `make test-import-status`
- `npm run test -- job-status`

Scale the envelope with risk. A documentation fix may need one sentence and a lint command. A migration needs preconditions, rollback, and explicit human gates.

Evidence: Review the resulting diff against the envelope. Unrequested refactors, guessed acceptance criteria, and unexplained skipped checks indicate the boundary was not strong enough.

This is the operational version of the story packet described in the harness-engineering pillar.

Pattern 3: Authority boundary

Context: The agent has tools capable of editing, deleting, pushing, publishing, deploying, or mutating external systems.

Problem: Capability is mistaken for permission.

Forces: Asking approval for every file edit destroys autonomy. Broad autonomy without named stop conditions creates unacceptable risk. Different tasks need different boundaries.

Pattern: Separate actions into three explicit classes:

• Autonomous: safe, reversible actions inside the task scope
• Approval-gated: irreversible, public, account-sensitive, or high-blast-radius actions
• Forbidden: actions the workflow must never perform

For every approval-gated action, define a safe fallback artifact: patch, branch, draft, migration plan, command kit, or deployment preview.

Evidence: Give the agent a task whose highest-value final step crosses a gate. It should finish the safe artifact, identify the exact pending action, and stop without repeated permission prompts.

Authority confusion is the second class in the coding-agent failure-mode taxonomy. The durable repair is a boundary, not a generic warning to “be careful.”

Pattern 4: Source-of-truth map

Context: Source, generated output, compiled assets, copied manifests, fixtures, and external configuration coexist.

Problem: The agent edits a plausible downstream artifact instead of the source that controls it.

Forces: Generated files are useful to inspect and sometimes committed. Their headers may be missing. The generator command may live far from the output. A prose reminder cannot prove synchronization.

Pattern: For each derived artifact family, colocate or link four facts:

1. authoritative source
2. derived outputs
3. regeneration command
4. synchronization check

## API client contract
- Edit: `schema/openapi.yaml`
- Generated: `clients/python/`, `clients/typescript/`
- Regenerate: `make generate-clients`
- Verify: `git diff --exit-code -- clients/`

Add mechanical checks where possible. The repository should reject a stale generated diff even if an agent misses the prose.

Evidence: Request a behavior change visible in generated output. The agent should edit the source, regenerate, and report both source and derived diffs.

Pattern 5: Decision memory

Context: The code contains an unusual adapter, dependency, data shape, compatibility branch, or operational constraint.

Problem: A future agent treats intentional complexity as accidental and “simplifies” it away.

Forces: Comments explain local mechanics but rarely capture alternatives and reopening conditions. Pull-request discussion is hard to discover. Large architecture documents become archives rather than decision tools.

Pattern: Record the smallest decision that future work must preserve:

# Keep the v1 event adapter

Status: accepted
Scope: `events/legacy/`
Decision: keep the adapter until partner traffic reaches zero.
Why: three external consumers still send the v1 envelope.
Rejected: forced migration; dual writes.
Reopen when: 30 days of telemetry shows zero v1 events.

Link the record from the scoped instructions or architecture map that governs the affected path.

Evidence: Ask a fresh agent to refactor near the surprising code. It should discover the rationale and preserve the constraint unless the reopening condition is met.

Pattern 6: Validation contract

Context: The agent has changed code and must decide what “verified” means.

Problem: It runs a convenient command that can pass while the changed contract remains broken.

Forces: Full suites may be slow. Focused tests may miss integration behavior. Different changes carry different risk. “Run relevant tests” leaves proof selection implicit.

Pattern: Map change categories and claims to required evidence.

Validation commands belong near the code or workflow they validate. Task envelopes select from that map; agents should not invent a proof strategy from scratch every session.

Evidence: For each handoff claim, ask whether the cited command could pass while the claim is false. If yes, the contract needs another check.

The agent-readiness audit includes validation and handoff criteria for finding this gap systematically.

Pattern 7: Evidence handoff

Context: The agent finishes a task and returns control to a reviewer or another agent.

Problem: The handoff says what changed but not why it is correct, what was actually tested, or what remains uncertain.

Forces: Raw command logs are noisy. “All tests pass” is too vague. Reviewers need concise evidence without repeating the entire session.

Pattern: Return a structured evidence packet:

## Outcome
Attempt count is visible in the API and UI.

## Changed
- API status schema and serializer
- UI job-status component
- focused contract and component tests

## Evidence
- `make test-import-status` — 18 passed
- `npm run test -- job-status` — 12 passed
- `npm run build` — success

## Not run
- full end-to-end suite; unrelated and 45 minutes

## Residual risk
- old mobile client ignores the new optional field; compatibility preserved

State exact commands and results. Separate skipped checks from failures. Tie residual risk to the changed contract.

Evidence: A reviewer should be able to decide whether proof is sufficient without reconstructing the agent’s terminal history.

Pattern 8: Durable checkpoint

Context: Work spans context compaction, interruption, multiple sessions, or multiple agents.

Problem: The next session repeats exploration, revives disproven assumptions, or continues from stale state.

Forces: Chat history is transient. Detailed logs become expensive to read. A checkbox alone does not preserve the evidence behind a decision.

Pattern: Checkpoint the minimum state required to continue safely:

• intended outcome and current scope
• completed steps with evidence
• current repository and external state
• disproven hypotheses
• unresolved decisions and blockers
• exact next action and its prerequisites

Use versioned plans for durable repository work and workflow state for automation. Do not store secrets or ephemeral noise.

Evidence: Interrupt after a meaningful discovery and resume in a fresh session using only the repository and checkpoint. The new session should continue without repeating completed work or discarding a verified conclusion.

Pattern 9: Safe recovery protocol

Context: A workflow can be interrupted between an external mutation and the checkpoint that records success.

Problem: Retrying duplicates a release, deployment, migration, payment, notification, or remote write.

Forces: “Not marked complete” does not mean “did not happen.” Blind replay is unsafe. Manual recovery does not scale. Documentation cannot make a non-idempotent operation safe.

Pattern: Design recovery around observation and idempotency:

1. assign a stable operation identifier
2. record preconditions before mutation
3. probe external state after interruption
4. distinguish not-started, applied-not-checkpointed, and complete states
5. continue from observed state
6. make repeated recovery converge on the same result

Evidence: Inject failure at every mutation-to-checkpoint boundary. Reload state and invoke recovery twice. The final system should match one uninterrupted execution with no duplicate side effects.

This is the pattern where prose is least sufficient. If the invariant is mechanical, the harness must enforce it mechanically.

How the patterns compose

The patterns form a decision path rather than a pile of files:

1. The repository router finds the correct local surface.
2. The task envelope defines the requested outcome and proof.
3. The authority boundary determines which actions may proceed.
4. The source-of-truth map identifies what can be changed.
5. Decision memory preserves constraints that code alone cannot explain.
6. The validation contract selects evidence for the changed behavior.
7. The evidence handoff makes review possible without replaying the session.
8. A durable checkpoint preserves progress across interruption.
9. The safe recovery protocol prevents duplicate external effects.

A single artifact can participate in several patterns. Root AGENTS.md may route work and state durable authority boundaries. A story packet can serve as task envelope and select the validation contract. The important property is not the filename; it is that every risky decision has a discoverable controller and every completion claim has evidence.

Choose patterns from observed failures

Do not begin by installing all nine. Start with a recent costly session and name the first wrong decision.

Then repair the narrowest authoritative layer and test the original scenario in a clean session. The failure-mode taxonomy provides the incident-analysis method behind this selection process.

A minimal repository harness

For a small repository, a useful first version can remain lightweight:

AGENTS.md                 # router + durable authority boundaries
docs/architecture.md      # subsystem and source-of-truth map
docs/decisions/           # non-obvious accepted choices
docs/tasks/active/        # task envelopes and durable checkpoints
scripts/validate.sh       # executable validation contract
.github/pull_request_template.md  # evidence handoff prompts

The structure is less important than the links between it. Root instructions should point to scoped context. Task envelopes should name exact proof. Decision records should be discoverable from affected code. Validation should test the contract rather than merely execute a familiar command.

For a ready-made starting point, repository-harness provides templates and workflow scaffolding for Claude Code, Codex, Cursor, and other coding agents.

Adoption sequence

A safe adoption sequence is:

Week 1: Observe

Collect three to five agent sessions. Record the first wrong decision, repeated correction, scope expansion, validation escape, and resume failure. Do not add rules yet.

Week 2: Install one controller

Choose the dominant failure class and implement one pattern in the narrowest location. Add an executable detector if the repository can express the invariant mechanically.

Week 3: Test fresh sessions

Repeat representative tasks without corrective prompts. Measure whether agents discover the new controller before the risky decision.

Week 4: Compose

Add the adjacent pattern only if the first repair exposes a second bottleneck. A router often reveals missing source-of-truth maps. A task envelope often reveals weak validation contracts. Durable checkpoints often reveal unsafe recovery.

This sequence keeps the harness small enough to maintain and grounded in actual failures.

Pattern quality checklist

Before calling a harness pattern complete, ask:

• Does it prevent a named repeated failure?
• Is the controlling source discoverable before the risky decision?
• Is it stored where the fact becomes true and changes?
• Does it link instead of duplicating lower-level detail?
• Is authority explicit rather than implied?
• Can a mechanical check carry the invariant?
• Does the proof cover the changed contract?
• Can a fresh session succeed without replaying the correction?
• Can interrupted work resume from observed state?
• Is there an owner or trigger for updating stale guidance?

From documents to an operating system

A repository harness is not a folder of agent instructions. It is a small operating system for repository work: routing, boundaries, memory, proof, handoff, and recovery.

The pattern language makes that system inspectable. Teams can point to the missing controller instead of blaming an agent in general. They can add one durable repair, test it in a fresh session, and measure whether the next task avoids the same correction.

Start with the failure you paid for twice. Choose the smallest pattern that would have controlled the first wrong decision. Then make the repository—not the next prompt—carry the lesson.

Related pages

• How to Manage Multiple Coding Agents in One Repository — compose the patterns into a cross-tool coordination workflow
• OpenAI Harness Engineering Explained — the agent-first framing translated into repository practice
• Harness Engineering for Coding Agents
• Context Engineering for Coding Agents
• Coding-Agent Failure Modes
• The Five Layers of Coding-Agent Context
• Why Coding-Agent Prompts Fail
• How to Audit a Repository for Agent-Readiness
• AGENTS.md Template
• repository-harness on GitHub

FAQ

What is a repository harness pattern?

A repository harness pattern is a reusable arrangement of instructions, workflow state, validation, and evidence that helps coding agents make correct local decisions repeatedly. Each pattern names a recurring problem, the forces behind it, a durable repository-level solution, and a way to verify that the solution works in a fresh session.

How is a repository harness different from AGENTS.md?

AGENTS.md is one surface inside a repository harness. A complete harness also includes task envelopes, authority boundaries, source-of-truth maps, validation contracts, decision records, checkpoints, safe recovery rules, and evidence-based handoffs. AGENTS.md should route agents to those sources rather than contain every detail.

Which repository harness pattern should a team implement first?

Start with the smallest pattern that prevents the most frequent costly mistake. For many teams that is the task envelope, which defines outcome, scope, constraints, acceptance criteria, and validation. If agents regularly start in the wrong place, begin with the repository router instead.

Do these patterns depend on Claude Code, Codex, or Cursor?

No. The patterns are tool-agnostic because they live in repository files, executable checks, and workflow state. Tool-specific instruction files can act as adapters, while the authoritative maps, contracts, decisions, and validation commands remain shared.

How do you test whether a coding-agent harness pattern works?

Reproduce a representative task in a fresh session without replaying the human correction. Verify that the agent discovers the controlling source before the risky decision, stays within scope, runs the required proof, and reports evidence. A current session succeeding after correction is not sufficient.

Should every coding-agent failure create a new rule?

No. First classify the failure and repair the narrowest authoritative layer. One-task facts belong in the task envelope, package rules near the package, accepted tradeoffs in decision records, mechanical invariants in executable checks, and only durable cross-repository routing rules in root instructions.

How should teams measure repository harness quality?

Track fresh-session success, human corrections before the first edit, scope expansion, validation escapes, repeated failure classes, successful resume after interruption, duplicate side effects during recovery, and whether each handoff contains claim-to-proof evidence.