Harness Handbook Improves AI Agent Harness Readability and Editability

The effectiveness of modern AI agents depends significantly on their "harnesses," which are the code structures responsible for prompt construction, state management, tool invocation, and execution coordination. As AI models and requirements evolve, these harnesses require continuous modification. However, identifying the specific code locations for desired behavioral changes is a major bottleneck due to the large, tightly coupled, and behaviorally distributed nature of production harnesses. To address this, the Harness Handbook proposes a behavior-centric representation automatically generated from a codebase using static analysis and LLM-assisted structuring. This handbook links specific behaviors to their corresponding source code. Complementing this, Behavior-Guided Progressive Disclosure (BGPD) helps developers and coding agents navigate from high-level behaviors to relevant implementation details, verifying candidate locations against the source. Experiments show that Handbook-Assisted planning significantly improves behavior localization and edit-plan quality, particularly for scattered, rarely executed, or cross-module interactions, while also reducing planner token usage. This highlights that successful agent evolution relies not just on generating edits, but crucially on efficiently identifying where those edits should be made.