The news. On July 14, 2026, the authors of Harness Handbook published a 29-page paper targeting a specific bottleneck in changing production agent harnesses: finding where a requested behavior is implemented across prompts, state management, tool invocation, and coordination code. It proposes Harness Handbook — a behavior-centric representation built from a harness codebase using static analysis and LLM-assisted structuring, with each behavior linked back to source locations — plus Behavior-Guided Progressive Disclosure, which progressively reveals details and verifies candidate locations against current source. The authors report improved behavior localization and edit-plan quality, evaluated on two open-source harnesses. In the paper's words: "Behavior localization is therefore a central bottleneck in harness evolution." Read the paper →
Your porch light flickers, and you have been asked to fix it. You could walk the building room by room, opening every wall panel you pass, and you would learn a great deal about the building — but the flicker is not in a room. It is in a circuit: a run of junction boxes threaded through several rooms, most of which look like every other box you have opened. What you needed was never a tour of the rooms; it was the diagram that says which boxes belong to that one light. A behavior-centric harness map is that diagram, for an agent harness: a lookup from one thing the agent does to the source locations that make it do it.
The reason a harness needs one is that a behavior has no home. The paper names the four places it hides: prompts, state management, tool invocation, and coordination code. Take "retry on timeout" as an illustration of those four — the paper describes the domains, not this example — and you can feel the spread: the prompt might mention trying again, the state object would carry the attempt count, the tool schema says what a timeout even looks like coming back, and the coordination code decides whether a retry is scheduled at all. That is 4 domains, and no single file owns the behavior — which is why the person asking for a one-line change is rarely asking for a one-file change. This is the everyday texture of why a harness fails in production: an edit that fixes the legs it found looks finished, ships, and the old behavior walks right through the leg nobody found.
| Approach | What you ask it | What comes back | What it misses |
|---|---|---|---|
| File-level code search | which files contain this string | a list of files, ranked by text match | any leg that implements the behavior without naming it |
| Behavior-centric map (Harness Handbook) | where does this behavior live | the source locations linked to that behavior | whatever the map was built too early to know |
| Map + BGPD | where does this behavior live, still | progressively, each re-checked against current source | less — verification is the point, at the cost of more steps |
Put rough numbers on it — the paper publishes no localization counts, so these are illustrative, chosen to show how the two approaches fail differently. Say the harness holds 40 source files, and "retry on timeout" genuinely lives in 4 of them. Run a text search for retry and suppose it hits 9 files: 3 are real legs, and 6 are logging lines and comments that merely say the word. The fourth leg is a deadline check in the coordination layer that never spells retry at all — so text search cannot rank it, at any threshold, because the string is not there. The search returns 9 files that are 33% correct and silently 1 leg short; the map is asked a different question and returns the 4. The gap is not that search is bad at ranking. It is that a name-matching tool cannot find code that declines to say the name.
So why is a map alone not the whole answer? Because a diagram of a building is only true until someone rewires a room, and a harness is rewired constantly. That is what BGPD is for: rather than handing the agent the entire map and hoping it is current, it discloses the details progressively and verifies each candidate location against the source as it is today — one leg at a time, in the metaphor. In electrician's terms, you trace one leg and put a probe on the box before you trust the line on the paper. The cost is honest — more steps, more checking, and a model in the loop naming what static analysis can only point at.
Two things this does not claim. It does not make the edit itself; localization ends where planning begins, and the paper's reported gains are in behavior localization and edit-plan quality rather than in shipped fixes. And its evidence is early — two open-source harnesses, with no headline number published, so the honest read is a promising direction rather than a settled result. What survives either way is the framing, and it is worth carrying into your own harness: the reason a "small" agent change keeps going wrong is that you are editing legs of a circuit you never traced.
Goes deeper in: AI Agents → The Agent Loop & State → The Anatomy of a Harness
Related explainers
- Omnigent — The agent meta-harness — the layer above: one control plane over many harnesses, rather than a map inside one
- HarnessBridge — Learned agent harness — the other direction: learn the harness instead of documenting it
- Crafter — Multi-agent refinement harness with a directive critic — once you know where to edit, what tells you the edit was good
- AWS — Tool design as context engineering — the same progressive-disclosure instinct, applied to what a tool shows the model