Write the design doc before you write the code

The fastest way to end up rewriting a feature is to start coding before anyone — including you — has written down what "done" actually means. A design doc does not need to be long to save you that rewrite; it needs to answer three questions before the first line of code.

Why does skipping the design doc cost more time than it saves?

Skipping the design doc feels faster because typing code feels like progress. But most rework doesn't come from writing the wrong code — it comes from building the right code against the wrong assumption, discovered only once a reviewer or a user hits the edge case you never wrote down. A half-page doc surfaces that assumption while it still costs a sentence to fix, not a pull request.

What does a lightweight design doc actually need?

Three sections are enough for most features: the problem in one paragraph (what breaks or is missing today), the approach in a few bullet points (what you will build, and just as importantly, what you will not), and the edge cases you already know about (what happens when the input is empty, huge, or malicious). If you can't fill in the second section confidently, that is the doc doing its job — it caught you before the code would have.

When is it fine to skip a design doc?

A one-line config change, a copy fix, or a revert doesn't need a doc — the design doc earns its cost on anything where a reviewer could reasonably ask "why did you build it this way" and you'd want a better answer than "it seemed right at the time."