Learn to write Architecture Decision Records (ADRs): decision context, consequences, rejected alternatives, MADR format, and linking decisions to code.
0 / 10 completed
1 / 10
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 / 10
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 / 10
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 / 10
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 / 10
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.
6 / 10
John from the Infrastructure team just posted this comment on your code review:
'This function uses a synchronous HTTP request. We should consider using an asynchronous approach to avoid blocking the main thread and improve responsiveness.'
What does John likely mean when referring to a 'Decision Record' in this context?
John is referencing an ADR – an Architecture Decision Record. An ADR documents technical decisions and their rationale, including trade-offs. The comment highlights a decision about using synchronous vs. asynchronous HTTP requests, demonstrating how ADRs capture these kinds of choices.
7 / 10
You're drafting the description for a new PR that introduces a change to the user authentication flow. You need to include a reference to an existing ADR.
Which of the following is the MOST appropriate way to phrase this within the PR description?
Option 3 is best because it clearly links the PR to the existing ADR without implying a direct implementation. It provides context and directs reviewers to the full decision-making process. The other options are either too prescriptive or subtly suggest that the ADR *is* the code, which isn't its purpose.
8 / 10
During a standup meeting, you're discussing your work on a new API endpoint. A senior developer asks: 'Can you share the rationale behind choosing this specific data format?'
You realize you haven't formally documented this decision. What would be the *most* helpful thing to do next?
While creating a formal ADR is ideal long-term, immediately creating one for a single decision isn't efficient. Explaining your reasoning during the standup provides immediate clarity. Creating a note allows you to capture the key considerations and link it to an existing ADR if applicable – demonstrating awareness of the broader architectural context.
9 / 10
You're reviewing a Slack message from a teammate regarding a performance issue with a microservice:
'We've added caching to reduce the number of database calls. This should improve response times.'
What type of decision record is this situation likely related to?
This message describes a decision to improve performance through caching. While it's a technical decision, it's likely part of an ADR – a formal record of architectural choices and their rationale. A MADR uses Markdown formatting for ease of creation, which aligns with the Slack communication style.
10 / 10
You are updating an ADR to include a rejected alternative that was considered during the design process. What should you document in this section?
It's crucial to document *why* an alternative was rejected. Simply stating it was 'discarded' isn't sufficient; specifying the negative reasons – in this case, performance and scalability – provides valuable context for future decision-makers and demonstrates a thorough evaluation process. This helps avoid repeating mistakes.
What will I practise in "Decision Log Writing — ADR & MADR Vocabulary"?
Learn to write Architecture Decision Records (ADRs): decision context, consequences, rejected alternatives, MADR format, and linking decisions to code.
How many exercises are in this module?
This module has 10 multiple-choice exercises, each with instant feedback and a full explanation of the correct answer.
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.
Do I need to create an account to do these exercises?
No account is required. Just click an option to answer — your score for this session is tracked automatically in the progress bar above.
What happens if I choose the wrong answer?
You'll immediately see which answer was correct, plus a full explanation covering the vocabulary and reasoning behind it — mistakes are where most of the learning happens.
Can I retry the exercises if I want a higher score?
Yes — use the "Try again" button on the results screen to reset and go through all the questions again.
Is my progress saved if I close the page?
No. Progress is tracked only for your current visit; reloading or leaving the page resets the counter. This keeps the exercise simple and account-free.
Where can I find more Knowledge Base Writing exercises?
Browse the full Knowledge Base Writing hub for related drills, or check the "Next up" link below to continue with a connected topic.
How is this different from reading an article on the same topic?
Articles explain vocabulary and concepts in prose; this exercise tests and reinforces that vocabulary through active recall with immediate feedback — the two work best together.
Who writes these exercises?
Every exercise is written by the CoderSlingo team, drawing on real workplace English used in IT roles, then reviewed for accuracy and clarity.