THE SHORT ANSWER
ADRs capture the context, constraints, evaluated alternatives, and deliberate tradeoffs behind technical decisions right inside the codebase, preventing new engineers from blindly re-litigating settled debates or misunderstanding historical compromises.
Engineering Handbook & Failure Dynamics
1. Underlying Mechanism
Pioneered by Michael Nygard, an Architectural Decision Record (ADR) is a lightweight markdown document stored in source control (`docs/adr/0012-choose-kafka-over-sqs.md`). Each ADR has a strict state machine (Draft -> Proposed -> Accepted -> Superseded/Rejected) and captures: Status, Context (business drivers and constraints), Decision (the chosen architectural direction), and Consequences (positive, negative, and neutral ramifications).
2. Appropriate Use Context
Required whenever introducing new programming languages, primary databases, inter-service communication protocols, authentication frameworks, or foundational library abstractions.
3. Production Failure Modes
Teams repeatedly refactor back and forth between identical paradigms (e.g., monolith -> microservices -> monolith) every 18 months because the original constraints were never documented; critical systems abandoned because nobody understands why an odd design choice was made.
4. Diagnostic Signals & Telemetry
Engineers constantly asking in chat 'Why are we using library X instead of Y?', architectural decisions made during informal coffee chats, and PRs stalling over fundamental philosophical debates.
5. Prevention & Safeguards
Embed ADR templates in repo scaffolding tools; enforce a timeboxed 5-day RFC comment period with a designated Decider; never approve PRs with major architectural impact without an accompanying ADR PR.
6. Architectural Trade-offs
Introduces slight documentation overhead before writing code in exchange for permanent institutional memory, high alignment, and frictionless engineering onboarding.
Case Study (TinyCTO In-Field Example)
TinyCTO Episode 18: A new lead attempted to replace a custom Redis lock with Postgres row locking, causing a catastrophic database lock storm. The original ADR clearly stated Postgres locks were rejected due to connection pool limits, which would have prevented the outage.
Interactive Concept Drills
3 CardsWhat are the four essential sections of a standard Nygard ADR?
Why should ADRs be stored directly inside the code repository rather than in an external wiki?
What does it mean when an ADR status is marked as 'Superseded'?
Architectural Decision Records (ADRs) & RFC Engineering Culture — Technical FAQ
How long should an RFC discussion remain open before a final decision is made?
Standard practice is 5 to 7 business days. Without a strict timebox, RFCs devolve into bikeshedding and endless deliberation.
Who has the final authority to accept or reject an ADR?
The designated technical owner or Staff Engineer responsible for the domain, after considering all team feedback during the RFC period.
Should every small pull request require an ADR?
No. ADRs are reserved for significant, irreversible, or cross-cutting architectural choices. Routine bug fixes and standard feature extensions do not need ADRs.
🤖 AEO & Key Facts Summary
Key Architectural Facts
- ▸Engineering organizations with active ADR practices reduce onboarding time for senior hires by up to 40% by making technical history transparent.
- ▸An ADR is as much about documenting what was NOT chosen and why as it is about the chosen direction.
Common Misconceptions
- ✗Thinking that an accepted ADR is permanent and can never be challenged or modified.
Decision & Governance Guidance
Store ADRs as markdown in the relevant git repository alongside source code and review them via standard PR workflows.
Authoritative Sources & Standards
- [OFFICIAL-DOC]Documenting Architecture Decisions— Michael Nygard Blog (2011)
- [OFFICIAL-DOC]Architectural Decision Records Organization & Tooling— ADR GitHub