Develop and extend
How-to Available

Write and Maintain Architecture Decisions

Use an ADR for a consequential choice that is difficult to reverse, surprising without context, and based on a real trade-off. Keep current behavior in architecture and feature guides.

For
Maintainers and technical leads
On this page
  1. When an ADR qualifies
  2. Smallest complete format
  3. Supersede instead of rewriting history
01

When an ADR qualifies

Create an ADR only when the choice is hard to reverse, surprising without context, and the result of alternatives worth preserving. Establish rationale from maintainers, issues, plans, commits, or other historical evidence. Mark retrospective records clearly.

02

Smallest complete format

Use a stable YYYY-MM-DD-descriptive-slug.md filename, then state the decision title, status, date, optional origin, context, choice, and reason. Add alternatives, consequences, and revisit conditions only when they help future maintainers preserve or challenge the choice.

03

Supersede instead of rewriting history

Accepted ADR filenames remain stable. When a decision changes, create a new ADR and mark the old one superseded. Feature and architecture docs must still describe the current system, because an ADR explains why rather than serving as a live product manual.

Documentation