---
id: arch.term-adr
title: ADR (architecture decision record)
kind: term
domain: architecture
description: 'An architecture decision record is a short, numbered Markdown file that records one significant decision: its context, the options considered, the choice and its consequences.'
version: 1.0.1
status: review
applies_to: [core]
sources:
  - title: 'Michael Nygard, "Documenting Architecture Decisions" (2011)'
    url: https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions
    license: LicenseRef-All-Rights-Reserved
    accessed: 2026-11-20
  - title: MADR 4.0.0 — Markdown Architectural Decision Records
    url: https://adr.github.io/madr/
    license: MIT OR CC0-1.0
    accessed: 2026-11-20
standards: [ISO/IEC/IEEE 42010:2022]
related: [arch.adr, arch.c4-model, arch.term-blueprint, mgmt.roles-and-decision-rights]
last_reviewed: 2026-11-21
review_every: 12
---

## Definition

An **ADR** (architecture decision record) is a short, numbered file kept next to the code that records one significant, hard-to-reverse decision: the context, the options considered, the choice and its consequences. An accepted ADR is not edited in substance; a changed decision gets a new ADR that supersedes the old one.

Michael Nygard proposed the practice in 2011; MADR is a Markdown template for it, with fields for the options, the outcome, the consequences and the way the decision will be confirmed. A decision that is hard to reverse is marked as one the owner takes (see [Roles and decision rights](/knowledge/core/management/roles-and-decision-rights/)).

## Example

`0007-store-sessions-in-redis.md` with status `accepted`, three considered options and a measured result. Hub projects keep them in `project/decisions/`, written from `templates/adr.md`.

## Related

- [Architecture decision records](/knowledge/core/architecture/adr/) — the rules for writing and changing ADRs.
- [Blueprint](/knowledge/glossary/blueprint/) — where the choices are marked.
- [Roles and decision rights](/knowledge/core/management/roles-and-decision-rights/) — which decisions are the owner's.

## Sources

- [Michael Nygard, "Documenting Architecture Decisions" (2011)](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions) — all rights reserved; summarised, not copied. Accessed 2026-11-20.
- [MADR 4.0.0 — Markdown Architectural Decision Records](https://adr.github.io/madr/) — MIT OR CC0-1.0; summarised, not copied. Accessed 2026-11-20.
