Architectural Decision Records (ADRs): Documenting 'Why'

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).