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 / 10 completed
1 / 10
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 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.
2 / 10
A developer reviews an old ADR and sees the Status field reads: "Superseded by ADR-042." What does this status correctly indicate about the decision documented in this ADR?
ADR Status vocabulary — lifecycle states:
The "Superseded" status is one of the most important governance concepts in ADR practice. It means: this was the right decision at the time, under the constraints that existed then — but circumstances have changed and a new decision replaces it. Crucially, superseded ADRs are never deleted — they are the historical record.
Status
Meaning
What to do
Proposed
Under review; not yet accepted by stakeholders
Circulate for review; gather feedback
Accepted
Decision is in force; implementation may proceed
Implement; reference from related ADRs
Deprecated
No longer recommended but not yet replaced by a specific successor
Avoid using the pattern for new work; plan migration
Superseded by ADR-NNN
Explicitly replaced by a newer decision; old ADR remains as history
Follow ADR-NNN for new work; old ADR explains the prior context
Rejected
Was proposed but not accepted after review
Retain as record of why this option was not chosen
Why retaining superseded ADRs matters: When a new engineer joins and asks "why are we using X instead of Y?", the superseded ADR provides the answer — including the context that made Y the wrong choice at the time. Without this history, teams repeat the same evaluation work that was already done, or make decisions that violate constraints that are no longer obvious.
3 / 10
An architecture review panel evaluates an ADR about adopting a microservices architecture. The Consequences section reads: "Positive: independent deployability per service, team autonomy. Negative: distributed tracing required, operational tooling investment. Risks: data consistency across services if distributed transaction patterns are not established before migration." What makes this Consequences section well-written?
ADR Consequences section vocabulary — what good looks like:
The Consequences section is the most commonly written section in ADRs, but also the one most frequently written poorly — usually by listing only positives. A well-structured consequences section is honest and complete.
Sub-section
What it captures
Example from the exercise
Positive
Benefits that are expected to materialise — the gains that motivated the decision
"Independent deployability per service, team autonomy"
Negative
Accepted costs — certain downsides that the team has explicitly accepted as part of the trade-off
Uncertain outcomes that may or may not materialise — they require monitoring and mitigation planning
"Data consistency across services if distributed transaction patterns are not established"
Common failure modes in Consequences sections:
Positive-only listing: reads as marketing copy, not an honest engineering decision record
Vague negatives: "some operational complexity" — does not help a future reader understand the actual cost
Missing risks: risks that materialise become surprises; risks documented upfront become managed items
Confusing negatives with risks: a negative is certain; a risk is conditional
Vocabulary test: If a team member who was not in the decision meeting reads only the Consequences section, they should understand what was gained, what was sacrificed, and what needs to be monitored — without ambiguity.
4 / 10
An architect writes in an ADR: "The key decision driver is the team's operational capacity — the platform team of three engineers cannot currently operate a distributed Kubernetes-based microservices deployment." What is a decision driver in ADR terminology?
Decision driver vocabulary — what shapes a decision:
Decision drivers are the forces that constrain the solution space. They are not outcomes or people — they are the conditions under which a decision must be made. Understanding what decision drivers are allows you to write Context sections that explain not just what was chosen but what would have needed to be different for the decision to have gone another way.
Driver type
Example
Effect on decision
Team capability constraint
"Team has no Kubernetes expertise"
Rules out Kubernetes-based options regardless of technical merit
Regulatory constraint
"GDPR data residency: data must stay in EU"
Rules out US-only cloud regions and US-owned managed services
Quality attribute requirement
"p99 read latency must be under 50ms"
Eliminates eventual-consistency architectures for the read path
Budget constraint
"Managed database budget capped at $500/month"
Eliminates enterprise managed database tiers
Time constraint
"Must ship before Q3 regulatory deadline"
Favours options requiring less migration effort regardless of ideal technical fit
Key vocabulary distinction:
Decision driver: a force that constrained the option space — existed before the decision
Decision outcome / consequence: a result that follows from the decision — exists after it
Decision maker: the person or body that accepted the decision — irrelevant to future readers who need to understand the reasoning
5 / 10
A staff engineer says: "This proposal needs to go to the ARB for approval before we proceed." A junior engineer asks what the Architecture Review Board does and when proposals typically bypass it. What is the correct explanation?
Architecture Review Board (ARB) vocabulary:
The ARB is a governance body, not a committee that reviews everything. Its value is in ensuring that high-impact, cross-team, or hard-to-reverse architectural decisions receive appropriate scrutiny before commitment. But it must be bypassed for low-impact decisions — otherwise it becomes a bottleneck that slows engineering without adding proportional value.
Decision type
ARB required?
Example
Cross-team system boundary change
Yes
Adding a new public API that three other teams depend on
Platform or technology selection with multi-team impact
Yes
Adopting a new message broker as the company-wide event bus
High blast-radius infrastructure change
Yes
Migrating the primary authentication service to a new identity provider
Low-impact, reversible, single-team decision
No
Switching a team's internal logging library; refactoring a module's internal structure
Spike / proof of concept
No
Building a throwaway prototype to evaluate a new technology before committing
Production incident decision
No (bypass with post-incident ADR)
Emergency service architecture change during a P1 incident; document in ADR retroactively
ARB vocabulary:
Blast radius: the scope of systems and teams impacted if this decision goes wrong
Reversibility: the cost and effort to undo this decision if it turns out to be wrong
Two-way door: reversible decision — can be undone without major cost (Jeff Bezos's term; bypass ARB)
One-way door: irreversible or very costly to reverse — warrants ARB-level scrutiny
6 / 10
Sarah (Lead Architect) sends a Slack message to the team: 'Okay, we're moving forward with the ADR for refactoring the user authentication service. The key thing is that we *must* prioritize performance – our SLAs are critical, and any latency spikes will directly impact user satisfaction. Let's ensure this is clearly articulated in the 'Quality Attributes' section.' Which of the following best describes Sarah's primary concern?
Sarah is focused on ensuring that the ADR addresses crucial quality attributes – specifically performance. While feasibility and brand alignment are important considerations, they aren't directly linked to the immediate impact of a refactoring decision on user experience. The 'Quality Attributes' section of an ADR is where these measurable requirements should be documented, ensuring the team understands what needs to be achieved.
7 / 10
David, a developer reviewing a PR, sees this comment in an ADR: 'Decision Driver: Reducing technical debt across our legacy codebase.' He notes that the ADR doesn't specify *how* this reduction will be achieved. What is the most important implication of this lack of detail?
The 'Decision Driver' in an ADR defines *why* a decision was made. It provides context for subsequent choices within the document, guiding the team towards solutions that address that driver. The ADR itself doesn't dictate implementation; that detail is fleshed out in other sections like 'Proposed Solution' or 'Alternatives Considered'. Simply stating the driver without further elaboration leaves room for misinterpretation.
8 / 10
Maria (Product Manager) is drafting a PR description for an ADR related to migrating to a serverless architecture. She writes: 'This change aims to improve scalability and reduce operational overhead.' What element is Maria *missing* from this description that would strengthen its value in the context of an ADR?
While scalability and reduced operational overhead are outcomes, an ADR needs to articulate *why* those outcomes are desired. The 'Forces' section – which outlines the business or technical drivers behind a decision – is critical. Without it, the ADR lacks context and may be viewed as purely a technical proposal rather than a strategically informed architectural choice.
9 / 10
Ben (Senior Engineer) is participating in a standup meeting and says: 'We're working on an ADR to transition our data pipeline to Kafka. The main reason we're doing this is because our current system can't handle the volume of real-time events, leading to significant delays.' What aspect of the ADR does Ben's statement primarily address?
Ben's statement directly identifies the 'Decision Driver' – the underlying problem or need that justifies the proposed change. In this case, it's the inability of the current system to handle event volume. The ADR will then elaborate on *how* Kafka addresses this driver and what alternatives were considered.
10 / 10
Chloe (Junior Developer) asks a more experienced architect: 'What exactly does the Architecture Review Board (ARB) do when reviewing ADRs?' The architect responds: 'The ARB ensures that proposed architectural changes align with our overall strategic goals and don't create significant technical debt.' What is the *primary* function of the ARB, according to this explanation?
The ARB's role is not simply approval or technical guidance. Its core function is to assess the *strategic alignment* of proposed changes. This means evaluating whether a decision will contribute positively to long-term goals and minimize potential negative consequences (like increased technical debt), ensuring architectural choices are consistent with the company's vision.
What will I learn from the "Architecture Decision Language — Software Architecture Exercises" exercise?
Practice English for ADR writing and architecture governance: ADR field vocabulary (Context vs. Decision vs. Consequences), Status lifecycle, Consequences section quality, decision drivers, and Architecture Review Board vocabulary. 5 advanced exercises.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to use with no account, sign-up, or paywall required.
How many questions are in this exercise?
This set contains 10 multiple-choice questions, each with a detailed explanation shown after you answer.
Do I need to create an account to track my progress?
No account is required. Your progress bar and score reset each time you reload the page, but you can retry the exercise as many times as you like.
Who is this Software Architecture exercise for?
This exercise is built for IT professionals and non-native English speakers who need to read, write, and discuss software architecture topics confidently at work.
What happens if I answer a question incorrectly?
You will see the correct answer highlighted along with a detailed explanation of why it is correct -- so every wrong answer becomes a learning moment, not just a lost point.
Can I retry this exercise?
Yes -- click "Try again" on the results screen at any time to reset your score and go through all the questions again.
How long does this exercise take to complete?
Most learners finish all 10 questions in under 10 minutes, since each question is answered by clicking a single option.
Where can I find more Software Architecture exercises?
See the full Software Architecture exercises hub for more vocabulary drills on this topic.
Is this exercise mobile-friendly?
Yes -- the exercise works on any device with a modern browser, including phones and tablets, with no app download required.