Architectural Decision Records (ADRs): Documenting 'Why'
An ADR is a short text file capturing the 'why' behind a key engineering choice. Use it for big decisions like choosing a library or defining a core pattern.
Why it exists
Key technical decisions are often made in meetings or chat threads, and the context behind them is lost over time. When a new engineer joins or a system needs to be changed months later, the team is left wondering 'why did we do this?' This leads to re-litigating old debates or accidentally breaking unstated assumptions.
The mental model
Think of an ADR as a memo to your future self and teammates. It's a short, structured document that lives with your code in version control. It doesn't just state the decision; it explains the problem, the options considered, and the trade-offs accepted. It preserves the 'why' for posterity.
How it works
An ADR is typically a simple text file created from a template. It contains a title, a status (e.g., Proposed, Accepted, Deprecated), the context of the problem, the decision made, and the consequences of that decision. By checking ADRs into the project's repository, they become part of the project's history, reviewable and discoverable alongside the code they affect.
When to use it
Use ADRs for decisions that are significant and have long-term consequences. These are choices that are hard or expensive to reverse. The Wikimedia design system, for example, uses ADRs to document choices like adopting a specific library (FloatingUI), standardizing on string types in TypeScript, or deciding how to implement internationalization support.
When not to use it
Avoid writing ADRs for trivial, easily reversible decisions. Documenting every small bug fix or minor style change creates noise and buries the important architectural records. An ADR is for the skeleton of the system, not the cosmetic details.
One canonical example
A team building a design system needs to decide how to share visual styles. They could use Less mixins, utility classes, or a CSS-in-JS library. After debate, they choose Less mixins. The ADR would capture this: it would describe the need for reusable styles (the context), list the alternatives considered, state the final choice (the decision), and explain the trade-offs, such as requiring developers to learn Less but gaining strongly-typed style logic (the consequences).
Interview question
Which statement best describes the core purpose of an Architectural Decision Record (ADR)?
- a.To capture the context, alternatives, and trade-offs behind significant engineering decisions.Correct
- b.To ensure that all minor technical choices are formally recorded to maintain a complete history.
- c.To provide a detailed technical blueprint for implementing specific software components.
- d.To track the current status and future roadmap of all architectural changes in a project.
Why? this is the answer
An ADR's primary purpose is to document the 'why' behind significant engineering choices, including the problem, options considered, and trade-offs, to preserve context for future reference. It is explicitly stated that ADRs should not be used for trivial or easily reversible decisions, making option B incorrect.
Just read this? Test yourself on what you have been reading.
Read the original → doc.wikimedia.org
Put your scrolling time to good use
Learn one idea, try a quiz and save useful cards for revision. Tezvyn makes it easy to learn and stay current in your tech field, a few minutes at a time.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on architecture — each one lists the topics its interview covers.
See open roles