Source: Michael Nygard's ADR pattern + Google/Meta/ByteDance design doc culture Core Philosophy: Every architectural decision is a bet. ADRs record the bet, the rationale, and the expected payout so future teams know why you bet what you bet.
Why ADRs Matter
Without ADRs:
❌ "Why did we use MongoDB instead of Postgres?" — nobody knows
❌ New hires repeat old debates endlessly
❌ Trade-offs are forgotten — only the outcome is visible
❌ Bad decisions can't be revisited because we don't know why they were made
With ADRs: ✅ Every decision has context — future developers understand the "why" ✅ Decision quality improves — writing it down forces clearer thinking ✅ New hires can catch up by reading ADRs, not hunting through Slack history ✅ Revisiting decisions is easier — "has the context changed?"
## ADR Lifecycle
Proposed → Accepted → Superseded → Deprecated
Proposed: Decision is suggested but not yet agreed Accepted: Team agrees and implementation begins Superseded: A newer ADR replaces this decision (links to it) Deprecated: Decision is no longer relevant (system changed)
---
## ADR Template
```markdown
# ADR-NNN: [Title — short, descriptive]
- **Status**: [Proposed | Accepted | Superseded | Deprecated]
- **Date**: YYYY-MM-DD
- **Author**: [Name]
- **Supersedes**: ADR-NNN (if applicable)
- **Superseded by**: ADR-NNN (if applicable)
## Context
What is the context that makes this decision necessary?
Include:
- The specific problem being solved
- Business constraints (time, cost, resources)
- Technical constraints (existing stack, team expertise)
- Any relevant background or prior art
## Decision
What are we deciding? State the decision clearly.
"We will use [Technology/Method] for [Purpose] because [Primary Reason]."
Provide a concise, unambiguous statement of what the team is committing to.
## Options Considered
### Option A: [Name] (Recommended)
**Description**: Brief explanation of the approach.
**Pros:**
- Pro 1
- Pro 2
**Cons:**
- Con 1
- Con 2
### Option B: [Name]
**Description**: Brief explanation of the approach.
**Pros:**
- Pro 1
- Pro 2
**Cons:**
- Con 1
- Con 2
### Option C: [Name] (Do nothing / Baseline)
**Description**: Keeping the current approach.
**Pros:**
- Pro 1
**Cons:**
- Con 1
- Con 2
## Trade-off Analysis
Use a clear comparison table to show the decision rationale:
| Criteria | Option A | Option B | Option C |
|--------------------|----------|----------|----------|
| Performance | High | Medium | Low |
| Maintainability | High | High | Medium |
| Learning curve | Medium | Low | None |
| Operational cost | Low | High | Medium |
| Time to implement | 2 weeks | 1 week | 0 |
| Risk | Low | Medium | High |
## Consequences
What are the implications of this decision?
**Positive:**
- Consequence 1: What becomes easier/better?
- Consequence 2: What new capabilities do we gain?
**Negative:**
- Consequence 1: What becomes harder?
- Consequence 2: What trade-offs did we accept?
**Neutral:**
- Consequence 1: What changes about how we operate?
## Validation
How will we validate this decision was correct?
- [ ] Metric to track: [e.g., p99 latency, error rate, dev velocity]
- [ ] Review date: YYYY-MM-DD (3-6 months after decision)
- [ ] Success criteria: [e.g., "p99 < 200ms", "deploy time < 10 min"]
## Related Decisions
- ADR-NNN: [Related decision title]
- ADR-MMM: [Related decision title]
ADR Quick Template (2-minute version)
For small decisions that still need documentation:
# ADR-NNN: [Title]
- **Status**: Accepted
- **Date**: YYYY-MM-DD
## Context
[1-2 sentences]
## Decision
Use [X] for [Y].
## Rationale
[1-2 sentences on key trade-off]
## Consequences
[What changes as a result]
Examples
Example 1: Full ADR
# ADR-017: Use PostgreSQL over MongoDB for Order Service
- **Status**: Accepted
- **Date**: 2026-05-02
- **Author**: XuanYuan
## Context
The Order Service needs to store transactional order data with:
- Strong consistency (no stale reads)
- Complex relational queries (orders × items × payments)
- ACID transactions (money movement)
- No pre-defined query patterns (ad-hoc reporting)
- 1M+ orders/month, growing 10% monthly
## Decision
We will use PostgreSQL (with TimescaleDB extension) for the Order Service
because the data is inherently relational and requires ACID guarantees
that document stores cannot provide.
## Options Considered
### Option A: PostgreSQL (Recommended)
**Pros:**
- ACID compliant — critical for financial data
- Rich query language for reporting
- Mature ecosystem (ORM, migration tools, monitoring)
- TimescaleDB extension for time-series data
- JSONB for semi-structured data when needed
**Cons:**
- Vertical scaling limit (single writer)
- Schema migrations require careful planning
- Higher operational overhead vs managed alternatives
### Option B: MongoDB
**Pros:**
- Schema flexibility
- Horizontal scaling built-in
- Fast iteration cycles
**Cons:**
- No ACID across documents (vulnerable to data inconsistency)
- Joins are slow/limiting for relational data
- Reporting requires ETL to another system
- Schema-less is a liability for money-related data
### Option C: CockroachDB
**Pros:**
- ACID + horizontal scaling
- Postgres-compatible
**Cons:**
- Higher latency (distributed consensus)
- Less mature ecosystem
- Team lacks operational experience
- Overkill for current scale (< 10M orders/month)
## Trade-off Analysis
| Criteria | PostgreSQL | MongoDB | CockroachDB |
|---------------------|------------|---------|-------------|
| ACID transactions | ✅ Full | ⚠️ Limited | ✅ Full |
| Query flexibility | ✅ High | ⚠️ Medium | ✅ High |
| Team experience | ✅ High | ⚠️ Medium | ❌ Low |
| Horizontal scaling | ⚠️ Manual | ✅ Auto | ✅ Auto |
| Operational cost (3yr) | $30K | $25K | $60K |
| Risk | Low | Medium | High |
## Consequences
**Positive:**
+ Strong data consistency for money-related operations
+ Team can leverage existing PostgreSQL expertise
+ Rich reporting capabilities without additional tooling
+ TimescaleDB covers time-series needs without another DB
**Negative:**
- Must plan for sharding when we exceed 10M orders/month (est. 18 months)
- Schema migration process needs to be robust (use Sqitch)
- Read replicas needed for reporting to avoid production impact
**Neutral:**
- Will need to use logical replication for analytics pipeline
- JSONB hybrid approach for flexible metadata
## Validation
- [x] Review PostgreSQL/CockroachDB decision in 6 months
- [ ] Track: query latency p99 < 20ms, schema migration time < 5 min
Example 2: Quick ADR (small decision)
# ADR-009: Use Biome over ESLint+Prettier
- **Status**: Accepted
- **Date**: 2025-11-15
## Context
Frontend toolchain currently uses separate tools for linting (ESLint) and
formatting (Prettier). This causes configuration drift and CI conflicts.
## Decision
Replace ESLint + Prettier with Biome for linting + formatting in web UI codebase.
## Rationale
Biome provides lint + format in a single binary (3x faster, no config conflict),
supports 95%+ of our existing rules, and eliminates two config files.
## Consequences
+ Faster CI (lint+format step drops from 45s to 12s)
+ Single config file (biome.json) instead of .eslintrc + .prettierrc
- Team needs to learn Biome's rule syntax
- Some custom ESLint plugins need to be ported
ADR File Organization
docs/adr/
├── README.md # Index of all ADRs with status table
├── ADR-001-initial-architecture.md
├── ADR-002-use-postgres-for-orders.md
├── ADR-003-use-redis-for-caching.md
├── ADR-004-supersede-003-use-memcached.md
└── ADR-005-microservices-vs-monolith.md
README.md (ADR Index)
# Architecture Decision Records
| ADR | Title | Status | Date | Author |
|-----|-------|--------|------|--------|
| 001 | Initial Architecture | Accepted | 2026-01-15 | Alice |
| 002 | Use PostgreSQL for Orders | Accepted | 2026-02-01 | Bob |
| 003 | Use Redis for Caching | Superseded | 2026-02-15 | Carol |
| 004 | Supersede 003: Use Memcached | Accepted | 2026-03-01 | Carol |
| 005 | Microservices vs Monolith | Proposed | 2026-04-01 | Alice |
When to Write vs Not Write an ADR
WRITE an ADR when:
✅ Choosing between two+ technologies
✅ Making a decision with long-term impact
✅ Changing an existing architectural decision
✅ Introducing a new pattern/paradigm to the team
✅ The decision has cost, risk, or dependency implications
DON'T write an ADR when:
❌ Choosing a code style (that's a style guide)
❌ Making a trivial implementation detail
❌ You need a decision in 5 minutes (write it later)
❌ The decision is temporary and will be reversed
ADR Review Process
┌──────────────────────────────────────────────────────────────┐
│ │
│ ① Author drafts ADR (Proposed status) │
│ ↳ Optionally shared in slack #architecture channel │
│ │
│ ② Team reviews (async — 48h minimum) │
│ ↳ Focus on: are the options fair? Are trade-offs real? │
│ │
│ ③ Architecture sync (optional — if contentious) │
│ ↳ Discuss unresolved differences │
│ ↳ Agree on final decision │
│ │
│ ④ Status → Accepted │
│ ↳ Decision is locked unless new information emerges │
│ │
│ ⑤ Implementation follows the ADR │
│ │
│ ⑥ Review in 3-6 months │
│ ↳ Was the decision correct? Update or supersede │
│ │
└──────────────────────────────────────────────────────────────┘