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

How to Migrate an Existing Repository to a Coding-Agent Harness

A low-risk migration guide for turning an existing repository into a coding-agent harness with routing, bounded tasks, validation contracts, decision memory, evidence handoffs, and safe recovery.

How to Migrate an Existing Repository to a Coding-Agent Harness

A repository-harness migration turns an existing codebase into an environment where coding agents can find the right source, stay inside a bounded task, verify the changed contract, and return reviewable evidence.

It is not a rewrite. It is not a giant prompt. It is a staged change to the operating layer around the code.

The safest migration begins with one repeated failure, repairs the earliest wrong decision, and proves the repair in a clean agent session. That approach is slower than copying a folder of templates for an afternoon—and much faster than maintaining repository instructions nobody trusts.

This guide provides a practical migration sequence for an existing production repository. It builds on the repository harness pattern language and turns the broader OpenAI harness-engineering idea into a controlled rollout.

Why big-bang harness migrations fail

Teams often notice unreliable coding-agent work and respond by adding everything at once:

• a long AGENTS.md
• new architecture documentation
• task templates
• decision records
• validation scripts
• agent-specific rule files
• an orchestration layer

The repository gains files, but nobody can tell which mechanism changed behavior. Contradictions appear between old and new documentation. Agents receive more context without better authority. Maintainers stop trusting the instructions after the first stale command.

A migration should reduce uncertainty, not relocate it.

Use an incremental rule:

Migrate one decision path at a time: entry point, authority, task boundary, source of truth, proof, handoff, continuity.

Before migration: capture the current failure

Do not begin by asking, “Which harness files should we add?” Begin with, “Where does the agent first make a costly wrong decision?”

Choose one task that is frequent, expensive to review, or dangerous when wrong. Good migration candidates include:

• editing generated output instead of its source
• changing the right behavior in the wrong package
• expanding a small request into an unrelated refactor
• running a convenient test that does not cover the changed contract
• repeating a rejected architectural choice
• claiming completion without reproducible evidence
• retrying an interrupted deployment or migration unsafely

Record a small baseline:

## Representative task
Add one field to the public account API and update generated clients.

## First wrong decision
The agent edits the generated TypeScript client directly.

## Human corrections required
1. Point to the OpenAPI source.
2. Explain the generator command.
3. Ask for the synchronization check.

## Review cost
34 minutes and two patch revisions.

The baseline gives the migration a falsifiable target. “We added AGENTS.md” is not a result. “A fresh agent edited the OpenAPI source, regenerated both clients, and proved synchronization without correction” is.

If you need a broader inventory first, run the agent-readiness audit and select the highest-cost gap rather than fixing every failed criterion.

Step 1: create a concise repository router

The root instruction file should help a fresh agent answer four questions quickly:

1. What does this repository do?
2. Where does this kind of change begin?
3. Which source is authoritative?
4. What validation is universal?

A migration-ready root AGENTS.md might begin like this:

# Repository operating guide

## Purpose
This repository contains the account API, web client, and generated SDKs.

## Route work
- API contract → `schema/openapi.yaml` → `make generate-clients`
- API implementation → `services/account/AGENTS.md`
- Web account UI → `apps/web/AGENTS.md`
- Release workflow → `docs/releasing.md`

## Universal workflow
1. Read the nearest scoped instructions.
2. Confirm the controlling source before editing derived files.
3. Keep changes inside the task envelope.
4. Run the validation contract for the changed behavior.
5. Report commands, results, omissions, and residual risk.

## Authority
- Local reversible edits and tests: autonomous.
- Push, deploy, release, migration execution: approval-gated.
- Secrets and production data: forbidden.

Keep the root small. It should route, not duplicate every package README. The AGENTS.md template is a starting point, but remove sections the team cannot keep accurate.

Migration check

Give a fresh agent four hypothetical changes and ask where each should begin. If it cannot identify the subsystem, controlling source, and first check, improve the router before adding more mechanisms.

Step 2: add scoped instructions only at real boundaries

A monorepo rarely has one validation command or one source-of-truth model. Add scoped instructions where at least one of these changes:

• architecture or package ownership
• setup and supported commands
• source versus generated outputs
• safety or approval boundaries
• validation requirements

AGENTS.md
services/account/AGENTS.md
apps/web/AGENTS.md
schema/AGENTS.md

A scoped file should answer local decisions the root cannot answer safely. It should not repeat the same global rules.

For the generated-client failure, schema/AGENTS.md could state:

## API contract workflow
- Authoritative source: `openapi.yaml`
- Generated outputs: `../clients/typescript/`, `../clients/python/`
- Regenerate: `make generate-clients`
- Verify synchronization: `git diff --exit-code -- clients/` after a second generation
- Never patch generated clients directly.

This is a source-of-truth map attached to the path where the decision occurs.

