Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable
arXiv · HuggingFace · ▲199
Abstract (verbatim)
The capability of a modern AI agent depends not only on its foundation model but also on its harness, which constructs prompts, manages state, invokes tools, and coordinates execution. As models, APIs, environments, and requirements evolve, the harness must be continually modified. Before such a change can be made, a developer or coding agent must identify all code locations that implement the target behavior. This is difficult because production harnesses are large, tightly coupled, and behaviorally distributed, while modification requests describe what the system should do and repositories are organized by files and modules. Code search, repository indexing, and long-context processing ease inspection, but still leave this behavior-to-code mapping to be recovered by hand. Behavior localization is therefore a central bottleneck in harness evolution. We introduce the Harness Handbook, a behavior-centric representation synthesized automatically from a harness codebase via static analysis and LLM-assisted structuring, linking each behavior to its corresponding source. We also introduce Behavior-Guided Progressive Disclosure (BGPD), which guides agents from high-level behaviors to relevant implementation details and verifies candidate locations against the current source. On diverse modification requests from two open-source harnesses, Handbook-Assisted planning improves behavior localization and edit-plan quality while using fewer planner tokens, with the largest gains on scattered sites, rarely executed paths, and cross-module interactions. Evolving complex agentic systems thus depends not only on generating edits, but also on determining where those edits should be made.
Background
Background Analysis
1. Technical Context and Real-World Needs
Modern AI agents (e.g., tool-using assistants or automated systems) rely not only on foundational models but also on their "harness"—a control layer that coordinates prompts, state management, tool invocation, and execution across components. These systems are widely used for complex tasks like web interaction, code generation, or data manipulation. However, as models, APIs, or requirements evolve, harnesses must be continuously updated. The core challenge for developers is: how to quickly locate all relevant code implementations when modifying a feature (e.g., optimizing tool calls or fixing execution bugs)? Traditional methods, whether manual code review or agent-based search, are inefficient and error-prone in large, tightly coupled harnesses.
2. Limitations of Previous Approaches
Existing tools (e.g., code search, repository indexing, or long-context processing) simplify code navigation but fail to bridge the gap between "behavior" (e.g., "retry failed queries three times") and "implementation." Developers or agents must manually map behavioral requests to code, a process that is time-consuming and prone to oversight. For example, a simple behavior might span multiple functions or files, and agents, limited by context length, cannot analyze all code at once, leading to missed edge cases or cross-module interactions.
3. Proposed Solution
The paper introduces the "Harness Handbook," a behavior-centric representation that automatically links system behaviors to code implementations via static analysis and LLM-assisted structuring. For instance, it connects the behavior "handle user authentication" directly to the corresponding code. Additionally, "Behavior-Guided Progressive Disclosure (BGPD)" guides agents from high-level behaviors to implementation details step-by-step, verifying candidate code against the current version. This approach makes the "behavior→code" mapping explicit, reducing the cognitive load for both humans and agents.
4. Key Differences from Prior Work
Previous methods focused on improving codebase explorability (e.g., generating summaries or indexes) but did not address the direct association between behaviors and code. The paper’s breakthrough lies in:
- Focus Shift: From "how to organize code" to "how to organize behavior," enabling developers/agents to first understand the required system behavior before locating implementations.
- Automation: Behavior-code mappings are generated automatically via static analysis and LLMs, rather than manual annotation or static rules.
- Dynamic Validation: BGPD verifies code-behavior alignment during planning, avoiding outdated or incorrect suggestions.
Experiments show this approach significantly improves localization accuracy and edit-plan quality, especially for scattered logic or cross-module interactions.




