Writing documentation that an agent will read
By Allan Leone on
Your README was written for a person who can skim, infer and ask a colleague. It is now being consumed by something that does none of those, and the result lands in your codebase at volume.
Documentation has always been written for a reader who can fill gaps. They skim to the relevant part, infer the convention from surrounding code, and ask in Slack when something is ambiguous.
An agent does none of that. It reads what is there, treats it as authoritative, and applies it consistently. Which means a vague sentence in your README no longer produces one confused developer. It produces forty files following a rule you did not intend to write.
Say what not to do
Most documentation describes the happy path and leaves the boundaries implicit, because a human infers them. The boundaries are the highest-value thing you can write down now.
"Use the shared fetch wrapper" is a preference. "Use the shared fetch wrapper. Never call fetch directly, it bypasses auth refresh" is a rule with a reason, and the reason is what stops it being discarded when it seems inconvenient.
Examples beat prose
A paragraph explaining your error handling convention will be interpreted. A short before-and-after pair will be copied.
// Wrong: swallows the cause, so the log says nothing useful
try { await save(x) } catch { toast('Save failed') }
// Right: keep the cause, tell the user what to do
try { await save(x) }
catch (e) {
logger.error('save failed', { id: x.id, cause: e })
toast('Could not save. Your changes are still here.')
}Ten lines like that are worth more than a page of description, and they stay accurate longer because they are close enough to real code that someone notices when they drift.
Delete more than you add
A stale instruction is worse than no instruction. A person reads "we use Redux" in a codebase with no Redux and ignores it. An agent reads it and installs Redux.
The same applies to volume. Everything in the file competes for attention with everything else, so a long document with three critical rules buried in it performs worse than a short one containing only those three.
The document is now testable
This is the part I find genuinely new. You can check whether your documentation works by giving an agent a real task and reading what it produces. Where it goes wrong points at a specific sentence.
That is a feedback loop documentation has never had. Previously the only signal was someone eventually complaining.
Where to start
- Give an agent a small real task using only your current docs. Read the output as a review of the documentation, not of the model.
- For your five most important conventions, add the prohibition and the reason, not just the preference.
- Replace your longest explanatory paragraph with a wrong-and-right code pair.
- Delete every instruction referring to something no longer in the codebase. Do this before adding anything new.
Tags: engineering, ai, process