Your Agent Harness Needs a Behavior Map

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 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:

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:

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:

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
• Harness Handbook repository
• Harness Handbook project page