Harness Handbook: Making Evolving Agent Harnesses Readable,Navigable, and Editable

2026-07-14

AI Summary

This work addresses the challenge that AI agent codebases are often large, tightly coupled, and exhibit scattered behavioral logic, making it difficult to precisely locate relevant code during system evolution and creating a manual bottleneck in mapping behaviors to implementation. To overcome this, the paper introduces Harness Handbook—a behavior-centric, human-readable, navigable, and editable abstraction—combined with static analysis and large language models to automatically construct behavior-to-code mappings. It further proposes Behavior-Guided Progressive Disclosure (BGPD), a novel mechanism that enables efficient behavior localization and editing planning. Experiments on two open-source agent harnesses demonstrate that the approach significantly improves both behavior localization accuracy and edit plan quality, particularly in scenarios involving dispersed code, infrequent execution paths, and cross-module interactions, while also reducing token consumption during planning.

Abstract

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.

Problem

• behavior localization
• agent harness
• code modification
• software evolution
• AI agent

Innovation

• Harness Handbook
• Behavior Localization
• Behavior-Guided Progressive Disclosure
• Static Analysis
• LLM-assisted Code Structuring