Practice ADR vocabulary: capturing context, status lifecycle, significant decisions, superseding ADRs, and the MADR format.
0 / 5 completed
1 / 5
An ADR template says 'The ADR captures the context for future engineers.' What does the context section explain?
The context section is the most valuable part of an ADR for future engineers. Systems are built by people with shared knowledge that is never written down. The context section captures: what problem this solves, what constraints existed, what was considered, and why the chosen approach was selected — preventing 'why did we do this?!' confusion years later.
2 / 5
An ADR has 'Status: Proposed.' What does the ADR lifecycle typically look like?
ADR status tracks where a decision is in its lifecycle: Proposed means it's been drafted and is under review; Accepted means it's been agreed upon and should guide development; Deprecated or Superseded means a newer ADR has replaced it. This allows teams to know which decisions are still in force.
3 / 5
Your team says 'We write an ADR when a significant decision is made.' What qualifies as a significant decision?
Significant decisions worthy of an ADR include: choosing a database, selecting an architectural pattern, deciding how to handle authentication, choosing a communication protocol, or deciding to adopt a new framework. The test: 'Will a future engineer wonder why we did this?' If yes, write an ADR.
4 / 5
An ADR header says 'This ADR is superseded by ADR-042.' What does superseding mean in ADR practice?
ADRs are never deleted — they are historical records. When a decision changes, a new ADR is written and the old one is marked 'Superseded by ADR-042.' This preserves the history of why the original decision was made, what changed, and when — valuable context for understanding how the system evolved.
5 / 5
A team says 'We use MADR (Markdown ADR) format.' What is MADR?
MADR (Markdown Architectural Decision Records) is a community-maintained template standard for ADRs written in Markdown — making them easy to store in a Git repository alongside the code they document. The standardized format makes ADRs consistent and easy to scan across a large codebase.