Design doc

A design doc is a short written description of how you plan to build something, written before you build it. It covers the approach, the main pieces, the trade-offs you weighed, and what you are deliberately not doing. It is not a spec: a spec says what to build and why, a design doc says how.

Why it matters more with agents

Writing the plan down forces a decision. Vague intentions survive in your head; they do not survive contact with a paragraph that has to name the actual approach. The act of writing surfaces the problems early, while they are cheap to fix, instead of halfway through the build.

For an agent, a design doc is high-value context. Hand it the plan up front and it builds along the lines you chose, rather than inventing an architecture on the fly that you then have to unpick. It is the difference between "add auth" and a page that says which library, which flow, and where the tokens live.

• Keep it short. A page that gets read beats ten that do not.
• Write it after a prototype, not before. Rough code makes the plan concrete.
• Include the rejected options. Knowing what you ruled out stops the agent re-suggesting it.