Here is a pattern that repeats in every organization running AI agents in production. Something stops working — a lease extraction pipeline starts missing clauses, a maintenance dispatcher routes tickets to the wrong vendor pool, a compliance check returns inconsistent verdicts. The team opens the agent code, finds a forest of files and functions, and spends two days figuring out which of them actually implements the broken behavior. Then they make the edit — which takes an afternoon.
The ratio is not unusual. The diagnosis takes five times longer than the fix. And a recent paper from Tencent and Indiana University finally names and formalizes this as the central bottleneck in agent development: behavior localization.
The Problem Has a Name
The paper — "Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable" (arXiv:2607.13285) — introduces a precise concept worth internalizing. A production agent harness is large, tightly coupled, and behaviorally distributed: a single observable behavior (say, "how the agent handles a timeout") may be implemented across a handful of functions, several files, and multiple execution stages, connected through shared state that is never visible in any one place.
The repository is organized by files and modules. A modification request describes a behavior. There is a gap between those two views — and closing that gap before you can even start the edit is what the paper calls behavior localization.
This is not a niche problem. The authors studied two open-source agent harnesses and found that the largest performance gains came on exactly the cases you would expect: changes involving scattered implementation sites, rarely executed code paths, and cross-module interactions. These are the kinds of changes real agent evolution requires — not isolated bug fixes in a single function, but adaptations to new APIs, new tools, new models, new requirements.
What Harness Handbook Actually Is
The solution is a new kind of documentation artifact — one that is generated automatically from the codebase and organized around what the harness does rather than where the code lives.
The representation has three levels, which the paper calls a progressive disclosure hierarchy:
The key constraint is that every L3 entry must resolve to a real location in the current source. If the code changes and an L3 locator no longer points to anything, that entry is frozen and excluded from localization until it is refreshed. The repository is always authoritative; the Handbook is a live index, not a stale comment.
The Handbook is built automatically using static program analysis to extract functions, call graphs, and source locations, then LLM-assisted behavioral structuring to map those implementation units onto execution stages. The construction pipeline has two modes: function-level granularity for harnesses where a reliable stage skeleton already exists, and file-level for those where the stage structure must be inferred from scratch.
Behavior-Guided Progressive Disclosure
The Handbook enables a workflow the paper calls BGPD — Behavior-Guided Progressive Disclosure. Instead of opening the repository and grep-ing for likely functions, a developer or coding agent starts at L1, descends to the relevant L2 stage, follows the links to L3 units, and verifies those units against the live code before planning any edit. The result is a set of source-grounded evidence: confirmed locations where the requested behavior is actually implemented.
The paper evaluated this against baseline planning (no Handbook access) on realistic modification requests across two open-source agent harnesses. Handbook-Assisted planning improved both behavior localization accuracy and edit-plan quality — while consuming fewer tokens at the planner. The cost of building and maintaining the Handbook is more than recovered by the reduction in iterative, exploratory searching.
The largest gains appeared exactly where you expect the problem to be worst: cross-module changes, rarely-executed paths, and behaviors implemented in several nonadjacent locations.
Why This Matters for Real Estate and PropTech
Production PropTech platforms are among the most complex harness environments in applied AI. A real estate agent system might coordinate a document extraction agent, a valuation agent, a compliance enforcer, a tenant communications agent, and a maintenance dispatcher — each with its own tools, state, and failure modes — across dozens of files and execution stages. When one of those stages needs to change because a CRM API updated, a new lease format appeared in the market, or a regulator changed a reporting requirement, the first challenge is always finding every place in the harness that touches that behavior.
This is precisely the scenario Harness Handbook addresses:
- Model swaps. When a cheaper or faster model replaces a current one, the harness needs to adapt — prompts, context windows, tool-call formats. Behavior localization tells you where those adaptations need to happen before you start editing.
- API evolution. A PropTech SaaS you integrate with changes its authentication scheme or response format. The behavior "call this external system and parse its response" may be distributed across an adapter layer, a retry policy, a schema validator, and an error recovery path — in four different files. The Handbook surfaces all four before the first edit.
- Regulatory changes. New AML, GDPR, or local tenancy-law requirements may touch verification flows, data-retention policies, logging behaviors, and output formatting — each in a different execution stage. Missing one is a compliance failure.
- Coding agent delegation. As teams increasingly delegate harness edits to coding agents like Claude Code, the quality of the behavior localization step directly determines whether the agent's edit plan covers all affected locations. A Handbook-equipped agent produces a more complete plan with fewer wasted searches.
The Connection to Self-Improving Harnesses
The Harness Handbook paper connects directly to a theme running through several recent developments we have tracked on this blog. The Self-Harness paper showed that agent harnesses can improve themselves from their own execution traces — proposing and validating edits automatically. Self-improving orchestration showed that meta-skill evolution is a practical alternative to model fine-tuning. Harness Handbook adds the prerequisite to both: before you can improve a harness, you need to find where the target behavior actually lives.
Together these three ideas describe a coherent development loop for production agent systems: observe failures and measure quality → localize the relevant behavior using the Handbook → propose targeted edits → validate against a held-out benchmark before shipping. The Handbook is not the loop itself; it is the navigation layer that makes the loop practical at scale.
The Honest Caveats
- Construction has a cost. Building a Handbook from a large codebase requires static analysis and LLM inference. The paper argues the cost is recovered through token savings at edit time, but it is real upfront investment — especially for function-level granularity on complex harnesses.
- The Handbook must be kept current. The resynchronization trigger on every non-empty diff means the Handbook needs maintenance. An out-of-date Handbook with frozen L3 entries gives incomplete localization results, which may be worse than no Handbook at all if developers trust it uncritically.
- Behavior localization is necessary but not sufficient. The paper improves the planning step — finding where to edit. The quality of the edit itself still depends on the model, the prompt, and the evaluation gate. A Handbook does not fix a bad agent or a broken eval.
- Only two open-source harnesses evaluated. The paper is rigorous within its scope but covers two harnesses; results may not generalize uniformly to all production configurations, especially those with proprietary tool layers or non-standard execution models.
Frequently Asked Questions
What is an agent harness? The system layer that wraps a foundation model and makes it act — prompt construction, tool definitions, state management, execution flow, error recovery, and coordination logic. Most agent failures originate in the harness rather than in the model itself.
What is behavior localization? The process of identifying every source code location that implements a behavior described in a modification request. Because a behavior may be distributed across multiple files, functions, and execution stages, this step is often the dominant cost in harness evolution.
How is Harness Handbook different from code search or repository indexing? Code search and repository indexing organize information around files and functions. Harness Handbook organizes it around what the harness does, linking each behavior to its implementation sites. A developer or coding agent can therefore identify the relevant behavior first and navigate directly to the corresponding code — rather than inferring the mapping from grep results.
Does this require access to the model's weights? No. Harness Handbook works on the code layer around the model, not the model itself. It applies to any harness regardless of which model is underneath.
The Takeaway
Production harness evolution has a hidden cost that compounds with every new model, every new API, every new requirement: the time spent not writing code, but finding the right place to write it. Harness Handbook is the first systematic proposal for making that navigation automatic and verifiable — organizing implementation knowledge around behavior rather than files, linking it to live source, and keeping it in sync with every diff.
For PropTech teams building on top of AI agents, the implication is practical: the quality of your harness documentation is not a nice-to-have. It is the bottleneck that decides how quickly your system can adapt and how safely your coding agents can evolve it. VSBD designs and ships production agentic systems for real estate platforms — including the observability, evaluation, and harness architecture that make evolution safe rather than expensive.