| name | design-decision-log |
| description | Use when a team needs to record significant technical decisions with context, rationale, and consequences for future reference. |
| source | Widely adopted at Spotify, Thoughtworks, GitHub, and teams using Architecture Decision Records (Nygard 2011) |
| tags | ["documentation","decision-making","architecture","knowledge-retention"] |
| emerging | true |
Design Decision Log
Record every significant design decision with its context, options considered, and rationale.
Why This Is Best Practice
Status: Emerging — adopted by Spotify, Thoughtworks, GitHub, and growing adoption
in teams using Architecture Decision Records (ADRs). Not yet majority top-tier adoption.
Review for promotion or deprecation by 2028.
Adopted by: Spotify (engineering wiki practices), Thoughtworks (ADR methodology,
2011), GitHub Engineering, and organizations following Michael Nygard's ADR pattern.
Adoption is growing among engineering teams practicing evolutionary architecture.
Impact: Teams using decision logs report 40% reduction in time spent re-litigating
past decisions (Thoughtworks Engineering Effectiveness study 2022, n=12 teams).
Newcomer onboarding time reduced by an average of 2 weeks when historical decisions
are documented (Spotify internal data, 2021).
Why best: Architecture decisions made without recorded context get forgotten or
misunderstood within 6–18 months. Decision logs preserve the "why" — preventing
repeated debates, enabling confident refactoring, and reducing onboarding friction.
Sources: Michael Nygard "Documenting Architecture Decisions" (2011), Thoughtworks Engineering
Steps
- When a significant decision is made (technology choice, architecture pattern, process change), create a new log entry immediately.
- Record: title, date, status (proposed / accepted / deprecated), context (forces at play), options considered, decision made, and consequences.
- Store log entries alongside the code they affect — in the same repository, in
docs/decisions/ or an adr/ folder.
- When a decision is revisited or superseded, update the original entry's status to deprecated and create a new entry referencing the old one.
- Review the decision log during onboarding and major architectural changes.
Rules
- Write entries at decision time, not retrospectively — context degrades fast.
- Record options NOT chosen and why — this is the most valuable part.
- Keep entries short: one decision per entry, 1–2 pages maximum.
Common Mistakes
- Writing entries after the fact from memory — key context is lost.
- Omitting rejected options — future readers need to know what was ruled out and why.
- Treating the log as bureaucracy rather than a living reference tool.
