Architecture Decision Language
5 exercises — practise the vocabulary of ADR writing and architecture governance: ADR field vocabulary (Context vs. Decision), Status lifecycle including Superseded, well-structured Consequences sections, decision drivers, and Architecture Review Board scope and bypass conditions.
0 / 5 completed
1 / 5
An architecture team is reviewing a completed ADR. A new team member asks: "Which section captures the WHY — the reasoning behind making this decision, including the forces, constraints, and quality attribute requirements that drove it?" Which ADR field is being described?
ADR structure vocabulary — field definitions:
The Context field answers: "Why did we need to make a decision at all? What was the situation?". The Decision field answers: "What did we decide?". These two are frequently confused — understanding the distinction matters for writing ADRs that are useful months or years later when the original team members are no longer available.
ADR quality test: If someone reads only the Context and Decision sections, they should understand both WHY the decision was necessary and WHAT was decided — without needing to read anything else.
The Context field answers: "Why did we need to make a decision at all? What was the situation?". The Decision field answers: "What did we decide?". These two are frequently confused — understanding the distinction matters for writing ADRs that are useful months or years later when the original team members are no longer available.
| ADR field | Question it answers | Example content |
|---|---|---|
| Title | What decision was made? | "ADR-012: Use PostgreSQL as the primary datastore" |
| Status | What is the lifecycle state of this decision? | Proposed → Accepted → Superseded by ADR-031 |
| Context | WHY did we need to make this decision? What were the forces and constraints? | "The team evaluated 3 databases. Constraints: GDPR residency, existing team PostgreSQL expertise, budget cap on managed services." |
| Decision | WHAT did we decide? | "We will use self-hosted PostgreSQL 16 on managed cloud VMs." |
| Consequences | What are the results — positive, negative, and risks? | "+ ACID guarantees; + team expertise. − No managed failover; risk: backup automation must be self-managed." |
ADR quality test: If someone reads only the Context and Decision sections, they should understand both WHY the decision was necessary and WHAT was decided — without needing to read anything else.