# Your Agent Harness Needs a Behavior Map Canonical URL: https://huecki.com/en/blog/agent-harness-needs-a-behavior-map/ Markdown URL: https://huecki.com/en/blog/agent-harness-needs-a-behavior-map.md Language: English Published: 2026-07-17 Updated: 2026-07-17 Author: Dominic Hückmann Topic: AI Agent Workflows - Agent topics: Agent Harnesses, Context Engineering, Agent Evals - Tags: AI Agents, Agent Harness, Coding Agents, Developer Workflow, AI Engineering - Audience: agent builders, developers maintaining coding agents, small engineering teams, automation teams - Concepts: agent harnesses, behavior mapping, codebase navigation, workflow documentation Thesis: Agent harness changes should start from a behavior-to-code map, not from dumping more repository context into the coding agent. Content status: field-note ## Summary Harness Handbook points at a practical bottleneck in agent engineering: the behavior you want to change is scattered across prompts, state managers, tool calls, policy code, and tests. Build a behavior map before editing the harness. ## Description A practical workflow for maintaining agent harnesses: map behaviors to prompts, state, tools, policy, source files, and tests before asking a coding agent to edit the loop. ## Body ## Short answer The hardest part of changing an agent harness is often not the model. It is finding where the behavior actually lives. The paper [*Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable*](https://arxiv.org/abs/2607.13285) names a practical maintenance problem: agent behavior is distributed across prompt builders, state managers, tool schemas, execution loops, memory updates, policy checks, retries, and tests. So a request like "make the agent ask before editing production config" rarely maps to one file. It maps to a behavior. That behavior needs a map before it needs a patch. ## The mistake Most coding-agent workflows start too low: ```txt Here is the repo. Change how the agent handles risky actions. ``` That sounds reasonable, but harness code is not ordinary feature code. The behavior may be assembled at runtime. A prompt fragment names the rule. A state object carries the risk label. A tool wrapper hides the permission boundary. A controller loop retries after refusal. A test only checks the happy path. If the coding agent edits the first plausible file, the harness can get worse while the diff looks tidy. The better first artifact is a behavior map: ```txt behavior: asks before production writes prompt: where the rule is stated state: where impact class is stored tool: which calls can mutate production policy: where act / ask / abstain is decided loop: retry and escalation behavior tests: verifier cases that prove the rule ``` ## A workflow to steal Use this before editing any agent harness that has tools, memory, or permissions: The prompt is small: ```txt Before editing this agent harness, build a behavior map. For the requested behavior, return: 1. observable behavior in one sentence 2. prompt fragments involved 3. state fields read or written 4. tools and permissions involved 5. controller or policy branches involved 6. tests, evals, logs, or traces that prove the behavior 7. exact source files and symbols to edit 8. files that look related but should not be touched Then propose the smallest edit against verified locations only. ``` That last line matters. The map is not documentation theater. It is a scope control device. ## Weak vs. safer ## Where it fails A behavior map can lie by going stale. That is the main risk. Treat it like generated operational documentation, not timeless architecture prose. Every mapped claim should cite current source files, symbols, or tests. If the map cannot point to evidence, it is a guess. This is also not a reason to put every harness rule in prose. Code should still enforce permissions, schemas, sandboxes, logs, and irreversible action gates. The behavior map sits above that. It helps humans and agents find the right enforcement points. There is also an evidence boundary worth keeping explicit. The paper evaluates behavior localization and edit-plan quality on modification requests from two open-source harnesses. The public repository's helper is plan-only: it emits a localization plan, not an executed patch. So the result supports better navigation and planning. It does not prove that a generated handbook makes every final code change correct. Our six-surface map — prompt, state, tools, loop, policy, and tests — is a practical extension of that behavior-centric idea. The source evidence still has to come from the current repository, and the final change still has to survive tests and behavior-level evals. The useful lesson is simple: evolving agents need readable harnesses. Not because documentation is virtuous. Because behavior you cannot locate is behavior you cannot safely change. ## Sources - [Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable](https://arxiv.org/abs/2607.13285) - [Harness Handbook repository](https://github.com/Ruhan-Wang/Harness_Handbook) - [Harness Handbook project page](https://ruhan-wang.github.io/Harness-Handbook/) ## FAQ ### What is a behavior map for an agent harness? It is a small index that links one observable agent behavior to the prompts, state, tool calls, policy branches, source files, and tests that create it. ### Why not just give the whole repo to a coding agent? More context can still miss the actual behavior boundary. A behavior map starts from what the agent does, then follows that behavior to the exact implementation surface. ### Where should a team start? Pick one brittle harness behavior, map the prompt, state, tool, policy, and verifier paths behind it, then ask the coding agent to edit only verified locations. ## Related - background on making harness policy inspectable instead of hidden in controller code: natural-language-agent-harnesses - related argument that state, evidence, and verification matter more than bigger prompts: agents-dont-need-longer-prompts-they-need-harnesses - a loop-spec workflow for coding agents once the relevant behavior is localized: stop-prompting-coding-agent-loop-spec ## Source References - [Harness Handbook: Making Evolving Agent Harnesses Readable, Navigable, and Editable](https://arxiv.org/abs/2607.13285) (paper) - [Harness Handbook repository](https://github.com/Ruhan-Wang/Harness_Handbook) (repository) - [Harness Handbook project page](https://ruhan-wang.github.io/Harness-Handbook/) (project)