What Is a Design Doc (and Do You Need One)?

Quick answer
A design doc explains why a system is shaped the way it is: the problem, the constraints, the options, the decision, and the consequences.
It is not a spec. A spec states what will be built and how it will be verified; a design doc states why this approach rather than the alternatives.
Write one when a decision is expensive to reverse, spans services or teams, or introduces a dependency you will live with.
A short design doc is better than a long one: two pages covering context, options, decision, risks, and rollout is usually enough.
For AI-assisted work it doubles as durable context, because the assistant’s reasoning disappears when the conversation does.

What goes in a design doc?

Context: the problem and the constraints that make it hard. Goals and non-goals: what this design is responsible for and deliberately not responsible for. Options: at least two real alternatives with their trade-offs. Decision: the chosen approach and the reasoning. Risks: what could go wrong and how you would notice. Rollout: migration, flags, and rollback.

Keep each section short. The value is in the options and the reasoning, not in a comprehensive description of the system. A reader should be able to disagree with the decision after fifteen minutes, which is only possible if the alternatives and constraints are visible.

# Design: move session storage from Postgres to Redis
## Context
Sessions add 4k reads/s to the primary database and dominate p99 latency.
## Goals / non-goals
Goal: remove session reads from Postgres. Non-goal: single sign-on changes.
## Options
1. Redis with TTL. Fast, adds a dependency, sessions lost on eviction.
2. Signed cookies. No store, but revocation is hard and size is limited.
3. Keep Postgres, add a cache. Least change, keeps the write path.
## Decision
Option 1. Sessions are disposable; a forced re-login is acceptable.
## Risks / rollout
Redis outage logs everyone out. Dual-write for one week, then cut reads.

How is it different from a spec or an ADR?

A spec describes a change’s behaviour and acceptance criteria; it is checked by tests. A design doc describes the architecture and the reasoning; it is checked by review. An architecture decision record is a shorter, narrower artifact that captures one decision and its consequences, often after the fact.

In practice, a small change needs a spec, a large architectural change needs a design doc and a spec, and a decision that will be referenced repeatedly deserves an ADR. Using all three for every change is process for its own sake; using none is how a team ends up unable to explain why the system works the way it does.

When is a design doc worth writing?

When a decision is expensive to reverse: a database choice, an authentication model, a message-broker topology, a data-retention policy, a public API shape. When it crosses team boundaries, because the document is how the other team learns what you assumed. When it introduces a dependency the team will operate for years.

It is not worth writing for a new endpoint, a UI change, or a refactor that stays inside one module. In those cases the spec and the tests carry the information, and a design doc adds a document that will not be read.

Why does it matter more with AI-generated code?

Because the reasoning behind generated code is not recorded anywhere. The assistant chose a queue, a schema, or an auth flow in a conversation that has ended. Six months later nobody can reconstruct the alternative it rejected, or whether it considered one at all. The design doc preserves that reasoning at the moment it exists.

It also constrains the next generation. When an agent is given the design doc as context, it has the decision and the non-goals, so it is less likely to introduce a second pattern that conflicts with the first. That is cheaper than discovering the inconsistency in review, and much cheaper than discovering it in production.

Where this bites vibecoders
AI-built projects often contain three competing patterns for the same concern because each feature was generated in a separate conversation with no shared design context. A two-page design doc that names the chosen pattern and the rejected options is the smallest artifact that keeps the next generation consistent with the last.

Where AI coding assistants get this wrong

Letting the assistant choose an architecture and never recording why.
Writing a design doc that describes the implementation instead of the decision.
Listing only the chosen option, so review cannot challenge it.
Writing a design doc for a small change and skipping it for a migration.
Leaving non-goals out, which invites scope creep in generated code.
Treating the design doc as immutable after approval instead of updating it when reality changes.

Checklist

State the problem and the constraints.
List at least two real alternatives with trade-offs.
Record the decision and the reasoning.
Name the non-goals.
Describe risks, rollout, and rollback.
Review it before implementation and update it if reality changes.

FAQ

How long should a design doc be?

Two to five pages for most decisions. The constraint is reviewer attention, not completeness. If it is longer, the decision is probably several decisions and should be split. A document nobody finishes does not produce the disagreement that makes it valuable.

Who writes and approves a design doc?

The engineer or team proposing the change writes it. Approval belongs to the people who will operate and depend on the result, not to a central architecture board. For a solo project, the discipline is writing it down and revisiting it after the rollout, when the assumptions can be checked.

Should a design doc include code?

Diagrams, interfaces, and small schema or API fragments help. Full implementations do not, because they lock the discussion to one solution and go stale quickly. Show the shape of the boundary and the data flow; leave the internals to the spec and the code.

Where should design docs live?

In the repository, next to the code they describe, so they are reviewed and versioned with it. A wiki or shared drive is acceptable for cross-team documents, but a design doc that lives only in a chat thread or a departed employee’s notes is effectively lost.