Skip to main content

Architecture Decision Records

Architecture Decision Records document important engineering decisions and the reasoning behind them.

An ADR should be created when a decision materially affects repository architecture, development workflow, infrastructure, or long-term maintainability.

Each ADR should document:

Status
Context
Decision
Consequences
Alternatives considered

ADRs describe why a decision exists, while regular documentation describes how the resulting system works.

Existing ADRs should normally remain in history even when superseded. A newer ADR can reference and replace an older decision.