Harness engineering: stability from the execution environment, not the prompt

Stability comes from the harness, not a cleverer prompt

When an agentic coding session goes wrong — the model edits the wrong file, hallucinates an API that does not exist, or makes a change that breaks ten things it did not know were connected — the instinct is to write a better prompt. That instinct is usually wrong. The underlying problem is almost never that the model misunderstood the instruction. It is that the execution environment gave the model too little information before it started acting and too little structure to channel its actions safely afterward.

Harness engineering is the discipline of building that execution environment: the scaffolding, gates, and conventions that sit around the model and make agentic coding reliable regardless of how complex the repository is. This sprint covers four pillars of harness engineering — repository impact maps, the plan-first protocol, worktree isolation, and the judgment-vs-determinism boundary — and shows how each maps directly onto the tools Claude Code provides: subagents, skills, plan mode, and git worktrees.

Pillar 1: Repository impact maps

Before any file is modified, the agent needs to know what it is about to touch and what depends on it. Without this knowledge, the model is navigating a large codebase by assumption — and assumptions about import paths, function signatures, and module boundaries are the primary source of hallucinated edits in agentic coding.

A repository impact map is a structured pre-flight that answers three questions before any edit is made: which files define the symbols the task touches, which other files call or import those symbols, and which tests cover that surface. The map is built deterministically — by grepping for definitions, tracing import graphs, and listing test files — before the model is given any write access. The model then reasons over this map rather than over its training-time assumptions about the codebase.

The practical effect is significant. When the model knows the exact paths and signatures of the functions it will change, it cannot hallucinate them. When it knows which callers exist, it cannot ignore a ripple effect. The impact map transforms the model's task from "infer the structure of this codebase" — which it will do imperfectly — to "reason about this concrete, verified map" — which it does well.

Pillar 2: The plan-first protocol

The most expensive mistakes in agentic coding happen early: the model makes an architectural decision in the first edit that constrains every subsequent edit, and by the time the problem is visible, a significant amount of work needs to be undone. The plan-first protocol prevents this by separating reasoning from action into an explicit two-phase sequence.

In the first phase, the agent produces a structured plan: the list of files to change, the specific modifications at each file, the order of changes, and the verification steps that will confirm each change is correct. No files are modified. The plan is written to a markdown document and presented for review.

In the second phase, the plan is approved — either by a human reviewer or by a gate that checks it against known constraints — and only then does the agent begin editing. If the plan is wrong, it costs a few seconds to revise. If the edit is wrong, it may cost hours to untangle.

Claude Code implements this pattern natively as plan mode: when activated, Claude reads, explores, and produces a plan but does not write any files until explicitly granted permission. This makes the plan-first protocol a first-class workflow in the tool rather than a discipline you have to enforce manually.

Pillar 3: Worktree isolation

Parallel agentic tasks — where multiple subagents work on independent parts of a codebase simultaneously — create a coordination hazard: if two agents modify the same files, one agent's changes will silently overwrite the other's, or a merge conflict will appear at integration time with no clean record of which change was intentional.

Worktree isolation eliminates this hazard by giving each parallel task its own git worktree: a full working tree checked out at the same commit, isolated from all other worktrees, where one agent can make and test changes without touching any other agent's work. When a task is complete and verified, its worktree is merged into the integration branch. Nothing is integrated before it is verified; nothing is verified in a shared state that another agent is also modifying.

Claude Code's subagents are the mechanism for parallel task execution. Each subagent can be launched with its own worktree, run to completion independently, and integrated after verification — a pattern that makes parallel agentic development safe at scale without requiring complex conflict resolution.

Pillar 4: Judgment vs. determinism

The fourth pillar is a boundary, not a tool. Every task in an agentic coding session can be classified as either requiring judgment — synthesis, design, interpretation, trade-off reasoning — or being fully deterministic — parsing, linting, running tests, grepping for symbols, computing checksums. The boundary matters because the model is the right executor for the first class and the wrong executor for the second.

When you ask a model to run a linter, it will simulate running a linter: it will produce output that looks like linter output, based on its training, and that output may be wrong. When you run the linter as a tool and feed the result back as an observation, the output is accurate by construction. The same applies to test runners, build systems, import graph tracers, and any other deterministic operation. As Anthropic's guidance on building effective agents frames it: the reliability and maintainability gains from a well-structured agentic system come from keeping the model in its lane — synthesis and judgment — while letting tools handle the deterministic work.

In Claude Code, this boundary is expressed through skills: reusable SKILL.md files that encode a process the agent follows, with tool calls embedded at the deterministic steps. A skill can specify "grep for all callers of this function" (deterministic — use Grep) and "decide which callers need to be updated given this change" (judgment — the model) as separate, explicit phases. The skill does not blur the boundary; it documents it.