Migration check

Ask the representative task again. The agent should cite the controlling source before proposing files to edit.

Step 3: standardize a task envelope

Repository context cannot decide the product outcome for a specific task. Put temporary intent in a task envelope:

## Outcome
Expose `preferred_name` in the public account API and generated clients.

## In scope
- OpenAPI schema
- account serializer
- generated TypeScript and Python clients
- focused contract tests

## Out of scope
- database schema changes
- UI changes
- renaming existing account fields

## Acceptance
- field is optional and backward compatible
- both clients expose the same nullable type
- existing API consumers remain valid

## Proof
- `make test-account-contract`
- `make generate-clients`
- `make check-generated`

## Authority
Local edits and tests are autonomous. Publishing packages requires approval.

The envelope prevents the repository guide from becoming a task backlog. It also makes review possible: compare the resulting diff and evidence with the declared outcome, scope, and acceptance.

Migration check

Inspect the diff for unrelated cleanup, inferred requirements, and unexplained omissions. Those are task-boundary failures, not style disagreements.

Step 4: convert commands into validation contracts

A list of test commands is not yet a validation contract. The migration must connect each changed claim to evidence capable of falsifying it.

For the representative API task, make test-account-contract can pass while generated clients remain stale. The synchronization check covers the missing claim.

Prefer stable repository commands over prose sequences:

validate-account-api:
	$(MAKE) test-account-contract
	$(MAKE) generate-clients
	$(MAKE) check-generated

The agent now selects a supported validation path instead of inventing proof during every session.

Migration check

For each handoff claim, ask: “Could this command pass while the claim is false?” Add the narrowest missing detector.

Step 5: preserve decisions that agents repeatedly rediscover

Do not migrate the entire architecture history. Capture only decisions whose absence causes recurring wrong turns.

# Keep `preferred_name` nullable

Status: accepted
Scope: account API and generated clients
Decision: the field remains nullable through v2 clients.
Why: older identity providers do not supply a preferred name.
Rejected: fallback to legal name; empty-string sentinel.
Reopen when: all supported providers guarantee the field.

Link the record from the scoped instruction governing that path. A decision file hidden in a large archive does not control behavior.

Use the five-layer context framework to separate durable repository decisions from temporary task details and session notes.

Migration check

Start a fresh refactor task near the unusual decision. The agent should discover and preserve the constraint without a human replaying the history.

Step 6: require an evidence handoff

The migration is incomplete if review still begins with “What exactly did you run?”

Adopt a compact handoff format:

## Outcome
`preferred_name` is exposed as an optional field in the API and both generated clients.

## Changed
- OpenAPI account schema
- account serializer
- TypeScript and Python generated clients
- focused contract coverage

## Evidence
- `make validate-account-api` — passed
- second generation produced no diff

## Not run
- full end-to-end browser suite; no UI behavior changed

## Residual risk
- one partner client still pins the previous generated package version

A reviewer can now inspect the important claims, evidence, omissions, and risk without reconstructing the session transcript.

Migration check

A reviewer who did not watch the agent session should be able to reproduce the proof and identify the remaining uncertainty.

Step 7: add continuity and recovery only when the workflow needs them

Short local tasks may not need durable checkpoints. Long tasks, multiple agents, deployments, releases, and migrations do.

Add a checkpoint when work can outlive a session:

## Current state
Schema and serializer changed. Generated clients not yet updated.

## Evidence
`make test-account-contract` passes.

## Next safe action
Run `make generate-clients`, then `make check-generated`.

## External side effects
None.

Add a recovery protocol when the next action may repeat a side effect:

Before retrying package publication:
1. Query the registry for the target version.
2. If it exists, verify checksum and continue from post-publish checks.
3. If absent, publish once with the recorded idempotency key.
4. Record the remote URL before updating local completion state.

Do not add ceremonial checkpoint files to every typo fix. Use the mechanism when interruption creates real uncertainty or replay risk.

Step 8: prove the migrated slice in a clean session

This is the gate between “files added” and “behavior improved.”

Start a new agent session with the original task. Do not include the prior corrections. Observe whether the repository causes the right decisions.

Score the result:

If the agent repeats the failure, diagnose the first wrong decision again:

• Did it fail to find the controller?
• Did two sources conflict?
• Was the rule too vague to choose an action?
• Did the validation run too late?
• Was the check incapable of detecting the failure?

The coding-agent failure taxonomy helps map the symptom to a narrower repair.

A four-phase rollout for the rest of the repository

After one workflow passes the clean-session gate, expand by pressure rather than directory count.

Phase 1: orientation and bounded execution

Migrate the root router, one scoped instruction boundary, one task envelope, and one authority policy. Target the most frequent class of work.

Exit criterion: a fresh agent starts correctly and stays inside scope.

