5 exercises — ADR status lifecycle, context sections, decision rationale, honest consequences, and managing historical ADRs. Capture the "why" behind technical decisions.
0 / 28 completed
1 / 28
A team starts writing ADRs. An ADR's Status field currently says "Proposed." What does this mean for the team?
ADR status values track the lifecycle of a decision. The most commonly used statuses are:
Proposed — written, shared, open for review and discussion Accepted — the team has agreed to this decision and will implement it Deprecated — this decision was once accepted but is no longer in effect Superseded by ADR-NNN — this decision was replaced by a newer one (link provided) Rejected — the proposal was discussed and not adopted
Why status matters: ADRs accumulate over time. Without clear status, a future engineer reading ADR-007 can't tell if it reflects current practice or a 3-year-old decision that was replaced. "Superseded by ADR-023" creates a navigable chain of reasoning.
ADR status vocabulary examples: "Status: Proposed" → "Status: Accepted (2026-04-07, agreed by backend team)" "Status: Superseded by ADR-023 (2026-03-15) — we moved from PostgreSQL to CockroachDB for global distribution" "Status: Deprecated — this pattern was abandoned when we moved to microservices"
2 / 28
An ADR's "Context" section reads: "We need to choose a database." A principal engineer rejects this as insufficient. What does a strong context section contain?
The ADR Context section answers: "Why was this decision even necessary? What situation forced us here?"
Weak context: "We need to choose a database."
Strong context: "Our current single-node PostgreSQL instance serves 3 read-heavy microservices. As of Q1 2026, peak read load exceeds the connection limit (500 connections). The services compete for connections, causing intermittent 503 errors. We need a solution that: • Handles at least 2,000 concurrent read connections • Requires no changes to the existing SQL query patterns • Can be deployed within the current infrastructure (AWS RDS or self-managed on EKS) • Fits within the team's existing Postgres expertise"
What context should establish: • The current state (what exists today) • The problem or constraint (why the current state is insufficient) • Specific requirements or constraints (non-negotiables) • Team context (skills, existing tools, budget) • Timing or urgency
ADR context vocabulary: "At the time of this decision, …" "The current approach has the following limitations: …" "The following constraints drive this decision: …" "We require a solution that: …"
3 / 28
An ADR's "Decision" section reads: "We will use PostgreSQL with read replicas." A tech lead says the decision statement is correct but incomplete. What is the most important thing to add?
The Decision section must state both what was decided AND why — otherwise the ADR is just a record of what was done, not a record of the reasoning.
Weak decision statement: "We will use PostgreSQL with read replicas."
Strong decision statement: "We will add 2 read replicas to our existing PostgreSQL instance. This approach was chosen because: • It requires no changes to existing SQL queries (unlike moving to a different database engine) • It is within the team's current operational expertise • It addresses the connection limit issue without a disruptive migration • Estimated cost increase: ~$340/month, within approved infrastructure budget The alternative (migrating to PgBouncer connection pooler) was rejected for now due to query compatibility unknowns (see ADR-Alternatives)."
Why the "why" matters: In 2 years, a new engineer will read this ADR and ask "but why not use connection pooling?" Without the reasoning, they will either repeat the analysis wastefully or make a change that undoes the original decision without understanding its context.
Decision vocabulary: "We will adopt X because: …" "We chose X over Y based on: …" "This decision is driven by: …" "We accept the trade-off of [X] in exchange for [Y]."
4 / 28
An ADR includes a "Consequences" section. An engineer asks: "This section says the decision creates both positive and negative consequences. Should we hide the negative ones?" What is the correct answer?
The Consequences section is what separates a genuine ADR from a post-hoc justification document.
What Consequences should list:
Positive consequences: "This eliminates connection limit errors immediately." "The team can implement this within 1 sprint using existing skills."
Negative consequences / trade-offs accepted: "Read replicas add replication lag — reads from replicas may return data up to 100ms old." "The team must now manage replica health monitoring and failover testing." "This is a temporary solution — at 10x current load, we will need to revisit sharding or a different database."
Why honesty is essential: • Future engineers who encounter the replication lag problem can look back and see: "yes, the team knew about this and accepted it" • It prevents the "but who decided this?" blame game • It enables smarter future decisions: "ADR-012 said this would need revisiting at 10x load — we're there now"
Consequences vocabulary: "The positive effect is: …" "The accepted trade-off is: …" "This introduces risk of: …" "Future teams should be aware that: …" "This decision will need to be revisited when: …"
5 / 28
A team has 47 ADRs. An engineer proposes deleting ADR-003 because "we don't use that technology anymore." The tech lead says this is wrong. What should be done instead?
ADRs are a historical record of decision-making, not a current state documentation system. Deleting or hiding decisions destroys the organisational memory that ADRs are designed to preserve.
Why "Superseded by ADR-031" is the right approach: • It preserves the original reasoning — future engineers can see what was decided AND what replaced it • It creates a chain of decisions — ADR-003 links to ADR-031 which may link to ADR-047 • It shows the evolution of thinking: "we tried approach A, it had problem X, so we moved to approach B" • It prevents re-litigating old decisions — "we already considered this in 2023"
The ADR amendment pattern: 1. Write a new ADR explaining what changed and why 2. Mark the old ADR as "Superseded by ADR-[new number]" 3. Add "Supersedes ADR-[old number]" to the new ADR 4. Add a brief note to the old ADR: "This approach was replaced in 2026 when [reason]."
What to preserve in a supersession note: "Status: Superseded by ADR-031 (2026-04-07). We replaced this approach because the chosen library was abandoned and we moved to [alternative]. See ADR-031 for the current decision."
6 / 28
Reviewer: 'Hey team, I'm looking at this PR and noticed a missing ADR for the new user authentication flow. It seems like we're just blindly implementing the API endpoint without documenting *why* we chose this approach. Project Manager: 'Yeah, that's what I was hoping to discuss with you – are we capturing these architectural decisions properly?'
This scenario highlights a critical aspect of ADRs: they aren't just about stating decisions but documenting the *reasoning* behind them. The Project Manager is raising a concern that the team isn't consistently providing context for architectural choices, which can lead to problems when the code needs to be maintained or modified later. Option A misinterprets the question as purely technical; option B focuses on just adding a comment without addressing the broader need for documentation. Option D is entirely irrelevant.
7 / 28
Sarah: "Hey team, I'm reviewing this PR for the new payment processing service. The developer just implemented the webhook endpoint against the existing MySQL database - no ADR! It seems like we're taking a significant risk by not documenting why we chose MySQL over PostgreSQL or even a NoSQL solution. This feels like a potential disaster waiting to happen."
Mark: "Relax, Sarah. We've been using MySQL for years; it works perfectly fine."
Which of the following is the MOST appropriate response from the team lead regarding Mark's comment?
The correct answer highlights the core purpose of ADRs: to provide justification for technical choices. While Mark's experience with MySQL might be valid, it doesn't negate the need for documented reasoning when introducing new services or making significant changes. The team lead needs to address the *lack* of documentation and guide the developer toward creating an ADR to mitigate potential risks. Options A and B are inaccurate – a lack of ADRs isn't simply about coding standards; it's about architectural risk management. Option D is also incorrect as addressing Sarah's concerns is paramount.
8 / 28
Reviewer: 'Hey team, I'm looking at this PR and noticed a missing ADR for the new user authentication flow. It seems like we're just blindly implementing the API endpoint without documenting *why* we chose this approach. Project Manager: 'Yeah, that's what I was hoping to discuss with you – are we capturing these architectural decisions properly?'
This scenario highlights a critical aspect of ADRs: they aren't just about stating decisions but documenting the *reasoning* behind them. The Project Manager is raising a concern that the team isn't consistently providing context for architectural choices, which can lead to problems when the code needs to be maintained or modified later. Option A misinterprets the question as purely technical; option B focuses on just adding a comment without addressing the broader need for documentation. Option D is entirely irrelevant.
9 / 28
Sarah: "Hey team, I'm reviewing this PR for the new payment processing service. The developer just implemented the webhook endpoint against the existing MySQL database - no ADR! It seems like we're taking a significant risk by not documenting why we chose MySQL over PostgreSQL or even a NoSQL solution. This feels like a potential disaster waiting to happen."
Mark: "Relax, Sarah. We've been using MySQL for years; it works perfectly fine."
Which of the following is the MOST appropriate response from the team lead regarding Mark's comment?
The correct answer highlights the core purpose of ADRs: to provide justification for technical choices. While Mark's experience with MySQL might be valid, it doesn't negate the need for documented reasoning when introducing new services or making significant changes. The team lead needs to address the *lack* of documentation and guide the developer toward creating an ADR to mitigate potential risks. Options A and B are inaccurate – a lack of ADRs isn't simply about coding standards; it's about architectural risk management. Option D is also incorrect as addressing Sarah's concerns is paramount.
10 / 28
Reviewer: 'Hey team, I'm looking at this PR and noticed a missing ADR for the new user authentication flow. It seems like we're just blindly implementing the API endpoint without documenting *why* we chose this approach. Project Manager: 'Yeah, that's what I was hoping to discuss with you – are we capturing these architectural decisions properly?'
This scenario highlights a critical aspect of ADRs: they aren't just about stating decisions but documenting the *reasoning* behind them. The Project Manager is raising a concern that the team isn't consistently providing context for architectural choices, which can lead to problems when the code needs to be maintained or modified later. Option A misinterprets the question as purely technical; option B focuses on just adding a comment without addressing the broader need for documentation. Option D is entirely irrelevant.
11 / 28
Sarah: "Hey team, I'm reviewing this PR for the new payment processing service. The developer just implemented the webhook endpoint against the existing MySQL database - no ADR! It seems like we're taking a significant risk by not documenting why we chose MySQL over PostgreSQL or even a NoSQL solution. This feels like a potential disaster waiting to happen."
Mark: "Relax, Sarah. We've been using MySQL for years; it works perfectly fine."
Which of the following is the MOST appropriate response from the team lead regarding Mark's comment?
The correct answer highlights the core purpose of ADRs: to provide justification for technical choices. While Mark's experience with MySQL might be valid, it doesn't negate the need for documented reasoning when introducing new services or making significant changes. The team lead needs to address the *lack* of documentation and guide the developer toward creating an ADR to mitigate potential risks. Options A and B are inaccurate – a lack of ADRs isn't simply about coding standards; it's about architectural risk management. Option D is also incorrect as addressing Sarah's concerns is paramount.
12 / 28
Reviewer: 'Hey team, I'm looking at this PR and noticed a missing ADR for the new user authentication flow. It seems like we're just blindly implementing the API endpoint without documenting *why* we chose this approach. Project Manager: 'Yeah, that's what I was hoping to discuss with you – are we capturing these architectural decisions properly?'
This scenario highlights a critical aspect of ADRs: they aren't just about stating decisions but documenting the *reasoning* behind them. The Project Manager is raising a concern that the team isn't consistently providing context for architectural choices, which can lead to problems when the code needs to be maintained or modified later. Option A misinterprets the question as purely technical; option B focuses on just adding a comment without addressing the broader need for documentation. Option D is entirely irrelevant.
13 / 28
Sarah: "Hey team, I'm reviewing this PR for the new payment processing service. The developer just implemented the webhook endpoint against the existing MySQL database - no ADR! It seems like we're taking a significant risk by not documenting why we chose MySQL over PostgreSQL or even a NoSQL solution. This feels like a potential disaster waiting to happen."
Mark: "Relax, Sarah. We've been using MySQL for years; it works perfectly fine."
Which of the following is the MOST appropriate response from the team lead regarding Mark's comment?
The correct answer highlights the core purpose of ADRs: to provide justification for technical choices. While Mark's experience with MySQL might be valid, it doesn't negate the need for documented reasoning when introducing new services or making significant changes. The team lead needs to address the *lack* of documentation and guide the developer toward creating an ADR to mitigate potential risks. Options A and B are inaccurate – a lack of ADRs isn't simply about coding standards; it's about architectural risk management. Option D is also incorrect as addressing Sarah's concerns is paramount.
14 / 28
Mark (Senior Developer): "Hey team, I just pushed a change to integrate with Stripe for processing payments. There's no ADR – it feels like we're just copying the example webhook implementation without understanding the potential rate limits or error handling strategies.
Mark is correctly pointing out a deficiency in the ADR process. The 'Consequences' section of an ADR should proactively address potential issues like rate limits or error handling, as he has identified. Option A is the most constructive response – guiding Mark towards completing the necessary documentation to mitigate risks. Options B, C & D are all incorrect approaches.
15 / 28
PR Description: 'Implemented the new user profile API endpoint using REST principles and JSON format. This improves data accessibility for mobile clients. No ADR required.'
The PR description is inadequate because it doesn't explain *why* REST was chosen over alternative approaches like GraphQL. A key purpose of an ADR is to document the reasoning behind technical decisions, particularly when trade-offs are involved. Simply stating that REST improves data accessibility isn't sufficient justification.
16 / 28
David: "I finished implementing the new search functionality today. I used Elasticsearch as the backend and set up a basic API endpoint for querying data. It's working, but I haven't created an ADR yet – I was focused on getting it deployed.
David's lack of an ADR is a significant concern. While deployment is important, documenting the decision-making process – especially regarding technology choices like Elasticsearch – is crucial for maintainability and future changes. Prioritizing the ADR ensures that the team understands the rationale behind the implementation and potential implications.
17 / 28
The API returns a 200 OK response with the following JSON payload: `{"status": "success", "data": {"user_id": 123, "username": "john.doe"}}`. The ADR for this endpoint is missing.
While the API response provides some information, it doesn't explain *why* this specific structure was chosen or what considerations were made regarding potential errors or edge cases. An ADR should document these aspects to ensure robust and maintainable code. The response alone isn't enough; it needs context.
18 / 28
During a standup meeting, Alex mentions implementing a new rate limiter for the API. The team lead asks, 'What's the primary purpose of documenting this decision in an ADR?' Option A focuses on technical details; option B emphasizes potential risks. Which option best reflects the core reason for creating an ADR in this situation?
A To detail the specific algorithms and performance metrics used for the rate limiter implementation.
B To proactively identify and mitigate potential negative consequences, such as impacting user experience or requiring significant operational adjustments.
ADRs aren't just technical specifications; they capture *why* a decision was made. Option B correctly identifies the core purpose: anticipating risks and consequences. The other options represent secondary or less critical aspects of an ADR – detailed implementation isn't the primary reason for documenting, nor is it solely about recording the rationale.
19 / 28
Reviewer Emily comments on a PR: 'This change introduces a new caching layer. While functional, I'm missing an ADR explaining why we chose Redis over Memcached – the performance trade-offs seem significant.' What is the MOST crucial element to add to the ADR in this case?
A A detailed benchmark comparing Redis and Memcached's performance under various load conditions.
B The specific configuration settings for the Redis cache, including memory limits and eviction policies.
The core issue isn't just *that* Redis was chosen; it's the lack of justification. The decision needs to be contextualized – why was Redis deemed appropriate despite potential trade-offs? A performance benchmark directly addresses this question.
20 / 28
Mark (Senior Developer) sends a Slack message: 'Hey team, I've implemented the new user authentication flow using OAuth 2.0 with Auth0. No ADR yet. Just wanted to get this working quickly.' Given this situation, what's the *immediate* next step Mark should take?
A Immediately deploy the change to production.
B Create a brief ADR outlining the key decisions made regarding Auth0 configuration and security considerations.
While speed is important, building an ADR *before* deployment is crucial for maintainability and understanding. A brief ADR will capture essential decisions regarding Auth0 configuration (scopes, callbacks, etc.) and security implications – preventing future issues.
21 / 28
A PR description reads: 'Implemented a new API endpoint for retrieving product details. Utilized GraphQL to enhance data efficiency.' The team lead asks, 'Is this sufficient documentation?' Which statement best describes the *missing* element?
A Details about the authentication scheme used by the GraphQL endpoint.
B A justification for choosing GraphQL over REST, explaining its advantages in terms of data retrieval and flexibility.
The PR description focuses solely on *what* was implemented. An ADR needs to explain *why*. Choosing GraphQL over REST requires a rationale – outlining its benefits like efficient data fetching and schema flexibility is essential for future understanding.
22 / 28
Reviewer Liam comments on a PR: 'This change introduces a new microservice to handle user notifications. It's functional but lacks an ADR detailing the rationale for using Kafka over RabbitMQ – the scalability considerations seem crucial.' What is the primary concern highlighted by Liam's comment regarding the missing ADR?
The core issue is that an ADR should document the 'why' behind architectural decisions. Liam specifically points out a crucial consideration – scalability – that was not addressed. The other options represent misinterpretations of what ADRs are for; they focus on process or immediate needs rather than strategic justification.
23 / 28
During a Slack conversation about implementing a new feature flag system, Developer Anya writes: 'Just added the feature flag toggle. It's working! No ADR needed – just a quick change.' What is the most appropriate response from the team lead to Anya's message?
An ADR isn't just for large changes. It's a standard practice to document the *reasoning* behind even seemingly small decisions like feature flags. Option 0 correctly emphasizes the importance of documenting decision-making processes, reinforcing the core purpose of ADRs.
24 / 28
Reviewer Ben comments on a PR: 'This change introduces a new data transformation pipeline. It's working as expected, but I'm missing an ADR outlining the trade-offs between using a batch processing approach versus real-time streaming for this particular use case.' Which of the following best explains Ben's concern regarding the absence of an ADR?
The core purpose of an ADR is to capture the reasoning behind architectural decisions. Ben's comment highlights that simply having working code isn't enough; a key element is understanding *why* a particular approach was chosen and anticipating potential future impacts or alternative solutions. Option A misinterprets the ADR's role, while options B and C trivialize the importance of documenting design choices.
25 / 28
Slack message from Developer Chloe: 'Just finished implementing the new API endpoint for generating reports. It's using a NoSQL database and returning JSON data. No ADR needed – it's straightforward!' Considering the potential long-term implications of this decision, what is the MOST critical reason why an ADR should have been created?
ADRs are fundamentally about documenting *why* decisions were made. While deployment instructions and API design are important, the primary focus of an ADR is to capture the reasoning behind architectural choices – in this case, selecting NoSQL over a relational database. This foresight helps avoid potential problems down the line.
26 / 28
PR Description: 'Implemented a new microservice for handling user session management. Utilized JWT (JSON Web Tokens) for authentication and authorization.' The team lead asks, 'Is this sufficient documentation to guide future development?' Which statement best describes the situation?
While a PR description can provide details about implemented technology, it doesn't capture the 'why'. An ADR would have documented the reasons for selecting JWT – likely related to security, scalability, or ease of integration. Simply stating that JWT was used doesn't convey the critical context needed for future development and potential risks.
27 / 28
During a standup meeting, Developer David states: 'I've implemented a new caching layer using Redis. It's working fine.' The team lead asks, 'What information should be included in an ADR for this change?' Which of the following options represents the MOST appropriate response from David?
An ADR should articulate the *reasoning* behind architectural decisions. David needs to document the rationale for choosing Redis – this likely involves comparing it with alternatives (like Memcached), considering factors like performance characteristics, data structures, and operational complexity. Simply stating that Redis was used is insufficient.
28 / 28
Reviewer Fiona finds a PR with the following description: 'Implemented a new API endpoint for processing image uploads. Utilized S3 storage.' The team lead asks, 'What's missing from this documentation?' Which of the following is the MOST crucial element to include in an ADR for this change?
The core value of an ADR is to document the *reasoning* behind architectural choices. While the S3 bucket names are important for operational details, they don't explain *why* S3 was selected. The team lead's question directly targets this lack of justification – a proper ADR would have addressed the trade-offs involved in choosing S3 over other storage solutions.
What does the "Architecture Decision Records (ADRs) — Documentation Types Exercises" exercise cover?
Practice writing Architecture Decision Records: status values, context sections, decision rationale, consequences, and managing ADR history. 5 exercises for architects and senior engineers.
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.
How many questions are in "Architecture Decision Records (ADRs) — Documentation Types Exercises"?
This exercise has 28 questions. Each one gives instant feedback with an explanation, so you can see exactly why an answer is right or wrong.
Do I need to create an account to save my progress?
No account is required. The progress bar and score are tracked in your browser for the current session -- the exercise is designed to be a quick, repeatable drill rather than something you resume later.
What happens if I get an answer wrong?
You'll see the correct answer highlighted immediately, along with a short explanation of why it's correct. Wrong answers aren't penalized beyond your score, and you can keep going through every question.
How is this exercise different from reading an article?
Articles explain vocabulary and concepts through prose, while exercises like this one are interactive drills -- multiple-choice questions -- that test and reinforce your recall of specific terms and phrasing.
Can I retry this exercise?
Yes -- use the "Try again" button on the results screen to reset your score and go through all the questions again from the start.
Where can I find more Documentation Types exercises?
Browse the full Documentation Types hub for related drills, or check the site-wide exercises index for other IT English topics.
Is this exercise suitable for beginners?
This exercise assumes basic familiarity with IT terminology. If a term feels unfamiliar, check the site Glossary for a plain-English definition before attempting the questions.
How often is new content like this published?
New exercises are added regularly across all categories, alongside new vocabulary sets and articles. Check back on the exercises hub to see what's new.