Architecture Decision Record (ADR) Vocabulary
Practice ADR vocabulary: capturing context, status lifecycle, significant decisions, superseding ADRs, and the MADR format.
0 / 25 completed
1 / 25
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 / 25
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 / 25
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 / 25
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 / 25
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.
6 / 25
Reviewer: 'I'm seeing a lot of boilerplate in this PR. Could you justify the decision to use this specific logging library instead of our standard one? It seems like we're adding unnecessary complexity here."The question centers around the core purpose of an ADR. The reviewer's comment highlights a situation where a developer needs to provide a 'justification' for their technical choices. An ADR provides that justification—it's not simply stating what was done but *why* it was done, detailing the reasoning and potential trade-offs involved in architectural decisions like library selection. Option A is incorrect because an account balance isn't relevant; option C misinterprets the reviewer's comment as a request for justification, while option D describes a vague communication style that doesn't align with ADR principles.
7 / 25
PR Description:
Subject: Implement User Authentication API
We're implementing a new user authentication API endpoint. This ADR outlines the decision to use JWT (JSON Web Tokens) for session management instead of our legacy cookie-based system. We believe JWT offers improved security and scalability.
Reviewer Comment: 'I appreciate the clarity, but can you elaborate on why we've chosen JWT over cookies? The team is concerned about potential key rotation challenges with JWT in a high-traffic environment.'This question assesses understanding of how ADRs should address concerns raised during code review. The correct answer highlights that a good ADR proactively anticipates potential issues like key rotation and explicitly justifies technical decisions. Options A and C misrepresent the role of an ADR – it's not just about stating the decision, but also explaining the rationale and addressing potential objections. Option D is too general; the PR *does* contain justification, though perhaps more could be added.
8 / 25
Reviewer: 'I'm reviewing this ADR for the new payment processing flow. The description mentions we're opting for a microservice architecture to handle transactions. But I'm seeing no discussion around potential data consistency issues – specifically, eventual consistency versus strong consistency in a system handling financial operations. Shouldn't we have addressed that explicitly?'This question tests understanding of the *purpose* of an ADR. While scalability and high availability are related to architectural decisions, a strong ADR must explicitly address potential trade-offs like consistency models – especially in critical areas like payments. The reviewer is rightly pointing out that merely stating 'we're using microservices' doesn't cover the fundamental technical implications for data integrity. The correct answer emphasizes that ADRs need to be *comprehensive* and proactively identify and discuss potential risks.
9 / 25
Reviewer: 'Okay, the ADR for this new API gateway is well-written. However, I'm noticing you've decided to use gRPC for inter-service communication instead of REST. Can you explain the rationale behind that choice? We haven't used gRPC before, and there are concerns about increased complexity and a steeper learning curve.'This question tests understanding beyond just the *technical* benefits of gRPC. A good ADR needs to justify architectural choices with a full consideration of the trade-offs – in this case, acknowledging the increased complexity and operational costs alongside performance improvements. Simply stating 'better performance' isn't sufficient justification for a significant change like adopting a new protocol; the team's lack of experience is also a critical factor to address.
10 / 25
PR Description:
Subject: Migrate to PostgreSQL Database
The team has decided to migrate our core application database from MySQL to PostgreSQL. This ADR outlines the decision based on PostgreSQL's superior support for JSON data types and its robust features for handling large datasets. We anticipate this will improve query performance and reduce storage costs in the long run.
Reviewer Comment: 'While I understand the benefits of PostgreSQL, I'm seeing no discussion about potential compatibility issues with our existing ORM (Object-Relational Mapper). Are we planning a full migration or a gradual switchover? Also, what's our rollback strategy if things go wrong?'This question tests understanding of a key aspect of ADRs: proactively addressing potential risks. The correct answer acknowledges that the ADR discusses migration strategy and risk mitigation. Options A and B misrepresent the purpose of an ADR—it's not just about stating decisions but also outlining how those decisions will be implemented and managed, including contingency plans. Option C highlights a crucial missing element – testing – and option D focuses on a less critical concern (user experience) that should have been addressed within the broader migration plan.
11 / 25
Reviewer: 'I'm seeing a lot of boilerplate in this PR. Could you justify the decision to use this specific logging library instead of our standard one? It seems like we're adding unnecessary complexity here."The question centers around the core purpose of an ADR. The reviewer's comment highlights a situation where a developer needs to provide a 'justification' for their technical choices. An ADR provides that justification—it's not simply stating what was done but *why* it was done, detailing the reasoning and potential trade-offs involved in architectural decisions like library selection. Option A is incorrect because an account balance isn't relevant; option C misinterprets the reviewer's comment as a request for justification, while option D describes a vague communication style that doesn't align with ADR principles.
12 / 25
PR Description:
Subject: Implement User Authentication API
We're implementing a new user authentication API endpoint. This ADR outlines the decision to use JWT (JSON Web Tokens) for session management instead of our legacy cookie-based system. We believe JWT offers improved security and scalability.
Reviewer Comment: 'I appreciate the clarity, but can you elaborate on why we've chosen JWT over cookies? The team is concerned about potential key rotation challenges with JWT in a high-traffic environment.'This question assesses understanding of how ADRs should address concerns raised during code review. The correct answer highlights that a good ADR proactively anticipates potential issues like key rotation and explicitly justifies technical decisions. Options A and C misrepresent the role of an ADR – it's not just about stating the decision, but also explaining the rationale and addressing potential objections. Option D is too general; the PR *does* contain justification, though perhaps more could be added.
13 / 25
Reviewer: 'I'm reviewing this ADR for the new payment processing flow. The description mentions we're opting for a microservice architecture to handle transactions. But I'm seeing no discussion around potential data consistency issues – specifically, eventual consistency versus strong consistency in a system handling financial operations. Shouldn't we have addressed that explicitly?'This question tests understanding of the *purpose* of an ADR. While scalability and high availability are related to architectural decisions, a strong ADR must explicitly address potential trade-offs like consistency models – especially in critical areas like payments. The reviewer is rightly pointing out that merely stating 'we're using microservices' doesn't cover the fundamental technical implications for data integrity. The correct answer emphasizes that ADRs need to be *comprehensive* and proactively identify and discuss potential risks.
14 / 25
Reviewer: 'Okay, the ADR for this new API gateway is well-written. However, I'm noticing you've decided to use gRPC for inter-service communication instead of REST. Can you explain the rationale behind that choice? We haven't used gRPC before, and there are concerns about increased complexity and a steeper learning curve.'This question tests understanding beyond just the *technical* benefits of gRPC. A good ADR needs to justify architectural choices with a full consideration of the trade-offs – in this case, acknowledging the increased complexity and operational costs alongside performance improvements. Simply stating 'better performance' isn't sufficient justification for a significant change like adopting a new protocol; the team's lack of experience is also a critical factor to address.
15 / 25
PR Description:
Subject: Migrate to PostgreSQL Database
The team has decided to migrate our core application database from MySQL to PostgreSQL. This ADR outlines the decision based on PostgreSQL's superior support for JSON data types and its robust features for handling large datasets. We anticipate this will improve query performance and reduce storage costs in the long run.
Reviewer Comment: 'While I understand the benefits of PostgreSQL, I'm seeing no discussion about potential compatibility issues with our existing ORM (Object-Relational Mapper). Are we planning a full migration or a gradual switchover? Also, what's our rollback strategy if things go wrong?'This question tests understanding of a key aspect of ADRs: proactively addressing potential risks. The correct answer acknowledges that the ADR discusses migration strategy and risk mitigation. Options A and B misrepresent the purpose of an ADR—it's not just about stating decisions but also outlining how those decisions will be implemented and managed, including contingency plans. Option C highlights a crucial missing element – testing – and option D focuses on a less critical concern (user experience) that should have been addressed within the broader migration plan.
16 / 25
Reviewer: 'I'm seeing a lot of boilerplate in this PR. Could you justify the decision to use this specific logging library instead of our standard one? It seems like we're adding unnecessary complexity here."The question centers around the core purpose of an ADR. The reviewer's comment highlights a situation where a developer needs to provide a 'justification' for their technical choices. An ADR provides that justification—it's not simply stating what was done but *why* it was done, detailing the reasoning and potential trade-offs involved in architectural decisions like library selection. Option A is incorrect because an account balance isn't relevant; option C misinterprets the reviewer's comment as a request for justification, while option D describes a vague communication style that doesn't align with ADR principles.
17 / 25
PR Description:
Subject: Implement User Authentication API
We're implementing a new user authentication API endpoint. This ADR outlines the decision to use JWT (JSON Web Tokens) for session management instead of our legacy cookie-based system. We believe JWT offers improved security and scalability.
Reviewer Comment: 'I appreciate the clarity, but can you elaborate on why we've chosen JWT over cookies? The team is concerned about potential key rotation challenges with JWT in a high-traffic environment.'This question assesses understanding of how ADRs should address concerns raised during code review. The correct answer highlights that a good ADR proactively anticipates potential issues like key rotation and explicitly justifies technical decisions. Options A and C misrepresent the role of an ADR – it's not just about stating the decision, but also explaining the rationale and addressing potential objections. Option D is too general; the PR *does* contain justification, though perhaps more could be added.
18 / 25
Reviewer: 'I'm reviewing this ADR for the new payment processing flow. The description mentions we're opting for a microservice architecture to handle transactions. But I'm seeing no discussion around potential data consistency issues – specifically, eventual consistency versus strong consistency in a system handling financial operations. Shouldn't we have addressed that explicitly?'This question tests understanding of the *purpose* of an ADR. While scalability and high availability are related to architectural decisions, a strong ADR must explicitly address potential trade-offs like consistency models – especially in critical areas like payments. The reviewer is rightly pointing out that merely stating 'we're using microservices' doesn't cover the fundamental technical implications for data integrity. The correct answer emphasizes that ADRs need to be *comprehensive* and proactively identify and discuss potential risks.
19 / 25
Reviewer: 'Okay, the ADR for this new API gateway is well-written. However, I'm noticing you've decided to use gRPC for inter-service communication instead of REST. Can you explain the rationale behind that choice? We haven't used gRPC before, and there are concerns about increased complexity and a steeper learning curve.'This question tests understanding beyond just the *technical* benefits of gRPC. A good ADR needs to justify architectural choices with a full consideration of the trade-offs – in this case, acknowledging the increased complexity and operational costs alongside performance improvements. Simply stating 'better performance' isn't sufficient justification for a significant change like adopting a new protocol; the team's lack of experience is also a critical factor to address.
20 / 25
PR Description:
Subject: Migrate to PostgreSQL Database
The team has decided to migrate our core application database from MySQL to PostgreSQL. This ADR outlines the decision based on PostgreSQL's superior support for JSON data types and its robust features for handling large datasets. We anticipate this will improve query performance and reduce storage costs in the long run.
Reviewer Comment: 'While I understand the benefits of PostgreSQL, I'm seeing no discussion about potential compatibility issues with our existing ORM (Object-Relational Mapper). Are we planning a full migration or a gradual switchover? Also, what's our rollback strategy if things go wrong?'This question tests understanding of a key aspect of ADRs: proactively addressing potential risks. The correct answer acknowledges that the ADR discusses migration strategy and risk mitigation. Options A and B misrepresent the purpose of an ADR—it's not just about stating decisions but also outlining how those decisions will be implemented and managed, including contingency plans. Option C highlights a crucial missing element – testing – and option D focuses on a less critical concern (user experience) that should have been addressed within the broader migration plan.
21 / 25
Reviewer: 'I'm seeing a lot of boilerplate in this PR. Could you justify the decision to use this specific logging library instead of our standard one? It seems like we're adding unnecessary complexity here."The question centers around the core purpose of an ADR. The reviewer's comment highlights a situation where a developer needs to provide a 'justification' for their technical choices. An ADR provides that justification—it's not simply stating what was done but *why* it was done, detailing the reasoning and potential trade-offs involved in architectural decisions like library selection. Option A is incorrect because an account balance isn't relevant; option C misinterprets the reviewer's comment as a request for justification, while option D describes a vague communication style that doesn't align with ADR principles.
22 / 25
PR Description:
Subject: Implement User Authentication API
We're implementing a new user authentication API endpoint. This ADR outlines the decision to use JWT (JSON Web Tokens) for session management instead of our legacy cookie-based system. We believe JWT offers improved security and scalability.
Reviewer Comment: 'I appreciate the clarity, but can you elaborate on why we've chosen JWT over cookies? The team is concerned about potential key rotation challenges with JWT in a high-traffic environment.'This question assesses understanding of how ADRs should address concerns raised during code review. The correct answer highlights that a good ADR proactively anticipates potential issues like key rotation and explicitly justifies technical decisions. Options A and C misrepresent the role of an ADR – it's not just about stating the decision, but also explaining the rationale and addressing potential objections. Option D is too general; the PR *does* contain justification, though perhaps more could be added.
23 / 25
Reviewer: 'I'm reviewing this ADR for the new payment processing flow. The description mentions we're opting for a microservice architecture to handle transactions. But I'm seeing no discussion around potential data consistency issues – specifically, eventual consistency versus strong consistency in a system handling financial operations. Shouldn't we have addressed that explicitly?'This question tests understanding of the *purpose* of an ADR. While scalability and high availability are related to architectural decisions, a strong ADR must explicitly address potential trade-offs like consistency models – especially in critical areas like payments. The reviewer is rightly pointing out that merely stating 'we're using microservices' doesn't cover the fundamental technical implications for data integrity. The correct answer emphasizes that ADRs need to be *comprehensive* and proactively identify and discuss potential risks.
24 / 25
Reviewer: 'Okay, the ADR for this new API gateway is well-written. However, I'm noticing you've decided to use gRPC for inter-service communication instead of REST. Can you explain the rationale behind that choice? We haven't used gRPC before, and there are concerns about increased complexity and a steeper learning curve.'This question tests understanding beyond just the *technical* benefits of gRPC. A good ADR needs to justify architectural choices with a full consideration of the trade-offs – in this case, acknowledging the increased complexity and operational costs alongside performance improvements. Simply stating 'better performance' isn't sufficient justification for a significant change like adopting a new protocol; the team's lack of experience is also a critical factor to address.
25 / 25
PR Description:
Subject: Migrate to PostgreSQL Database
The team has decided to migrate our core application database from MySQL to PostgreSQL. This ADR outlines the decision based on PostgreSQL's superior support for JSON data types and its robust features for handling large datasets. We anticipate this will improve query performance and reduce storage costs in the long run.
Reviewer Comment: 'While I understand the benefits of PostgreSQL, I'm seeing no discussion about potential compatibility issues with our existing ORM (Object-Relational Mapper). Are we planning a full migration or a gradual switchover? Also, what's our rollback strategy if things go wrong?'This question tests understanding of a key aspect of ADRs: proactively addressing potential risks. The correct answer acknowledges that the ADR discusses migration strategy and risk mitigation. Options A and B misrepresent the purpose of an ADR—it's not just about stating decisions but also outlining how those decisions will be implemented and managed, including contingency plans. Option C highlights a crucial missing element – testing – and option D focuses on a less critical concern (user experience) that should have been addressed within the broader migration plan.
Frequently Asked Questions
What does the "Architecture Decision Record (ADR) Vocabulary" exercise cover?
Practice ADR vocabulary: capturing context, status lifecycle, significant decisions, superseding ADRs, and the MADR format.
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 Record (ADR) Vocabulary"?
This exercise has 25 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.