Phase 2: source control and proof

Map generated outputs, schemas, copied manifests, migrations, and other source-of-truth traps. Turn important commands into validation contracts.

Exit criterion: changed claims have covering evidence and derived artifacts stay synchronized.

Phase 3: decisions and handoffs

Capture recurring non-obvious decisions and standardize evidence packets in pull requests or agent handoffs.

Exit criterion: review focuses on tradeoffs and risk instead of rediscovering context and test coverage.

Phase 4: continuity and safe recovery

Add durable checkpoints, state probes, and idempotent recovery to workflows with remote side effects or multi-session execution.

Exit criterion: interrupted work resumes from known state without duplicate mutation.

Tool-specific files should be adapters, not competing authorities

An existing team may use CLAUDE.md, Cursor rules, Copilot instructions, or another vendor-specific surface. Do not delete useful adapters during migration. Make them point toward shared authoritative mechanisms.

# CLAUDE.md
Follow root `AGENTS.md` for repository routing and authority boundaries.
Use the nearest scoped `AGENTS.md` for package commands and source-of-truth rules.
Return the evidence handoff defined in `.github/pull_request_template.md`.

The context-file comparison explains the scope and precedence differences among common formats. Shared context belongs in the repository layer; product-specific ergonomics can remain in thin adapters.

Migration anti-patterns

Copying templates without observing a failure

A template can supply vocabulary, but it cannot know which decisions are costly in your repository. Start from evidence and delete unused sections.

Putting every fact in root AGENTS.md

A huge root file lowers signal and creates stale duplication. Route to scoped, authoritative sources.

Documenting commands that do not work from a clean checkout

A command dependent on hidden shell state is not a durable validation contract. State setup preconditions or repair the command.

Treating more context as better context

Duplicated or conflicting context increases uncertainty. Prefer one authoritative source linked at the decision point.

Measuring output instead of behavior

File counts, prompt length, and agent-message count do not prove reliability. Measure first-wrong-decision rate, correction count, validation coverage, rework, and clean-session success.

Expanding before the representative slice passes

If the first workflow still needs human correction, adding the same structure to ten packages multiplies an unproven design.

Migration checklist

Before calling the first slice complete, confirm:

• one representative failure has a written baseline
• root instructions route work instead of duplicating local details
• scoped instructions exist only at meaningful boundaries
• the task envelope defines outcome, scope, acceptance, proof, and authority
• source and derived artifacts are explicitly mapped
• validation commands cover the changed claims
• recurring non-obvious decisions are discoverable near affected paths
• the handoff reports evidence, omissions, and residual risk
• interrupted or external workflows have state-aware recovery where needed
• a clean session completes the representative task with fewer corrections

Start with a working repository-harness scaffold

repository-harness provides reusable structures for repository instructions, task state, validation, decision memory, and agent handoffs. Use it as a scaffold, then adapt the mechanisms to the failures and boundaries of your own codebase.

Do not install every pattern on day one. Choose one representative task, apply the smallest useful slice, and keep only the parts that improve fresh-session behavior.

For the underlying components, continue with Repository Harness Patterns. For a system-wide diagnosis before migration, use How to Audit a Repository for Agent-Readiness.

FAQ

What is the safest way to migrate an existing repository to a coding-agent harness?

Start with one recurring, costly agent failure. Add the smallest repository controller that prevents its first wrong decision, add executable validation, and rerun the task in a clean session. Expand only after the first slice produces measurable improvement.

Do we need to rewrite our repository before adopting harness engineering?

No. A repository harness is an operating layer around the codebase, not an application rewrite. Most migrations begin with a concise root router, scoped instructions, a task template, validation commands, and an evidence handoff format.

Should AGENTS.md contain every repository rule?

No. Root AGENTS.md should route agents to authoritative sources, state global boundaries, and name universal validation entry points. Package-specific commands, architecture, and source-of-truth rules should live near the paths they govern.

How long does a first repository-harness migration take?

A useful first slice can usually be built in one week because it targets one representative workflow rather than the entire repository. The migration should then expand by observed failure class and subsystem risk.

How do we know the migration improved agent behavior?

Rerun a previously troublesome task in a fresh session without replaying human corrections. Measure orientation time, scope accuracy, correct source selection, validation coverage, review rework, and handoff completeness.

Can one repository harness support Claude Code, Codex, and Cursor?

Yes. Keep authoritative repository maps, decisions, validation contracts, and task state tool-independent. Use CLAUDE.md, Cursor rules, or other tool-specific files as thin adapters that point to the shared operating layer.

What should a team migrate after the first successful workflow?

Expand to the next highest-cost failure or highest-risk subsystem. Add scoped instructions, source-of-truth maps, stronger validation, checkpoints, or recovery protocols only where observed pressure justifies them.