Developer Productivity
Implement Architecture Decision Records to document why you made important technical decisions. ADR template, examples, and workflow for software teams.
You make a technical decision.
"We're using PostgreSQL instead of MongoDB."
"We're adopting TypeScript."
"We're moving to microservices."
It's a good decision at the time.
Then: 18 months later, new team member asks, "Why PostgreSQL? Can we switch to MongoDB?"
You have to re-explain everything.
Or worse: you don't remember the tradeoffs anymore.
Context disappears.
Architecture Decision Records (ADRs) preserve that context.
An ADR is a lightweight document that captures:
This guide shows you how to implement ADRs effectively.
You make decision. You remember it.
6 months later: You don't remember why.
12 months later: New people question it constantly.
ADRs preserve context for future you and your team.
Same architectural question gets debated over and over.
Each time, you make the same decision.
Each time, someone questions it.
ADRs short-circuit repeated discussions.
New engineer joins.
Wants to understand architecture.
Architecture decisions feel arbitrary.
No way to learn the why.
ADRs help new engineers understand the why behind the what.
You build something.
Later: "Why did we do this?"
You don't know. You re-decide (differently).
ADRs create an audit trail of decisions and their justification.
Use this template for every architecture decision:
# ADR [NUMBER]: [TITLE]
## Date
[YYYY-MM-DD]
## Status
[Accepted/Proposed/Superseded/Deprecated]
## Context
What is the issue driving this decision?
[Explain the problem, constraints, context]
## Decision
What did we decide?
[State the architectural decision clearly]
## Rationale
Why this decision?
- Pro 1: [Benefit of this choice]
- Pro 2: [Benefit of this choice]
- Con 1: [Tradeoff or drawback]
- Con 2: [Tradeoff or drawback]
## Alternatives Considered
### Alternative 1: [Option A]
[Why we didn't choose this]
### Alternative 2: [Option B]
[Why we didn't choose this]
### Alternative 3: [Option C]
[Why we didn't choose this]
## Consequences
### Positive
- [What gets better]
- [What gets easier]
### Negative
- [What gets harder]
- [What we're giving up]
## Related Decisions
[Link to related ADRs]
# ADR 001: Use PostgreSQL as Primary Database
## Date
2025-01-15
## Status
Accepted
## Context
We're building a SaaS product with relational data (users, accounts, permissions).
We need ACID compliance, complex queries, and strong schema validation.
Decision: PostgreSQL vs MongoDB
## Decision
Use PostgreSQL as our primary database.
## Rationale
### Pros
- ACID guarantees: Data consistency is critical for billing, permissions
- Complex queries: JOINs across users, accounts, transactions
- Strong schema: We benefit from typed validation
- Mature ecosystem: Great tools, strong community
### Cons
- Horizontal scaling: PostgreSQL doesn't scale horizontally as easily as MongoDB
- Schema migrations: Schema changes require explicit migrations
- Cost: Hosting PostgreSQL clusters costs more than document stores
## Alternatives Considered
### MongoDB
- Rejected: No ACID (until MongoDB 4.0, but still not as strong). Looser schema makes debugging harder. Wrong tool for relational data.
### DynamoDB
- Rejected: AWS vendor lock-in. Query patterns less flexible. More expensive for our scale.
### Cockroach DB
- Rejected: Good for scaling, but immature. Operational overhead not worth it at our scale.
## Consequences
### Positive
- Strong data consistency: Billing/permissions guaranteed correct
- Easier debugging: Schema is explicit, no surprises
- Mature tooling: Lots of libraries, frameworks, operational tools
### Negative
- Schema migrations required for changes: Extra process, some downtime
- Horizontal scaling harder: We'll hit single-node limits at some scale
- Higher operational knowledge required: Team needs PostgreSQL expertise
## Related Decisions
- ADR 002: API response caching strategy
- ADR 003: Database backup and recovery process
Examples:
Why ADR: These are major, long-lived decisions affecting architecture.
Examples:
Why ADR: These drive the structure of the system.
Examples:
Why ADR: These affect system design and integration patterns.
Examples:
Why ADR: These have wide-ranging consequences.
Skip ADR for:
Use judgment: If it affects the team and it's not easily reversible, ADR it.
docs/
├── adr/
│ ├── 001-database-choice.md
│ ├── 002-api-caching-strategy.md
│ └── README.md
Store ADRs in version control (Git).
ADR 001, ADR 002, etc.
Use numbers for easy reference.
Don't wait months.
Write while decision is fresh.
Post for feedback.
Allow amendment during feedback period.
Once accepted, finalize.
In related code, add comment:
// See docs/adr/001-database-choice.md for why we use PostgreSQL
If ADR is superseded by new decision:
## Status
Superseded by ADR 015
Don't delete. Keep historical record.
You write 5-page ADR for minor decision.
Team thinks this is too heavyweight.
ADRs never get written again.
Fix: Keep ADRs brief (1–2 pages). Template should take 15–30 min to fill.
Decision was made 6 months ago.
You write ADR from memory.
Missing context and reasoning.
Fix: Write ADR immediately after decision is made, while context is fresh.
ADR just defends the choice.
Doesn't explain what was rejected and why.
Fix: Always include "Alternatives Considered" section.
Architecture changes.
ADR becomes outdated.
New people read it, get confused.
Fix: Update ADR status when context changes. If superseded, note which ADR replaces it.
ADR explains decision.
Doesn't explain what breaks or becomes harder.
Fix: Always document both positive and negative consequences.
ADR 005: Adopt Microservices Architecture
Context: Monolith growing to 500k LOC. Deployment cycles slow.
Decision: Split into 3 services (auth, core, analytics)
Alternatives:
- Monolith with better CI/CD: Rejected, still too tightly coupled
- Fully distributed: Rejected, too complex for current team
Consequences:
+ Faster deployment per service
+ Teams can work independently
- Operational complexity (3 databases, 3 deployments)
- Network calls between services (latency)
ADR 009: Use Redis for Caching
Context: Database queries slow. Need to cache frequently accessed data.
Decision: Use Redis cluster for cache
Alternatives:
- In-memory (application): Rejected, not shared across instances
- Memcached: Rejected, Redis has better data structures
- Database query cache: Rejected, not flexible enough
Consequences:
+ 10x faster reads for cached data
+ Flexible cache invalidation
- Extra infrastructure to operate
- Learning curve for team
Setup:
docs/adr/ folder.md filesPros: Simple, versioned, no extra tools
Cons: No fancy interface
Best for: Most teams
Setup:
Pros: Easy to link, built-in to GitHub
Cons: Less versioned than markdown in repo
Setup:
Pros: Beautiful interface, searchable
Cons: Not version-controlled with code
Best for: Non-technical stakeholders also need to read**
Before publishing, check:
docs/adr/ folderADRs preserve architectural decision context.
ADR template (simple version):
When to write ADR:
How to start:
docs/adr/ folder in your repoIn 3 months, you'll have 6–10 ADRs capturing your architectural context. In 6 months, new team members will reference them constantly.
For developer documentation, see Developer Notes System. For team documentation culture, check Documentation Culture in Engineering Teams.
Document decisions. Preserve context. Build shared understanding.
More WebSnips articles that pair well with this topic.
Build an engineering documentation culture developers will actually use. Covers incentives, templates, tooling, and practices for living documentation.
Write meeting notes that drive action. Template, best practices, and workflow for capturing decisions, action items, and context from every meeting.
Build async documentation practices for remote teams. How to write documentation that answers questions before they're asked and reduces meeting load.