Agent harnesses need maps, not more manuals

We keep trying to build agents that rewrite their own harnesses — the scaffolding of skills, tools, and routing logic wrapped around the model. The part that looks hard is generating the edit. A paper out this month says that is the wrong part to worry about.

"Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable" (Ruhan Wang and colleagues, arXiv 2607.13285, July 14) builds a behavior-to-source map straight from a harness codebase — static analysis plus LLM structuring — that links each behavior to the code that produces it. Then a step called Behavior-Guided Progressive Disclosure walks an agent from a high-level behavior down to candidate implementation sites, and verifies each candidate against the current source before anything is edited. Across modification requests on two open-source harnesses, planning with the handbook improved where-to-edit accuracy and edit-plan quality while spending fewer planner tokens. The largest gains were on scattered sites, rarely-run paths, and cross-module behavior.

Read the consensus way, this is "nicer tooling for self-improving agents." Read it the way that bites: the agent was failing at localization before it ever failed at generation. It knew how to write the fix. It did not know which of forty files owned the thing it was fixing.

That lands close to home, and I have to correct my own reflex out loud. My instinct — and I'd bet most teams' — has been to make agents more reliable by stuffing the manual: a fatter CLAUDE.md, more skill descriptions, more "when you see X, do Y." The Harness Handbook does the opposite. It adds almost no instructions. It adds a map, and it makes every claim in that map provable against source before an edit lands. Documentation for an agent, it turns out, is not prose you write. It is a navigable, source-verified index you regenerate — a build artifact, not a file you lovingly hand-maintain.

Here is the rule I am taking from it, and it is the thing the paper does not say. Instruction context depreciates as models get better; navigational context appreciates as your codebase gets bigger. A smarter model needs fewer "do it like this" rules — it already knows. But no model, however capable, can know that your rate-limiter lives across three files and one of them is a decorator nobody remembers. We keep adding navigational facts as if they were instructions, and instructions as if they were permanent — which is exactly why CLAUDE.md files bloat into swamps nobody can read.

I felt this one directly. At Trigent we wired a self-editing agent into a client's support-automation stack — a dozen skill files, the usual accretion. Ask "which file owns the escalation-to-human behavior?" and the honest answer was grep plus two engineers' memory. It went fine until the agent confidently edited the file that looked like it owned retries and did not — a plausible, well-named, wrong location. The change passed review because it read correctly in isolation, then broke a rarely-hit timeout path in production a week later. That is precisely the failure the verify-against-source step is built to kill: not a bad edit, a correctly-written edit in the wrong place.

So the implication if you run a production agent stack: before you add one more line to your instructions file, ask whether the reliability you want is an instruction problem or a map problem. If your agents keep getting lost — "which skill owns this?", "where does this behavior actually live?" — no manual saves them.

The scar is cheap to avoid. Point an LLM at your harness this week and have it emit one artifact: behavior → the file, function, and line that produces it, each link confirmed to still exist. Not prose — a checked index. That single afternoon buys more edit safety than a month of instruction-tuning.

What's in it for you

I share these mid-experiment so you can skip the weekend I spent learning them. From this one:

• A faster diagnosis. Next time an agent edits the wrong file, suspect localization first — and stop hardening prompts that were never the problem.
• A checked map, not more docs. One regenerated artifact — behavior to file to line, verified against source — that catches wrong-location edits before your review does.
• A line to hold. "Navigational context appreciates, instruction context depreciates" is your argument for shrinking the CLAUDE.md instead of feeding it. Steal it, try it, and tell me where it breaks.

Stop writing your agents a longer manual and start handing them a verified map — localization is the failure, and a map you regenerate beats a manual you maintain.