Write Design Docs

Core Workflow

Use the design doc as a problem-solving and consensus-building tool, not as an implementation manual.

1. Decide whether a design doc is warranted.

   • Write one when the software design is ambiguous, complex, contentious, cross-functional, likely to benefit from senior review, or valuable as organizational memory.
   • Prefer a short note, issue, or direct implementation when the solution is obvious and there are no meaningful trade-offs.
   • Prefer a mini design doc for small but non-obvious changes.

2. Gather the minimum context needed to make the design concrete.

   • Identify the problem, existing landscape, constraints, stakeholders, and decision deadline.
   • Ask focused questions only when missing information would materially change goals, non-goals, or trade-offs.
   • State assumptions explicitly when proceeding with incomplete information.