awesome-design-doclisted

# Design Doc / ADR Turn a feature request or architectural question into a decision a team can execute and a future reader can retrace. The core discipline: requirements and numbers before components, real alternatives before a recommendation, and a recommendation before the end — a document that tours options without choosing is a meeting agenda, not a design. ## When to Activate - "Design X", "how should we build Y", "write a design doc / ADR / RFC". - A reviewer flagged a load-bearing decision that needs an ADR (awesome-code-review hands the format here). - Two credible approaches exist and the choice is expensive to reverse. Do not activate for reversible everyday choices (naming, a helper's location) — an ADR for those is noise; the three-condition test below decides. ## When an ADR is warranted All three, or don't write one: 1. Expensive to reverse — schema, public API shape, persisted format, event name, framework/storage choice, service boundary. 2. Crosses a boundary — more than one module, team, or service must honor it. 3. The context would be lost — six months from now, the "why" is not recoverable from the code. One-page ADR for a single decision; full design doc when the feature needs a data model, API surface, and rollout plan together. ## Work Process 1. Requirements before components — functional requirements as testable statements, then the constraints that shape the design: expected scale (users, QPS, data volume and growth), latency targets, consi