Writing for two audiences

The design document you write next quarter will be read by a system that cannot ask you a follow-up question. This is a smaller change than it sounds, and it has one consequence worth taking seriously.

What does not change

Most advice about writing for AI is bad, and it is bad in a specific way: it assumes machines want something alien. Structured headings. Bulleted fragments. Keyword density. Documents optimised into shapes no human would choose to read.

This is unnecessary. The properties that make a document useful to an agent — explicit subjects, stated assumptions, defined terms, clear scope, a conclusion that is actually stated rather than implied — are the properties that make it useful to the engineer who joins in eighteen months. Good technical writing was always machine-readable. We simply had no machines reading it.

What does change: the cost of implication

Here is the real difference. Human readers repair documents as they read. When a design doc says "we'll use the standard retry approach," a colleague supplies the missing content from shared context — they know which approach is standard here, because they were in the room.

An agent has no room to have been in. It will either surface the ambiguity, or worse, resolve it confidently with the most common answer in its training rather than the correct answer for your organization.

So the discipline is not to write differently. It is to notice the places where you were relying on the reader to already know, and to stop. "The standard retry approach" becomes "exponential backoff with jitter, capped at thirty seconds, per ADR-0042." That sentence is better for everyone. It was always better. The cost of not writing it has simply become visible.

The second-order effect

Something we did not anticipate: making documents binding changed who writes them.

When a design document is decoration — written after the decision, read by nobody, filed forever — writing it is a chore delegated to whoever has time. When the document is the thing the pipeline enforces, writing it is the design work itself, and it goes to whoever has the judgment.

That has been the most significant cultural shift in our own organization, and it arrived sideways. We set out to give agents better context. We ended up giving writing back its status.

A practical test

Before you publish, ask what a competent stranger would have to assume to act on this document. If the answer is "nothing," you are done. If the answer includes anything about your team's habits, you have found the sentence to rewrite.

That test predates agents by about forty years. It is just that now, something runs it every time you merge.