Why We Still Write Design Docs on an AI-Assisted Engineering Team

Our engineers now write a meaningful share of their code alongside an AI coding agent — it drafts boilerplate, proposes a first pass at a function, catches the kind of typo that used to cost twenty minutes. It has made the mechanical part of engineering noticeably faster. What it hasn't touched is the part of the job that was never really about typing: deciding what to build, and why this approach over the three other reasonable ones.

That's the gap a design doc fills, and it's why we still require one for anything beyond a small, contained change — a new service boundary, a schema migration, an integration with a client's existing systems, anything where the cost of an early wrong turn compounds.

The "why" before the "how"

An AI agent, asked well, will happily produce working code for almost any approach you describe to it. That's the trap: it removes the friction that used to force a developer to slow down and think through an architecture before committing to it. A design doc reintroduces that friction deliberately, but earlier and cheaper — on a page, before a line of code exists, where a colleague can challenge an assumption in a comment instead of in a much more expensive pull-request review three weeks later.

A template that actually gets used

We keep ours short on purpose, because a design doc nobody reads is worse than no design doc. Ours covers four things:

• Context — the problem in the client's or product's terms, not the technical framing, in three or four sentences.
• Options considered — at least two real alternatives, including "do nothing" or "the smallest possible version," with honest trade-offs for each.
• The decision — what we're building and, just as importantly, what we're explicitly not building yet.
• Risks — what could make this the wrong call in six months, and what signal would tell us that early.

One page. If it needs a second page, that's usually a sign the problem hasn't been scoped tightly enough yet.

A design doc is not documentation for later. It's the cheapest disagreement we'll ever have about this decision.

Where AI agents fit — and where they don't

We do use AI agents inside this process, just in a specific role: drafting the first version of the options section from a rough description, summarising a long client thread into the "context" a doc needs, or reviewing a finished doc for gaps and unstated assumptions before a human does. What we don't delegate is the decision itself — picking between the options is a judgment call that has to sit with someone who owns the consequences of being wrong, and who can be asked "why this one" in a meeting six weeks later.

Code review discipline hasn't changed

If anything, AI-assisted code raises the bar on review, not lowers it. Code that was generated quickly still has to be read slowly — for correctness, for whether it actually matches the design doc's decision, and for the subtle inconsistencies that come from a model pattern-matching against similar-looking code elsewhere rather than reasoning about this specific system. Our review checklist hasn't shrunk since we adopted these tools. It's stayed exactly as thorough, applied to code that now arrives faster.