ADR template (illustrative example)
# ADR-012: Enforce locale fallback rule in release service, not UI
## Status
Accepted
## Context
Entries could be published to locales they are not localised in via fallback…
## Options
1. UI-only validation — cheap, bypassed by API/CLI users
2. Enforce in release service (v2) — consistent for all clients
3. Enforce at deploy time only — late feedback
## Decision
Option 2, plus deploy-time skip as a safety net for items added earlier.
## Consequences
+ All clients (UI, API, SDK, CLI) get the same rule
− v1 releases excluded; document the boundaryHow to think about trade-offs
diagram
- There are no best practices, only trade-offs in context. Always say what you're giving up.
- Name the quality attributes that matter for this system; you can't maximise all of them.
- Prefer reversible decisions and decide those quickly. Spend time on the one-way doors.
Where I've used it
The TRDs I wrote as tech lead followed this shape: context, options considered, decision, and backward-compatibility impact. Deploy-side changes went through review by the team owning the delivery service. Written decisions are what made cross-team review possible.
Sources & further learning
Videos, courses, docs and books I recommend for this topic.
Documenting Architecture Decisions (original ADR post)Article · Michael Nygard · cognitect.comADR templates and toolingRepo · adr.github.io · adr.github.ioArchitecture decision record (ADR)Docs · Azure Well-Architected · learn.microsoft.comSoftware Architecture: The Hard PartsBook · Ford, Richards, Sadalage, Dehghani · oreilly.com
Related topics
Design PrinciplesApplied in production
KISS, DRY, YAGNI & Rule of Three
The pragmatic trio — keep it simple, don't repeat knowledge, don't build what you don't need yet — and when each one actually applies.
Foundation4 sources
Design PrinciplesApplied in production
API Evolution & Backward Compatibility
Change APIs without breaking clients — additive changes, tolerant readers, versioning strategy and explicit compatibility boundaries.
Intermediate4 sources
System DesignUnderstood
How to Approach Any System Design
A repeatable framework — requirements, estimates, API, data model, high-level design, deep dives, trade-offs — plus the numbers every architect should know.
Foundation7 sources