When to Write an ADR
What you'll learn: You'll discover which technical decisions deserve formal documentation as Architecture Decision Records.
Not every decision needs an ADR. Writing too many creates noise; writing too few leaves critical context undocumented. The key is recognizing which decisions have lasting impact on your system's shape and direction.
Decisions That Warrant an ADR
Structural Changes
If a decision affects how major components relate to each other, write an ADR. Examples include:
- Moving from a monolith to microservices
- Introducing an event-driven architecture
- Changing your data storage layer's organization
- Adopting a new deployment model
Think of it this way: If the decision changes the "skeleton" of your system, it deserves documentation.
Technology Choices
Selecting technologies with long-term consequences requires an ADR:
- Choosing a primary programming language or framework
- Adopting a database system
- Selecting a message queue or caching solution
- Committing to a cloud provider
These choices create technical debt if reversed, so documenting the "why" becomes crucial.
Significant Trade-offs
When you make a decision that explicitly accepts one disadvantage to gain an advantage elsewhere, document it:
- Choosing eventual consistency over strong consistency for performance
- Accepting increased complexity for better scalability
- Trading development speed for runtime efficiency
The ADR captures what you knew at decision time and what you considered acceptable.
What Doesn't Need an ADR
Skip ADRs for routine implementation details, reversible choices, or decisions limited to a single component's internals. Not every technical choice is architectural.
Key Takeaway: Write an ADR when a decision has structural impact, involves significant technology choices, or represents an important trade-off that future engineers will need to understand and potentially revisit.