ADR Writing Deep Dive
When to write ADRs, consequences, status values, titles, and ADR lifecycle
ADR writing essentials
- When to write: significant decision with meaningful alternatives and long-term consequences
- Consequences: positive + negative + neutral — an ADR with only positives is a sales pitch
- Status: Proposed → Accepted → Deprecated / Superseded by ADR-XXX
- Title format: "Use X instead of Y for Z purpose" — present tense, shows the choice and the alternative
- Supersede, don't delete — write a new ADR, update old status to "Superseded by ADR-N"
Question 0 of 5
What is an Architecture Decision Record (ADR) and when should you write one?
Record of a significant decision with alternatives and trade-offs — written when the decision is made. When to write an ADR:
- ✅ Choosing a database (PostgreSQL vs. MongoDB vs. DynamoDB)
- ✅ Selecting an authentication approach (session-based vs. JWT vs. OAuth2)
- ✅ Deciding on a deployment strategy (containers vs. serverless vs. VMs)
- ✅ Choosing a communication pattern (REST vs. GraphQL vs. gRPC)
- ✅ Accepting a significant technical trade-off
- ❌ Minor implementation details (which variable name to use)
- ❌ Decisions with only one obvious option
- ❌ Decisions already documented in other artefacts (tickets, design docs)
Which ADR section is most commonly written poorly, and what is the typical mistake?
Consequences section: engineers only list positives, omit trade-offs. Complete consequences section:
- Positive: "Reduced infrastructure cost by 40%; simpler deployment; no connection pool management"
- Negative: "Cold start latency of 200–800ms for infrequently called functions; 15-minute timeout limit constrains long-running operations; vendor lock-in to AWS Lambda"
- Neutral: "Requires team to learn serverless patterns; changes local development workflow"
What are the valid status values for an ADR, and what does each mean?
Proposed → Accepted → Deprecated / Superseded by ADR-XXX. ADR lifecycle:
- Proposed: decision is being discussed — the ADR documents the options under consideration
- Accepted: the team has decided — this is the current approach
- Deprecated: this approach is no longer recommended but the code still exists using it
- Superseded by ADR-0012: a newer decision explicitly replaced this one — link to the new ADR
- Deleting an ADR loses the history of why the original decision was made
- The old ADR explains the context that made the original approach reasonable
- Future engineers can trace the evolution of decisions without losing context
Which ADR title is written most effectively?
Number + decision verb + what was chosen + what was rejected. ADR title conventions:
- ✅ "Use PostgreSQL for the primary data store instead of MongoDB"
- ✅ "Adopt JWT for stateless authentication over session-based auth"
- ✅ "Deploy to AWS Lambda instead of containerised EC2 instances for the event processor"
An ADR was written 2 years ago for "Use Redis for caching". The team is now evaluating switching to an in-memory cache. What should they do with the existing ADR?
Write a new ADR that supersedes the old one — never delete, never overwrite. ADR revision process:
- Step 1: Write ADR-0024: "Replace Redis with in-memory LRU cache for the API response cache"
- Step 2: In ADR-0024, reference: "Supersedes ADR-0008 (Use Redis for caching)"
- Step 3: Update ADR-0008: change status to "Superseded by ADR-0024" — add a link to the new ADR
- ADR-0008 is kept, not deleted — it explains why Redis was chosen originally, which provides context for why the team is now switching