Skip to content
BENIBIX Learn

Architecture Decision Record (ADR)

Development🏗️ ArchitectureArchitecture Basics

Also known as Architectural Decision Record, Decision Log, ADR File

A short note that saves one design choice and why the team made it.

Think of it like

It is like a diary page for one big choice. It says what you chose and why.

Example

Emma's team picks PostgreSQL over MongoDB. She writes record number 7 with the reasons, so a new developer a year later knows why.

Why it matters

Teams forget why things are the way they are. A record stops the same argument from coming back again and again.

Definition

An architecture decision record is a short note that saves one big design choice and the reasons for it. It says what the problem was, what the team chose and what follows from that choice. Each record covers one decision and gets a number. The records live with the code, often as Markdown files in a docs folder. Michael Nygard made the idea popular in a blog post in 2011.

Example code

console
$ ls docs/adr
0001-record-architecture-decisions.md
0002-use-postgresql.md
0003-split-billing-service.md
Each decision gets its own numbered file, kept next to the code.
The record in the middle holds one choice. It says why, what was picked and what comes next.

Common mistake

Editing an old record when the choice changes. Write a new record that replaces it, so the history stays true.

Key takeaways

  1. 1
    One decision each. Short and numbered.
  2. 2
    Context and consequences. Why, and what follows.
  3. 3
    Never rewritten. Replaced by a new one.

Compare