A repeatable structure for every design doc
Engineering teams move faster when every technical spec looks the same. A reviewer should always know where to find the problem statement, the API design, and the risky edge cases without hunting through the document. This builder produces a consistent Markdown document so your team spends energy on the design itself, not on document structure.
How it works
The builder maps each input field to a named section and assembles them in the canonical order used across most engineering design docs: Problem Statement, Proposed Solution, System Components, API Design, Data Model, Edge Cases, and Open Questions.
Multi-line inputs (components, edge cases, open questions) are rendered as bulleted lists for scannability. Prose fields (problem statement, proposed solution) remain paragraphs. Empty sections are dropped entirely, so a small bugfix produces a short, focused spec while a major architectural change naturally produces a thorough one — without restructuring the template.
The output is plain Markdown with ## headings, which pastes directly into GitHub PRs, Notion, Confluence, or any engineering wiki without reformatting.
What belongs in each section
Problem Statement: describe the current situation and what it prevents. One to three sentences. If you cannot state the problem clearly in three sentences, the design is not ready for a spec yet. Avoid mentioning the solution here — a spec that opens by describing the solution skips the step where reviewers can suggest a better one.
Proposed Solution: the high-level approach and why it was chosen over alternatives. This is where you make the case for your design direction. Keep it at the architecture level; the details go in the components and API sections.
System Components: list each piece of the system that will be built or modified — services, databases, queues, caches, external APIs. One item per line. Reviewers use this list to check completeness and identify missing dependencies.
API Design: document the key endpoints, their request/response shapes, authentication requirements, and HTTP methods. Even a rough sketch of the API surface is more useful than prose describing it — other teams or frontend engineers use this section to plan their work.
Data Model: describe the key entities, their fields, and their relationships. Include schema changes if modifying an existing model. This is the section most likely to catch design flaws early, since data model decisions are the hardest to reverse after launch.
Edge Cases: the cases that break naive implementations — empty inputs, concurrent writes, partial failures, out-of-order events, very large payloads, missing optional fields. List them explicitly. A spec with no edge cases for a non-trivial change usually signals they have not been examined yet.
Open Questions: list what you do not know yet and who needs to decide. This is one of the highest-signal sections in any spec — it tells reviewers exactly where to focus and prevents a design from looking more complete than it is.
Tips for review-ready specs
- Write the problem statement before the solution. The act of stating the problem often surfaces whether the proposed solution actually addresses it.
- Enter components, edge cases, and open questions one per line — the builder renders them as bullet points, which makes the section scannable in 30 seconds.
- Keep open questions visible and honest. Closing a spec with unresolved questions marked clearly is far better than leaving them implicit and discovering them mid-implementation.