Skip to content

Draft — not approved. A working draft by UASK. It may change without notice.

Status: review · Version 1.0.0

Architecture decision records

Summary

An architecture decision record (ADR) captures one significant decision: the problem, the options that were considered, the choice and its consequences. ADRs live in the repository, are numbered, and are never rewritten once accepted — a changed decision gets a new record that supersedes the old one. The result is a decision log that explains why the system looks the way it does, to new people and to AI agents alike.

Rules

  • R1. A decision that is significant or hard to reverse (structure, technology, interfaces, data ownership, licensing, deployment model) MUST be recorded as an ADR before or when it is implemented.
  • R2. ADRs MUST be stored in the project repository as Markdown files named NNNN-short-title.md, where NNNN is the next sequential number; numbers MUST NOT be reused.
  • R3. Each ADR MUST contain at least: title, status, date, context and problem, considered options, the decision with its justification, and consequences (good and bad).
  • R4. Status MUST be one of proposed, accepted, rejected, deprecated or superseded; a superseded record MUST link to the record that replaces it, and the new record MUST link back.
  • R5. The substance of an accepted ADR MUST NOT be edited; a changed decision MUST be recorded as a new ADR that supersedes it. Typo fixes and added links MAY be made in place.
  • R6. An ADR SHOULD cover exactly one decision and SHOULD fit on one or two pages.
  • R7. An ADR SHOULD list at least two real options, including “do nothing” or “keep the current approach” where that is viable.
  • R8. The decision text SHOULD cite evidence — measurements, prototypes, documentation with access dates — rather than opinion alone.

Guidance

  • Who decides. Make the approver explicit (a deciders field). In teams where agents draft ADRs, agents write proposed; a named human moves it to accepted.
  • Template. MADR 4 is a good default: it is free (MIT or CC0), Markdown-native and splits required sections (context, options, outcome) from optional ones (drivers, pros and cons, confirmation). Nygard’s original five sections (title, context, decision, status, consequences) are enough for small projects.
  • Where. MADR suggests docs/decisions/; Nygard used doc/arch/. Any fixed folder works — pick one per repository and link it from the README.
  • When not to write one. Reversible, local choices (a variable name, a library used in one test) do not need an ADR. If nobody would ask “why did we do this?” in a year, skip it.
  • Writing the context. State forces as neutral facts, including the ones that pull against the chosen option. A reader should be able to disagree with the decision using only the record.
  • Link both ways. Reference the ADR from the code, issue or pull request that implements it, and list that pull request in the ADR.

Explanation

Architecture is the set of decisions that are expensive to change. Code shows what was built, but not the alternatives that were rejected or the constraints that applied at the time. Without that record, later contributors either repeat old debates or reverse a decision without knowing why it was made.

Nygard proposed ADRs in 2011 as small text files kept with the code, so that they are versioned, reviewed and read in the same workflow as the code itself. Keeping superseded records, rather than deleting them, preserves the history: the old decision is still relevant to understanding the system, even when it is no longer the decision. ISO/IEC/IEEE 42010 likewise treats architecture rationale as part of an architecture description.

Examples

Good — one decision, options, evidence, consequences:

---
status: accepted
date: 2026-11-20
deciders: Product Owner
---
# 0007: Store sessions in Redis
## Context and problem
Two web nodes behind a load balancer; in-process sessions log users out on every failover (issue #41).
## Considered options
1. Sticky sessions on the load balancer
2. Sessions in the existing PostgreSQL database
3. Sessions in Redis
## Decision outcome
Chosen: Redis. Load test (PR #44): p95 login 38 ms vs 95 ms for PostgreSQL; Redis is already run for caching.
## Consequences
- Good: failover keeps users logged in.
- Bad: Redis becomes critical; needs persistence and monitoring (follow-up #45).

Bad — no options, no evidence, edited in place after acceptance:

# Decisions
- We use Redis now (changed from Postgres in March, see chat).

Sources