4 min readaiengineeringdelivery
Write the documentation your agents will read
Once machines do most of the building, documentation stops being a courtesy to future colleagues and becomes load-bearing — and has to be written differently.
Documentation has always been the thing everyone agrees is important and nobody funds. The usual argument for it — future maintainers will thank you — has never once won a prioritisation meeting, because future maintainers don’t attend.
Something changed when most of my code started being written by agents. Documentation stopped being a courtesy and became the highest-leverage artifact in the repository. Not because machines are more deserving readers, but because of a structural difference: a human who finds the docs wrong asks someone. An agent who finds the docs wrong confidently builds the wrong thing.
That single asymmetry changes what you write and how.
What became load-bearing
The constraints, stated as rules. Not “we generally prefer thin controllers” but “controllers contain no business logic; logic lives in a service; data access lives in a repository”. A human reads the first and infers the second. An agent reads the first and treats it as a preference, then produces a controller with a query in it and a polite note that this seemed simpler.
Rules with edges get followed. Preferences with hedges get negotiated away, every time, by a system that is trying to be helpful.
The anti-patterns, named explicitly. Listing what’s forbidden turns out to be more effective than describing what’s correct, because “correct” has many valid shapes and “forbidden” has a checkable one. My repository guidance is roughly a third prohibitions, and it’s the third that does the most work.
Why, not just what. This surprised me. I assumed rationale was a human luxury. It isn’t: an agent that knows why a rule exists handles the case the rule didn’t anticipate. One that only knows the rule either applies it somewhere it doesn’t belong, or abandons it at the first friction.
The map. Where things live, which module owns which concern, what the naming convention is. Cheap to write, and it’s the difference between a change landing in the right file and a plausible new file appearing beside it.
What stopped mattering
Prose explaining what the code does. The code is right there and it’s read faster than your paragraph. Comments that narrate the next line were always noise; now they’re noise that costs context.
Exhaustive API references written by hand. Generate them or don’t have them. A hand-written reference is wrong within a month and wrong documentation is worse than none, for exactly the reason above — a human notices the drift and mistrusts the doc, an agent doesn’t.
Onboarding documents in the old shape. “Welcome to the team, here’s our culture” has a purpose, but it isn’t this one. What earns its place is: how do I run this, how do I test this, how do I know I haven’t broken anything.
The rule that changed my output most
Every instruction must be checkable.
If a rule can’t be verified by running something or reading something specific, it’s a mood, and moods don’t survive contact with a system that takes text literally.
“Write efficient queries” is a mood. “No N+1 queries: a list endpoint must issue a constant number of queries regardless of result count” is a rule, and one you can actually check.
“Handle errors properly” is a mood. “Every external call is wrapped, has a timeout, and its failure path is tested” is a rule.
This discipline improved things for the humans too, which I didn’t expect. It turns out much of what we’d written for people was also mood, and everyone had been quietly interpreting it their own way for years. The ambiguity was always costing us; the machines just made the bill arrive faster.
Where it goes
Close to the code and versioned with it. A wiki in another system is a document about a codebase that used to exist.
Practically: a file at the root with the constraints and the map, and a docs folder with the deeper material — architecture, data model, API contracts, decision records. The important part isn’t the layout, it’s that updating them is part of the change, not a follow-up ticket. A follow-up ticket is where documentation goes to die.
I enforce this the boring way: if a change touches the data model, the data model doc is part of the same commit, and review rejects it if not. Not elegant. Reliable.
The test
Take a task you’d give a competent new colleague. Give it to an agent with only the repository and the docs — no conversation, no context from you. Look at what comes back.
Whatever it got wrong is a documentation gap, and it’s a gap that was already costing you with human colleagues; they were just filling it by interrupting someone.
That’s the honest reframe. Writing documentation an agent can follow isn’t a new discipline for a new kind of reader. It’s the old discipline, finally with a feedback loop fast enough that you can’t skip it.