Architecture Decision Records: The Engineering Practice That Prevents Repeated Mistakes

Every software system carries a history of decisions—some documented, most not. When the engineers who made those decisions leave, the reasoning disappears with them. Future engineers either re-litigate settled questions or reverse decisions without understanding why they were made. Architecture Decision Records solve this.

What Is an ADR?

An Architecture Decision Record is a short document that captures a single architectural decision, its context, the options considered, and the rationale for the choice made. Michael Nygard popularised the format in 2011. It has since become a standard practice in high-performing engineering organisations.

The ADR Format

A minimal ADR contains:

Title: Short, imperative phrase describing the decision. "Use PostgreSQL as the primary database."

Status: Proposed / Accepted / Deprecated / Superseded by ADR-XXX

Context: The situation that necessitated this decision. What forces are at play? What constraints exist?

Decision: What was decided, stated clearly.

Consequences: What becomes easier, harder, or different as a result of this decision? What are the trade-offs?

When to Write an ADR

Write an ADR whenever you make a decision that:

• Has significant trade-offs
• Would be hard to reverse
• A new team member would question when reading the code
• The team debated before deciding

Decisions like: choice of database, choice of programming language, authentication approach, deployment model, API design style, frontend framework.

Where to Store ADRs

ADRs live in the repository alongside the code they describe. Use a docs/decisions/ directory. They are version-controlled, searchable, and co-located with the affected code. Tools like adr-tools automate creation and linking.

The Cultural Requirement

ADRs only work in a culture where engineers are expected to document reasoning, not just output. Lead by example—senior engineers and technical leads should write ADRs visibly and consistently. Make ADR review part of the PR process for significant changes.