Architecture Decision Records: Documenting Technical Decisions

Architecture Decision Records (ADRs) document significant architectural decisions and their context. An ADR captures the decision, the alternatives considered, the rationale, and the consequences. This creates an organizational memory that persists beyond team changes.

ADR Structure

Each ADR follows a consistent format. Title includes a short description and a unique number. Status indicates whether the decision is proposed, accepted, deprecated, or superseded. Context describes the problem and constraints that led to the decision.

Decision states the chosen approach explicitly. Consequences document the trade-offs, both positive and negative. Alternatives list approaches that were considered and why they were rejected.

Storage and Discovery

Store ADRs in version control alongside the code they describe. A \_docs/adr directory is conventional. Use sequential numbers or ISO dates as prefixes: 001-use-postgresql.md or 2026-05-use-postgresql.md. ADRs in version control are linked to commits and code changes.

Adoption

Start documenting decisions during design discussions. Write the ADR when the decision is made, not after. Review ADRs during architecture reviews. Link ADRs in pull requests that implement the decision. Keep ADRs short—one page is ideal.