Learn to write Architecture Decision Records (ADRs): decision context, consequences, rejected alternatives, MADR format, and linking decisions to code.
0 / 5 completed
1 / 5
What is an Architecture Decision Record (ADR) and what problem does it solve?
ADRs solve the 'why did we do this?' problem. Without them, teams re-debate settled decisions, make changes that violate implicit constraints, and lose context when engineers leave. A good ADR answers: What was the situation? What did we decide? Why did we choose this over the alternatives? What are the trade-offs? ADRs are typically stored in a docs/decisions/ folder alongside the code they relate to, making them version-controlled and PR-reviewable.
2 / 5
What is the correct language for the 'Context' section of an ADR?
ADR Context section language: 'We are building a multi-tenant SaaS application. Each tenant requires data isolation. Our team has strong PostgreSQL expertise but limited MongoDB experience. We expect 100-500 tenants at launch, growing to ~5,000 within two years. We need to choose a data isolation strategy.' — factual, specific, describes constraints. Avoid vague context: 'We needed to make a database decision.' Good context lets a reader understand why the decision made sense even years later.
3 / 5
How should 'rejected alternatives' be documented in an ADR?
Rejected alternatives language: 'Option B: Row-level security (RLS) in PostgreSQL. Considered because it avoids schema proliferation. Rejected because: (1) our ORM has limited RLS support requiring custom query interceptors, (2) debugging cross-tenant queries becomes significantly harder, (3) adding new tenants requires no schema changes but RLS policy management at scale is operationally complex for our current team.' This prevents future engineers from saying 'why didn't we just use RLS?' — the answer is already there.
4 / 5
What is the MADR (Markdown Architectural Decision Records) format and how does it differ from Nygard's original ADR format?
Nygard ADR (original): Title, Status, Context, Decision, Consequences — simple and quick to write. MADR: adds Decision Drivers (what criteria mattered most), structured pros/cons for each option, and a more formal decision outcome section. MADR trades brevity for rigour — better for high-stakes architectural decisions. Nygard's format is better for quick decisions. Both are stored in version control. Key MADR status values: proposed, accepted, deprecated, superseded (by ADR-0042).
5 / 5
How do you link an ADR to the code it governs?
Bidirectional linking pattern: In the ADR: 'This decision affects src/infrastructure/eventstore/ and all aggregate root classes.' In the code: '// ADR-0023 (docs/decisions/0023-event-sourcing.md): We use event sourcing for audit trail requirements. See the ADR before changing the persistence strategy.' This means: (1) engineers reading code can find the rationale, (2) engineers reviewing the ADR can find the affected code, (3) when you update the pattern, you know which files to check against the decision.