Architecture Decision Records
A systematic method for documenting architectural and technical decisions, their context, and rationale to preserve knowledge for future maintainers.
Also known as: ADR, Decision Records, Architectural Decision Records
Category: Techniques
Tags: software-development, documentation, knowledge-management, decision-making, best-practices, architecture
Explanation
Architecture Decision Records (ADRs) are short documents that capture important architectural and technical decisions made during software development. Each ADR describes a single decision, the context that led to it, the alternatives considered, and the rationale for the chosen approach. ADRs combat context rot by explicitly capturing the 'why' behind decisions at the moment they're made, when context is fresh and complete.
A typical ADR includes: a unique identifier, the decision title, status (proposed, accepted, deprecated, superseded), context (what circumstances led to this decision), decision (what was chosen), consequences (what trade-offs were accepted), and alternatives considered (what else was evaluated and why it was rejected). ADRs are stored as text files in version control alongside the code, making them discoverable and keeping them close to what they document.
The practice was introduced by Michael Nygard and has become widely adopted in software engineering. ADRs are particularly valuable for: onboarding new team members (who can understand past decisions without tribal knowledge), avoiding repeated debates (decision is documented once), understanding technical debt (why shortcuts were taken), and enabling confident change (knowing what assumptions a decision was based on).
ADRs should be immutable once accepted—if a decision changes, create a new ADR that supersedes the old one, preserving the historical context. This creates an audit trail of thinking. The format is intentionally lightweight to reduce friction: a few paragraphs is often sufficient. The key is capturing enough context that someone without your current knowledge can understand the decision in the future. ADRs transform implicit team knowledge into explicit documentation, making systems maintainable over time.
Related Concepts
← Back to all concepts