# Architecture Decision Record (ADR)

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

**Field:** Software Development  
**Category:** Architecture  
**Also known as:** Architectural Decision Record, Decision Log, ADR File

## Think of it like

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

## 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

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

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

## Why it matters

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

## Common mistake

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

## Three principles

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

## Related terms

- [Technical Design Document](https://learn.benibix.com/term/development/technical-design-document)
- [Software Architecture](https://learn.benibix.com/term/development/software-architecture)
- [Software Documentation](https://learn.benibix.com/term/development/documentation)
- [Technical Debt](https://learn.benibix.com/term/development/technical-debt)
- [Unified Modeling Language (UML)](https://learn.benibix.com/term/development/uml)
- [README File](https://learn.benibix.com/term/development/readme)

## Told apart from

- [Architecture Decision Record vs Design Doc](https://learn.benibix.com/compare/architecture-decision-record-vs-technical-design-document): People think an architecture decision record is just a short design doc. A design doc plans a whole change before the code is written, and is read and argued over. A decision record saves one choice and the reasons, at any time, in a few lines. Design docs often go stale once the work ships. Decision records are kept for good, and a new one replaces an old one.

![Three papers side by side. The first, a design doc, has headings for problem, design, options turned down and open questions. The second, an architecture decision record numbered 7, has headings for context, decision and consequences. The third, a UML class diagram, shows two boxes, Order and Customer, joined by a line marked many to one.](https://learn.benibix.com/diagrams/dev6-architecture-docs.svg)

---

Source: https://learn.benibix.com/term/development/architecture-decision-record
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-18
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
