Harness Engineering: Fixing Agent Failures at the Environment Layer

This long X article by the account LunarResearcher argues that when an AI agent fails, rewriting the prompt is usually the wrong fix. Its examples are failures of the surroundings rather than of reasoning: the agent did not know which files mattered, lost decisions from an earlier session, claimed success without running checks, or had permission for an action that should have needed approval. The author calls the software around the model the harness (everything that supplies context, runs tools, keeps state, checks results and enforces limits) and says designing it is becoming its own engineering discipline. The guide's own summary of the difference is that a prompt changes one attempt while a harness changes every attempt.

Most of the guide is a set of design rules that follow from one idea: anything that matters repeatedly should be enforced by code rather than remembered by the model. It recommends turning a vague request into a contract that states the outcome, the scope, what must not change, what evidence proves completion and which actions need human approval. Tools should sit behind a gateway that validates arguments, restricts paths and requires confirmation for risky actions. Completion should be decided by observable checks such as a compiler, a test or a query, with another model used only where the answer is ambiguous, and verification should be done by a separate reviewer whose job is to find reasons to reject the work. Retries should change something about the conditions, and every loop needs limits on attempts, time and spending, along with a defined point at which it escalates.

The guide also argues against building too much. It describes harness decay, where a workaround written for an older model can stop a newer one from using a better strategy, and tells readers to add a layer only when an observed failure calls for it and to keep simple prompts for short, cheap, easily checked tasks. It reports no experiments or numbers, so these are one practitioner's recommendations rather than tested results. Several sections refer to tables or diagrams that did not survive in the stored text, so some specifics, such as its proposed metric for accepted work, are not visible here.