Goal
A design document reviewers can approve or challenge in one meeting, because the decisions and trade-offs are written down.
Inputs
- Feature and the problem it solves: [description, link to requirements if any]
- Current system: [stack, main components, where the feature fits]
- Constraints: [deadline, budget, hosting limits, compliance needs, team size]
- Expected scale: [users, requests per second, data size, growth]
- Ideas already discussed: [approaches the team is considering]
Steps
- State the context and the problem in a few sentences.
- List goals and non-goals, so scope is clear.
- Describe the proposed design: components, data flow, data model changes and API changes.
- Compare at least two alternatives with their trade-offs.
- Cover security, privacy, performance, failure modes, testing, rollout with a feature flag, and rollback.
Output format
- Title, status (draft) and summary in three sentences.
- Context and problem.
- Goals and non-goals.
- Proposed design, with a text diagram of the data flow in a code block.
- Data model and API changes, as tables.
- | Alternative | Pros | Cons | Why not chosen |
- Risks and mitigations.
- Rollout plan and rollback plan.
- Open questions for reviewers.
Check before answering
- Every non-goal is something a reader might reasonably expect, so it prevents scope creep.
- Security covers authentication, authorisation, input validation and secrets handling.
- Rollback is possible without data loss, or the document says clearly that it is not.
- No technology is recommended that the constraints rule out.






