Teams use ADRs to document choices such as selecting a database technology, choosing between a monolith or microservices architecture, deciding on an authentication strategy, or adopting a specific framework.
This guide explains when you should write an ADR, how to structure it, and what makes a good ADR.
When Should You Write an ADR?
Not every technical decision requires an ADR. They are most useful for decisions that significantly affect the architecture of the system, introduce long-term constraints, involve multiple alternatives, or require explanation for future team members.
Typical ADR topics include:
- Choosing a database technology
- Selecting a messaging system
- Deciding between REST or GraphQL
- Choosing a frontend framework
- Introducing event-driven architecture
- Deciding between monolith vs microservices
- Defining API contracts (REST, GraphQL, gRPC)
If a decision might raise the question "Why did we choose this?" in the future, it is usually a good candidate for an ADR.
The Basic Structure of an ADR
Most Architecture Decision Records follow a simple structure consisting of a few key sections.
Title
The title should clearly describe the decision being made. Example: Use PostgreSQL as the primary database.
Status
The status indicates the lifecycle of the decision — typically Proposed, Accepted, Deprecated, or Superseded. This allows teams to track whether a decision is still relevant or has been replaced.
Context
The context describes the problem or situation that led to the decision. It should explain the technical background and constraints — what problem are you solving, what limitations exist, what requirements must the solution satisfy.
Decision
A short, direct statement of what was chosen. The goal is not to explain everything here but simply to record the final choice. Example: The system will use PostgreSQL as the primary relational database.
Alternatives
A brief description of the other approaches that were considered and why they were not selected. Listing alternatives helps future developers understand why the chosen solution was preferred and prevents relitigating the same debate.
Consequences
The impact of the decision — both positive and negative. For example: strong relational model and good tooling on the upside; requires database administration and scaling complexity on the downside.
This is one way to structure an ADR — not the only way. Different formats exist (Nygard, MADR, Y-Statement) and teams adapt the structure to fit their needs. Some add a dedicated Problem Statement section separate from Context. Others include Assumptions as explicit, trackable items. The sections above represent a solid, widely-used baseline to start from.
The Writing Process
-
Write it when the decision happens
The best time to write an ADR is while the discussion is still fresh. Waiting weeks or months means losing the reasoning that made the decision obvious at the time.
-
Involve the right people early
An ADR is not just a personal note — it reflects a shared commitment. Draft it collaboratively with the team members who were part of the decision, or circulate a draft for comment before marking it accepted.
-
Start with "Proposed", not "Accepted"
Mark the ADR as Proposed initially. This signals that the decision is under discussion and invites feedback. Move it to Accepted once there is alignment.
-
Keep it short and focused
Resist the urge to document everything. An ADR is not a design document. If the context section is becoming very long, that is usually a sign the scope is too broad — consider splitting into multiple records.
-
Revisit status as circumstances change
When assumptions break or a decision is superseded, update the status rather than deleting the record. Preserving the history is one of the core values of ADRs.
Common Mistakes When Writing ADRs
- Writing ADRs too late. ADRs should ideally be written when the decision is made, not months later when context has already faded.
- Making ADRs too long. ADRs should be concise. The goal is to capture reasoning, not to write full architecture documentation.
- Not documenting alternatives. If alternatives are missing, future developers may repeat the same discussions without knowing what was already considered.
- Forgetting to update ADR status. Over time some decisions become outdated. Updating the status keeps the documentation accurate and trustworthy.
ADR Templates and Examples
To make writing ADRs easier, many teams use a predefined template. We offer free templates in Nygard, MADR, and Y-Statement formats — download them in Markdown or PDF.
ADR Templates
Download free ADR templates in Nygard, MADR, and Y-Statement formats.
To see what a fully filled-out ADR looks like in practice, we've put together a concrete example showing how ReflectRally structures an architectural decision.
ADR Example
See a complete ADR as structured in ReflectRally, covering a real-world technology decision.
Managing ADRs in Teams
Many teams start by storing ADRs as Markdown files in their repositories. While this works well for small projects, it can become harder to manage as the number of decisions grows.
Tools like ReflectRally help teams manage ADRs collaboratively by providing structured ADR creation, decision history, collaboration features, and centralized decision tracking — making it easier to keep architectural knowledge accessible to the whole team.
Conclusion
Architecture Decision Records are a lightweight but powerful practice for documenting important technical decisions. By capturing the context, the decision, and its consequences, ADRs help teams maintain architectural clarity over time.
Whether you manage them in Markdown files or in a dedicated tool, consistently writing ADRs ensures that important architectural knowledge is preserved for the future.