Say it like this
- We should write an ADR for this decision
- Let me check the ADR for that architectural choice
- This ADR documents the reasoning behind our microservices approach
Use it at work
Proposing a decision
- I'll write an ADR for switching to Kafka.
- Can you review my ADR before Thursday's architecture meeting?
Explaining the past
- There's an ADR explaining why we chose Postgres.
- Check the ADR before you change the auth flow.
In a code review
- This is a big change. Could you add an ADR?
- Please link the ADR in the PR description.
Don't say this
ADRs document decisions already made, not the decision-making process itself. They record the outcome and reasoning.
Don't mix it up
| Term | What it is | Who writes or uses it | When |
|---|---|---|---|
| ADR | Records one architecture decision and why | Engineers | After a decision is made |
| RFC | Proposes an idea for feedback | Engineers | Before a decision |
| design doc | Describes how a system will be built | Engineers | Before or during building |
Practice
Try it
4 quick exercises
1. Your team chose to use Kubernetes for orchestration. What do you do next?
2. The _______ documents why we decided to use event-driven architecture instead of request-response.
3. Which sentence uses ADR incorrectly?
4. Rewrite this using ADR: 'We made a decision to use PostgreSQL instead of MongoDB because it is better for structured data, and we should write something down about this choice so people know why we chose it.'
Say it out loud
Phrase 1 of 3
"We should write an ADR for this decision"
We don't save your recording. The word check uses your browser's speech recognition.
More about ADR
Real examples(3)
- in a design meeting
"Before we move forward, we need to create an ADR explaining why we're switching to a serverless architecture."
- in a code review
"The ADR clearly states that we chose REST over GraphQL for API simplicity, so this implementation is correct."
- in onboarding a new developer
"Read the ADRs in our docs folder to understand the architectural decisions made over the past two years."
More mistakes(2)
Handle with care. ADR is often confused with decision logs or design documents. ADRs specifically document the reasoning behind architectural choices, not all decisions. Do not use ADR for minor implementation choices.
- ✕I wrote an ADR for the bug fix we shipped today.✓I wrote an ADR for our decision to refactor the authentication module.
ADRs are for significant architectural or technical decisions, not routine bug fixes or minor code changes.
- ✕Our ADR says we should use microservices, so let us do it.✓Our ADR documents why we chose microservices for this system based on our scalability requirements.
ADRs explain the reasoning and context, not just the decision itself. They should help others understand the trade-offs.
Other forms(2)
- ADR noun
"The ADR for our caching strategy is documented in the architecture folder."
- ADRs noun
"Our team reviews ADRs during architecture discussions."
Often used with(5)
- write an ADR · Used when creating a new architecture decision record
- document in an ADR · Describing the act of recording a decision formally
- ADR proposes · When referring to the suggestion or solution within an ADR
- follow the ADR · Implementing the decision documented in an ADR
- review the ADRs · Examining existing architecture decision records
Similar words(3)
- design decision log · Broader term for documenting design choices; ADR is more specific and structured
- decision record · General term; ADR specifically focuses on architectural decisions
- architecture documentation · Broader category that may include ADRs along with other documentation
Questions(5)
- What does ADR stand for?
- ADR stands for Architecture Decision Record. It is a document that captures an important architectural decision made by a software development team, including the context, the options considered, and the reasoning behind the choice.
- What should I include in an ADR?
- A typical ADR includes: Title (the decision), Status (proposed, accepted, deprecated), Context (the problem or situation), Decision (what was chosen), Consequences (trade-offs and implications), and sometimes Alternatives (options that were considered). The structure may vary between teams.
- When should we write an ADR?
- Write an ADR when making significant architectural or technical decisions that affect the system design, such as choosing a database technology, adopting a new framework, switching to microservices, or changing your authentication approach. Do not write ADRs for minor implementation details or routine bug fixes.
- How long should an ADR be?
- ADRs should be concise but complete, typically one to three pages. The goal is to be clear and informative without unnecessary length. Include enough detail to explain the reasoning to someone unfamiliar with the decision.
- Are ADRs formal or informal?
- ADRs are semi-formal documents. They are more structured than casual chat messages but less formal than comprehensive technical specifications. They balance clarity with brevity, making them practical for busy teams.
