Skip to content

architecture decision record (ADR)

An architecture decision record, or ADR, is a short, dated document that captures a single architecturally significant decision, the context that forced it, and the consequences the team agrees to live with. ADRs are written as the decision is being made, stored in version control next to the code, and moved through a small lifecycle by adding new records that supersede earlier ones:

Top down state diagram. A start dot flows to a Proposed box that branches to Rejected or Accepted. Accepted then splits into Deprecated and Superseded boxes. All end states converge on one end dot.
A record is never edited to flip a decision, a new ADR supersedes it.

A typical ADR is one or two pages of Markdown checked in at doc/adr/0007-use-postgres-for-tenant-storage.md. The pull request that adds it is the forum where the decision is debated, amended, and accepted. Common topics include a deliberate piece of technical debt the team intends to revisit, or a security decision surfaced during a threat modeling session.

How It Shows Up in Practice

ADRs surface in a Python project the way any other piece of documentation does: as numbered files in a folder, reviewed through pull requests, and referenced from issues, design docs, and incident postmortems.

The convention popularized by Michael Nygard’s 2011 blog post and codified by Nat Pryce’s adr-tools CLI is to keep each record in doc/adr/. A typical filename looks like 0001-record-architecture-decisions.md, where the leading number is monotonically increasing and the rest is a present-tense imperative phrase.

adr-tools exposes a small set of subcommands that match the way teams actually work with these files:

Language: Shell 
adr init doc/adr
adr new "Use Postgres for tenant storage"
adr new -s 2 "Switch tenant storage to DynamoDB"
adr list

The -s flag stamps the new record as superseding ADR 2 and updates ADR 2 to point forward. Status moves through a small lifecycle of Proposed, Accepted, Deprecated, and Superseded. Records are never edited to flip a decision. A reversal is a new ADR with a new number, and the old one stays in the repository as the historical answer to “why did we ever do that?”

Because the records are plain Markdown committed beside the code, a single ADR stays short enough to read in a minute:

Language: Text 
# 3. Switch tenant storage to DynamoDB

Status: Accepted (supersedes ADR 2)

## Context
Postgres tenant tables are hitting write limits under multi-tenant load,
and the team needs single-digit-millisecond key lookups.

## Decision
We will move tenant storage to DynamoDB with on-demand capacity.

## Consequences
Faster key lookups and less database tuning, at the cost of ad hoc SQL
queries and a new dependency on one cloud provider.

Anatomy of an ADR

Most templates share the same skeleton. Nygard’s original four-section form is the lowest common denominator:

  • Title: a numbered, present-tense phrase such as 3. Switch tenant storage to DynamoDB.
  • Status: Proposed, Accepted, Deprecated, or Superseded by ADR N.
  • Context: the forces at play, written so a new engineer can understand the constraints without asking anyone.
  • Decision: the response, stated in active voice, such as “We will…”.
  • Consequences: the results the team accepts, both good and bad, including the new problems the decision creates.

Common variations layer extra sections on top. MADR, short for Markdown Architectural Decision Records, adds a “Considered Options” list with pros and cons for each alternative.

The Y-statement form compresses the whole record into a single sentence: “In the context of X, facing Y, we decided for Z and against W, to achieve Q, accepting R.” AWS Prescriptive Guidance recommends a longer form with explicit “Drivers” and “Decision Outcome” sections aimed at cross-team review.

Documenting Python Code Guide

Tutorial

Documenting Python Code: A Complete Guide

A complete guide to documenting Python code. Whether you're documenting a small script or a large project, whether you're a beginner or seasoned Pythonista, this guide will cover everything you need to know.

intermediate best-practices

For additional information on related topics, take a look at the following resources:

By Martin Breuss • Updated June 5, 2026
Software Engineering Glossary Share Feedback