Architecture Decision Records (ADRs) capture the context, decision, and consequences of important architectural choices. Unlike design documents that propose changes, ADRs document decisions that have been made — creating a permanent record of why things are the way they are. This template follows the widely adopted Michael Nygard format with Status, Context, Decision, and Consequences sections.
Why ADRs Matter
Six months from now, your team will wonder "why did we choose PostgreSQL over DynamoDB?" or "why is this service in Python instead of Go?" ADRs answer these questions by preserving the context and reasoning behind architectural choices. They prevent revisiting settled decisions, speed up onboarding for new team members, and create an audit trail of how the system evolved.
ADR Format
The template follows the standard ADR structure.
- Title: A short, descriptive name (e.g., "Use PostgreSQL for user data")
- Status: Proposed, Accepted, Deprecated, or Superseded (with link to replacement)
- Context: The forces at play — technical constraints, business requirements, team capabilities
- Decision: The change we are making — stated clearly and concisely
- Consequences: What becomes easier, harder, or different as a result of this decision
Tips for Writing Good ADRs
Keep ADRs short — one to two pages maximum. Focus on the "why" more than the "what." Include alternatives you considered and briefly explain why they were not chosen. Write ADRs as soon as a decision is made, while the context is fresh. Number your ADRs sequentially so they form a chronological record of decisions.