Agent experience
Codebases that are easy for agents are mostly codebases that were already easy for humans — with a few new emphases.
DX is how well a codebase lets humans work. AX — agent experience — is how well an environment lets agents perform. The overlap is large, which is reassuring: most AX work is good engineering you could already justify. But the weightings differ, and a few things matter much more than they used to.
Where AX and DX agree
- Fast, reliable test suites.
- Clear module boundaries with enforced dependencies.
- Descriptive names; consistent patterns.
- Types that encode intent rather than shapes.
- Small files with a single responsibility.
Where AX weights differently
- Searchability beats cleverness. An agent finds code by grep. Dynamically constructed names, magic strings assembled at runtime, and heavy metaprogramming are invisible to search, so the agent cannot find the thing it needs to change. A human can at least reason about the framework; the agent just misses it.
- Locality beats DRY, at the margin. A human can hold six files in their head. An agent pays real context for each one. Code that reads top to bottom in one file, with a little duplication, often outperforms a perfectly factored version spread across five — because the whole thing fits in one cheap read.
- Explicit beats implicit, strongly. Convention-over-configuration frameworks rely on knowledge that is nowhere in the repository. Explicit wiring costs lines and saves an entire category of confident wrong guesses.
- Error messages are instructions. Humans learn a cryptic error once and remember it. An agent meets it fresh every session. An error that says what to do converts a stuck loop into a fix.
- Generated code needs a visible boundary. Agents will happily hand-edit a generated file. Mark them clearly, put them in known directories, and mention it in the brief.
The cheap AX wins
- one 'check' script, same name in every repo - README with the three commands that matter, at the top - a brief that names the danger zones - fail-fast, quiet test output - error messages that name the fix - delete dead code (agents read it, copy it, and revive it)
That last one is underrated. Dead code is worse than neutral now: it is plausible, in-repo, and looks like a pattern to follow.
Watch out
Do not optimise a codebase for agents at the expense of the humans who maintain it. If a change makes the code worse to read and only helps the agent, it is probably a brief line or a check instead. AX is a tiebreaker, not an override.
Try it
Ask a fresh agent: "What about this codebase made it hard to work in? Be specific and cite files." Do not defend it. The answers that also annoy your teammates are your work queue.
Takeaways
- Most AX work is ordinary good engineering, reweighted.
- Searchability, locality, and explicitness matter more than they used to; cleverness costs more.
- Error messages that name the fix turn stuck loops into self-corrections.
- Delete dead code — agents read it and copy it.
Why does an agent prefer a slightly duplicated file over a well-factored abstraction across five files?
Because each file it must open costs context and attention, and following an abstraction means opening all of them. One self-contained file is a single cheap read with everything in view. This is a marginal preference, not a licence to abandon abstraction — but it is a real one.
A course by Pieter Zandbergen