Architecture Decision Records: A Practical Guide for Engineering Teams

An Architecture Decision Record (ADR) is a focused document that captures a technical decision, the context behind it, and its expected consequences. At Spotify, teams such as the Creator Team—which builds tools for creators and manages their content data—use ADRs to log decisions about system design and engineering practices. These decisions typically emerge from Request for Comments (RFCs) discussions or regular engineering meetings.

Why ADRs Matter

Teams that consistently record architecture decisions report several concrete gains:

  • Faster onboarding: New engineers can review the decision history to understand not just what the current architecture is, but why it evolved that way. For example, when the Creator web engineers adopted React Hooks in 2019—after a small experiment in one part of the application—the ADR made it clear that new components should be function components, not class components.
  • Cleaner ownership handovers: In an agile organization, systems frequently move between teams. In the past, this often meant losing context and seeing productivity dip. With ADRs, the incoming team can reconstruct the reasoning behind architectural choices without relying on the departing team's institutional memory.
  • Better cross-team alignment: Documented decisions can be referenced and adopted by other teams. Spotify's Stockholm teams, for instance, were able to read and apply the React Hooks ADR written by the New York-based Creator web engineers, which reduced duplicated efforts and the number of divergent solutions central teams needed to support.

When to Write an ADR

The core question is: What counts as a decision of significant impact? That threshold is team-specific, but three common scenarios can guide you.

Backfilling undocumented decisions

Some standards form implicitly over time without ever being written down. These are often discovered during peer review, when a reviewer spots a competing pattern or library that reveals an unrecorded choice. If a decision exists but nobody has documented it, it is not truly a standard—new hires in particular will have no way to know. The mental model here is straightforward:

  1. Is there a problem? Yes.
  2. Is there an accepted solution? Yes.
  3. Is that solution documented? No.
  4. Write an ADR.

Proposing large changes

Major architectural shifts—breaking API changes, migration requirements, or significant redesigns—typically go through formal review processes like system design reviews or RFCs. Once those discussions conclude with a decision, the result should be captured in an ADR so the outcome is not lost after the meeting ends:

  1. Is there a problem? Yes.
  2. Is there an accepted solution? No.
  3. Is there a proposed solution? Yes.
  4. Is it a big change? Yes.
  5. Write an RFC first, then follow with an ADR once the RFC concludes.

Proposing small changes

Small decisions with little apparent impact are easy to skip—but the cost of undocumented decisions compounds over time. Undocumented choices can lead to duplicated work and competing libraries solving the same problem, eventually requiring a migration that could have been avoided. ADRs do not need to be heavyweight; a brief record of a small decision is enough:

  1. Is there a problem? Yes.
  2. Is there an accepted solution? No.
  3. Is there a proposed solution? Yes.
  4. Is it a big change? No.
  5. Write an ADR.