Structure improves agent predictability

Structure Improves Agent Predictability

An AI agent edits code by pattern-matching against what it can see. The more the code's structure encodes the rules, the less the agent has to infer — and inference is where it guesses wrong. So structure isn't only for human maintainers anymore: a well-structured codebase makes agent behavior predictable; an ad-hoc one makes every agent edit a gamble. Treat the agent as a first-class reader and design for it.

Why structure changes the odds

A human carries hidden context across a sprawling function; an agent only has what's in front of it plus its priors. When the rules live in the shape of the code, a correct edit is the obvious edit:

• Typed boundaries (parse-don't-validate) mean the agent literally cannot thread an invalid value deep into the core — the type won't let it.
• Exhaustive matches / tagged unions mean adding a case forces handling it everywhere; the compiler points the agent at every site instead of it having to remember them.
• Named dispatch (table/map) over long if/switch chains means "add a behavior" is "add a row," not "find and correctly weave a branch into five places."
• Small, single-responsibility surfaces mean the blast radius of an edit is visible and local — the agent can't accidentally reach what it can't see.
• Explicit contracts at the edges (signatures that are misuse-resistant) mean the wrong call doesn't type-check, so the agent's mistake fails loudly at authoring time, not silently at runtime.

The tell

If you find yourself writing a comment like "remember to also update X when you change Y," that coupling is invisible to an agent and it will miss it. The fix isn't a louder comment — it's structure that makes X and Y change together (one source, exhaustive switch, shared type). Every "remember to…" is a latent agent bug; convert it into something the type system or a single dispatch point enforces.

How to apply

When writing or reviewing code that agents will maintain, prefer the option that removes a thing the next editor has to remember:

1. Make illegal states unrepresentable (types) over validating-and-hoping.
2. Make the set of cases explicit and exhaustive over open-coded branching.
3. Make "add a variant" a local, mechanical edit over a cross-cutting one.
4. Keep surfaces small so the visible context is the whole context.

This compounds with the rest of the design skills (parse-don't-validate, map-dispatch-over-conditionals, enums-codify-behavior, small-focused-changes): each one is also a bet that the next editor — increasingly an agent — will do the predictable thing because the structure left no other obvious move.