Mapping Agent Behavior to Code with the Harness Handbook

The Problem: The Complexity of Agent Behavior

The actual behavior of an AI agent is determined less by model performance than by the harness that wraps the agent. For example, Codex consists of 2,267 files, over 34,000 functions, and 160,000 code connections. At this scale, file trees or search alone cannot reveal how the pieces of code work together to produce actual behavior.

The Solution: A Three-Level Behavior Map

The Harness Handbook structures behavior into three levels. L1 (System Overview) shows the overall flow of how a request passes through the system. L2 (Behavior Unit Overview) decomposes the system into coherent behavior units and records each one's responsibilities, inputs/outputs, and dependencies. L3 (Behavior Unit Detail) examines a specific behavior in depth, linking triggers, state changes, exception paths, and code evidence. For example, the behavior "confirm with user before deleting a file" spans multiple parts—permission policy, confirmation state recording, sandboxed execution—and L3 breaks this down into verifiable units.

Generation Method: Grounded in Code Facts

The generation process has three stages. First, static analysis extracts program facts—files, functions, call relationships, state reads/writes—to build a program graph. Second, this graph is reorganized around behavior, going through a propose-review loop to align steps and unit boundaries. Third, the converged map is rendered into a handbook. The key principle is "prose explains, facts anchor"—every claim is anchored to extracted program facts.

Three Uses

Understanding: Start with L1 and L2 to grasp the system's overall execution flow and the connections between behavior units, then check the detailed implementation in L3. Monitoring: Drill down to L3 to verify triggers, permission rules, state changes, and fallback paths one by one, and check that there are no bypass routes. Modification: Find behavior units, implementation links, and dependency paths to define the scope of change and use it as an editing plan for a coding agent.

Improved Coding Agent Performance

The planning phase (before editing) was compared between agents that consulted the Harness Handbook and those that did not. The test was run on two production harnesses, Terminus-2 and Codex, and evaluated by three judge models—GPT-5.5, Opus 4.8, and DeepSeek-V4-Pro—each independently. The results show that the Handbook helps agents locate the correct implementation sites and form appropriately scoped editing plans.