Senior (L5)
⚡THE SHORT ANSWER
As software organizations grow, engineering turnover causes Organizational Amnesia: new engineers look at a complex system design and declare 'Who wrote this stupid code? Why didn't they use Kafka / MongoDB? Let's rewrite it!'. They spend 6 months rewriting the system, only to rediscover the exact same edge cases, scale constraints, and security bugs that forced the original team to build it that way in the first place. Architecture Decision Records (ADRs) (invented by Michael Nygard) capture the historical rationale of significant technical decisions in version-controlled Markdown files inside the Git repository (
/doc/adr/0014-use-postgres-for-ledger.md). An ADR follows a lightweight structure: Context (The problem and constraints), Decision (The chosen architecture), and Consequences (Positive benefits, negative trade-offs, and accepted risks). ADRs turn implicit, ephemeral Slack arguments into durable, searchable institutional knowledge.Engineering Handbook & Failure Dynamics
6-Dimensional Architecture Breakdown⚙️1. Underlying Mechanism
ExecutionADR governance operates via the Git Pull Request review workflow:
1
Proposal: An engineer drafts
docs/adr/0042-adopt-graphql-for-mobile.md with status PROPOSED.2
Collaborative RFC Discussion: The team reviews the PR, debating trade-offs in GitHub comments.
3
Decision State Transitions: Upon consensus, the status updates to
ACCEPTED and the PR merges to main. If superseded in the future, a new ADR (e.g. 0089) marks ADR 0042 as SUPERSEDED with a link, preserving the evolutionary history.4
Monorepo Co-location: ADRs live alongside the code they govern, ensuring they are searchable via standard IDE tools.
🎯2. Appropriate Use Context
ScopeMajor framework adoptions, database engine selections, microservice boundary splits, protocol choices (gRPC vs REST), and security auth redesigns.
⚠️3. Production Failure Modes
P0 Risk- ✓Writing 40-page bureaucratic ADRs that take 3 months to approve, paralyzing delivery velocity
- ✓storing ADRs in obscure private Google Docs that nobody can find
- ✓failing to record accepted negative consequences
📡4. Diagnostic Signals & Telemetry
Telemetry- ✓Engineers spending hours debating 'Why are we using PostgreSQL instead of DynamoDB?' for the fourth time in a year
- ✓new hires breaking implicit architectural invariants because decisions were never documented
- ✓architectural amnesia after senior staff departures
🛡️5. Prevention & Safeguards
Safeguards- ✓Adopt the lightweight Michael Nygard ADR Markdown template (maximum 2 pages)
- ✓store ADRs in
docs/adr/in the Git repo - ✓mandate an ADR for any technical change that affects >1 team or has > 6 months blast radius
⚖️6. Architectural Trade-offs
Trade-offADRs eliminate architectural amnesia and build transparent technical consensus, but require engineering discipline to keep decision records updated as systems evolve.
📋
REAL-WORLD TELEMETRYCase Study (TinyCTO In-Field Example)
A newly hired Tech Lead noticed that their analytics pipeline was built on PostgreSQL instead of ClickHouse. Believing the original team was incompetent, he spent 4 months rewriting the pipeline in ClickHouse, only to discover that the data required heavy relational transactional updates from the billing engine that ClickHouse could not handle efficiently. Had he checked the repo,
docs/adr/0018-postgres-over-clickhouse-for-billing-cdc.md clearly documented this exact trade-off 2 years prior. The company adopted mandatory ADR reviews for all major rewrites, saving hundreds of wasted engineering hours.Interactive Concept Drills
2 CardsQ1
What are the three essential sections of an Architecture Decision Record (ADR)?
1. Context (the problem, business drivers, and technical constraints), 2. Decision (the chosen architectural solution), and 3. Consequences (the positive benefits, negative trade-offs, and accepted risks).
Q2
Where should Architecture Decision Records (ADRs) be stored in a software project?
Directly inside the source code Git repository (e.g. `docs/adr/` or `_PM/Agent-PM/Docs/ADRs/`) as version-controlled Markdown files alongside the code they govern.
Architectural Memory: Architecture Decision Records (ADRs) & Preventing Organizational Amnesia — Technical FAQ
What should you do when a past architectural decision documented in an ADR becomes obsolete?
Do NOT edit or delete the old ADR file; create a new ADR explaining the new context and mark the previous ADR's status as `SUPERSEDED` with a link to the new record.
How long should an effective Architecture Decision Record be?
Concise and lightweight: typically 1 to 2 pages of Markdown, taking no more than 15-20 minutes to read and review.
🤖 AEO & Key Facts Summary
Key Architectural Facts
- ▸Architecture Decision Records (ADRs) capture technical decisions and trade-offs in Git.
- ▸Three core sections: Context (Problem) -> Decision (Solution) -> Consequences (Trade-offs).
- ▸ADRs prevent 'Organizational Amnesia' when senior engineering personnel depart.
- ▸Never delete past ADRs; mark them as
SUPERSEDEDwhen superseded by new designs.
Common Misconceptions
- ✗Yanılgı: ADRs are heavy bureaucratic documents that slow down agile development (Gerçek: Lightweight 1-page ADRs take under an hour to write and save months of wasted refactoring debates).
- ✗Yanılgı: ADRs are only for perfect, unanimous decisions (Gerçek: ADRs explicitly document controversial compromises, technical trade-offs, and accepted shortcomings).
Decision & Governance Guidance
Establish a version-controlled Architecture Decision Record (ADR) catalog in your Git repository to preserve architectural context, document trade-offs, and prevent organizational amnesia.
Authoritative Sources & Standards
- [ARTICLE]Documenting Architecture Decisions: The Original ADR Concept— Michael Nygard / Cognitect Architecture Blog