Ruhan Wang, working with a team based at Tencent’s HY LLM Frontier lab alongside researchers from Indiana University and three other universities, has published Harness Handbook, an open reference that restructures coding-agent codebases around behavior rather than file layout. The project targets a problem that grows more urgent as coding agents get real filesystem and shell access: confirming that an agent will actually ask before deleting a file requires tracing logic scattered across prompts, tool wrappers, permission configs, and sandbox execution code, not a single function.
The scale problem is concrete. The project’s own accounting of Codex, OpenAI’s coding-agent product, counts 2,267 files, more than 34,000 functions, and nearly 160,000 code connections. A keyword search for “delete” or “permission” returns fragments; reassembling them into one verifiable behavior chain is manual work that most teams skip.
Harness Handbook’s fix is a three-level structure. L1 gives a system-wide view of how a request flows through the harness. L2 breaks that flow into discrete behavior units with defined inputs, outputs, and dependencies. L3 opens a single unit in full: what triggers it, how state changes, what happens on failure, and which files and line ranges back each claim. The team calls the process of navigating from a plain-language question down to that evidence chain “Behavior-Guided Progressive Disclosure.”
Generation follows what the authors describe as a facts-first pipeline: static analysis extracts a program graph of files, functions, and call relationships; a proposer-reviewer loop maps that graph onto behavior stages; and a synthesis step renders the three-level document while keeping every explanation tied to a source citation. The stated goal is that no behavior description in the Handbook exists without a corresponding code reference.
To test whether the map actually helps, the team ran a coding agent built on NexAU, an agent framework, with DeepSeek-V4-Pro as the planning model, against Terminus-2 and Codex, with and without Handbook access before localization. Three models, GPT-5.5, Opus 4.8, and DeepSeek-V4-Pro, judged each comparison. The Handbook-assisted planner won more pairwise comparisons while spending fewer tokens per case, and recall, precision, and F1 against reference plans improved across most settings. Cases where the planner landed in the wrong subsystem entirely dropped. The gains held across easy, medium, and hard requests and across three request categories the team defines as query changes, cross-file additions, and search-hostile edits.
One detail in the evaluation setup is worth flagging. DeepSeek-V4-Pro serves as both the planner’s model and one of the three judges scoring the comparisons, and Opus 4.8 and GPT-5.5, the models that generated the reference plans used to score localization accuracy, are also two of the three judges. The published results do not describe any control for a model favoring outputs that resemble its own family’s reasoning style.
The team also built Handbook Studio, an interface for connecting a repository, generating the map, and proposing edits against it. In a worked example, a request to scope environment variables to a single Codex command expanded into 14 implementation sites across 10 files, including the shell execution path and its unified-exec counterpart plus mirrored test files. The system reportedly writes nothing to the repository or the Handbook itself until a human confirms the generated diff.
For any team building or auditing a coding agent that has been granted filesystem or shell permissions, this is a specific tool to test against your own permission logic before trusting a vendor’s safety documentation: run a targeted audit question, such as confirmation-before-delete, through both a plain code search and a behavior-mapped tool, and compare how completely each surfaces the actual execution path.
Ruhan Wang and collaborators published the Harness Handbook project page, hosted by Tencent’s HY LLM Frontier group, dated June 2026.
