Use when documenting significant technical or architectural decisions that need context, rationale, and consequences recorded.
Document significant architectural and technical decisions with full context, alternatives considered, trade-offs analyzed, and consequences understood. ADRs create a decision trail that helps teams understand "why" decisions were made, even years later.
Trigger phrases: "ADR", "architecture decision", "document this decision", "why did we choose", "decision record", "technical decision log"
An Architecture Decision Record is a document capturing a single significant decision. It includes:
Quick Example:
# ADR-042: Use PostgreSQL for Primary Database
**Status:** Accepted
**Date:** 2024-01-15
**Deciders:** Backend team, CTO
## Context
Need to select primary database for new microservices platform.
Requirements: ACID transactions, complex queries, 10k+ QPS at launch.
## Decision
Use PostgreSQL 15+ as primary relational database.
## Alternatives Considered
- MySQL: Weaker JSON support, less robust constraint handling
- MongoDB: No ACID across documents, eventual consistency issues
- CockroachDB: Excellent but adds operational complexity we can't support yet
## Consequences
✓ Strong consistency and data integrity
✓ Excellent JSON support for semi-structured data
✓ Team has deep PostgreSQL experience
✗ Vertical scaling limits (will need read replicas at 50k+ QPS)
✗ More complex to shard than DynamoDB if we need it
Copy this checklist and track your progress:
ADR Progress:
- [ ] Step 1: Understand the decision
- [ ] Step 2: Choose ADR template
- [ ] Step 3: Document the decision
- [ ] Step 4: Validate quality
- [ ] Step 5: Deliver and file
Step 1: Understand the decision
Gather decision context: what decision needs to be made, why now, who decides, constraints (budget, timeline, skills, compliance), requirements (functional, non-functional, business), and scope (one service vs organization-wide). This ensures the ADR addresses the right problem.
Step 2: Choose ADR template
For technology selection (frameworks, libraries, databases) → Use resources/template.md. For complex architectural decisions with multiple interdependent choices → Study resources/methodology.md. To see examples → Review resources/examples/ (database-selection.md, microservices-migration.md, api-versioning.md).
Step 3: Document the decision
Create adr-{number}-{short-title}.md with: clear title, metadata (status, date, deciders), context (situation and requirements), decision (specific and actionable), alternatives considered (with pros/cons), consequences (trade-offs, risks, benefits), implementation notes if relevant, and links to related ADRs. See Common Patterns for decision-type specific guidance.
Step 4: Validate quality
Self-check using resources/evaluators/rubric_adr_architecture.json. Verify: context explains WHY, decision is specific and actionable, 2-3+ alternatives documented with trade-offs, consequences include benefits AND drawbacks, technical details accurate, understandable to unfamiliar readers, honest about downsides. Minimum standard: Score ≥ 3.5 (aim for 4.5+ if controversial/high-impact).
Step 5: Deliver and file
Present the completed ADR file, highlight key trade-offs identified, suggest ADR numbering if not provided, recommend review process for high-stakes decisions, and note any follow-up decisions needed. Filing convention: Store ADRs in docs/adr/ or architecture/decisions/ directory with sequential numbering.
For technology selection:
For architectural changes:
For standards and conventions:
For deprecations:
Do:
Don't:
resources/template.mdresources/methodology.mdresources/examples/database-selection.md, resources/examples/microservices-migration.md, resources/examples/api-versioning.mdresources/evaluators/rubric_adr_architecture.jsonADR Naming Convention: adr-{number}-{short-kebab-case-title}.md
adr-042-use-postgresql-for-primary-database.md