Architectural Decision Records (ADRs)

Purpose

An ADR records one significant architectural decision — why it was needed, what was decided, and what it costs and gains — at the time the decision is made, preserving the reasoning for future readers who weren’t part of the original discussion.

Example

# ADR 12: Adopt ports-and-adapters for the order service

## Context

The order service's core logic is tightly coupled to a specific ORM, blocking a planned
database migration and making unit testing require a real database.

## Decision

Introduce a repository port; core logic depends only on that interface.

## Consequences

- Core logic becomes unit-testable without a real database.
- Slightly more indirection for readers unfamiliar with the pattern.
- The database migration becomes additive rather than a rewrite.

Behavior notes

• ADRs are typically numbered and kept together (often in the repository itself), forming a browsable history of significant decisions over a project’s lifetime.
• An ADR is not updated after the fact to reflect hindsight — if a decision is later reversed, a new ADR records that reversal and links back to the original, preserving the historical record.
• The Consequences section should honestly include costs, not only benefits — an ADR that only lists upsides isn’t a genuine decision record.

Common mistakes

• Writing an ADR after the decision is old news, reconstructed from memory rather than the actual reasoning at the time — loses most of its value as a record.
• Treating an ADR as permanent, unchallengeable justification rather than a snapshot of reasoning that was correct given what was known at the time.

Runtime notes

A documentation practice, not a language feature — applies to any software project regardless of technology.