Structuring Agent Harnesses for Better Edits

Summary & Methodology Analysis

The Harness Handbook addresses the behavior localization bottleneck in agent systems by utilizing static program analysis and LLM-assisted behavioral structuring. This approach constructs a behavior-centric representation of the codebase, organized into a hierarchical L1 to L3 document tree that maps the System, Component, and Unit levels. By integrating a cross-stage state-register view, the system enables Behavior-Guided Progressive Disclosure, allowing agents to navigate from abstract behavioral goals to concrete code segments. Before committing any edits, the system verifies candidate locations against the current repository state to ensure accuracy, and it maintains synchronization by automatically updating only the affected sections of the handbook when repository diffs occur. The architecture relies on rigorous validation cycles to maintain the mapping between behavioral descriptions and code implementation. Performance evaluations demonstrate significant efficiency gains, with Codex win rates rising from 28.3 percent to 38.3 percent, and Terminus-2 win rates increasing from 26.7 percent to 45.6 percent. Token efficiency also improved, with a 12.7 percent decrease in token usage for Codex and an 8.6 percent decrease for Terminus-2. Despite these gains, the system operates under conservative constraints: any code that cannot be parsed or revalidated is excluded from the handbook until it can be refreshed. This approach prioritizes stability over aggressive guessing, ensuring the handbook remains a reliable source of truth during the development lifecycle.