Architecture Decision Record (ADR)
A concise document that captures a single architecture decision, its context, the options considered, and the rationale for the chosen approach. ADRs create an immutable log of why decisions were made.
Purpose
ADRs provide a historical record of architecture decisions so that future team members understand why the system is built the way it is. They prevent repeated debates, support onboarding, and create accountability for technical choices.
When to Use
Create an ADR whenever a significant technical decision is made that affects the structure, non-functional characteristics, dependencies, interfaces, or construction techniques of the system.
How to Build
Start by identifying the decision that needs to be recorded. Write a clear, concise title that summarises the decision in active voice (e.g., 'Use PostgreSQL for transactional data storage'). Document the context — what forces are at play, what constraints exist, and what problem you are solving.
Next, list the options you considered. For each option, provide a brief description and note its pros and cons. Be honest about trade-offs; an ADR that only lists positives for the chosen option lacks credibility.
State the decision clearly and explain the rationale. Link back to the forces and constraints you identified in the context. If the decision was influenced by a spike, proof of concept, or vendor demonstration, reference that evidence.
Finally, document the consequences — both positive and negative. What will this decision enable? What technical debt might it introduce? What future decisions does it constrain or enable? Record the status (proposed, accepted, deprecated, superseded) and date.
Tips
- Keep ADRs short — one to two pages maximum. If it is longer, you are probably documenting multiple decisions.
- Use a sequential numbering scheme (ADR-001, ADR-002) and store them in version control alongside the code.
- Write in past tense for accepted decisions and present tense for proposed ones.
- Link ADRs to each other when decisions are related or when one supersedes another.
- Include the names of people involved in the decision for future reference.
- Review ADRs periodically — mark outdated ones as superseded with a link to the replacement.
Common Mistakes
- Writing ADRs after the fact without capturing the original context and alternatives considered.
- Making ADRs too long or too detailed — they should be decision records, not design documents.
- Not recording rejected alternatives, which leads to the same options being re-evaluated later.
- Failing to update the status when a decision is superseded or deprecated.
- Using vague language like 'we chose the best option' without explaining why it was best for this context.
Government Context
In UK government, ADRs are particularly valuable for spend control submissions and service assessments. GDS assessors will ask why certain technology choices were made, and ADRs provide ready-made evidence. They also support the Technology Code of Practice requirement to make things open by documenting reasoning transparently. CDDO encourages departments to share ADRs across government to prevent duplicated evaluation effort.