Architecture Decision Records (ADRs) are lightweight documents that capture important architectural and technical decisions along with their context and consequences. They create an institutional memory that helps current and future team members understand why systems were built the way they were. This guide shows engineering managers how to implement ADRs to improve decision quality, reduce repeated debates, and accelerate onboarding.
What Are ADRs and Why They Matter
An Architecture Decision Record is a short document that captures a single architectural decision and its context. The format was popularised by Michael Nygard and typically includes a title, status (proposed, accepted, deprecated, or superseded), context describing the forces at play, the decision itself, and the consequences - both positive and negative. Each ADR is numbered sequentially and stored alongside the codebase it relates to.
Engineering teams make dozens of significant technical decisions every quarter - choosing a database, selecting an API style, deciding on a deployment strategy, or picking a testing approach. Without ADRs, the rationale behind these decisions lives only in the heads of the people who made them. When those people leave, change teams, or simply forget, the organisation loses the context needed to evaluate whether the decision still makes sense.
ADRs also reduce the cost of revisiting decisions. When a new engineer asks 'why did we choose PostgreSQL over DynamoDB?', the ADR provides the answer immediately. Without it, the team either spends time reconstructing the rationale or, worse, re-debates the decision from scratch. ADRs transform institutional knowledge from an oral tradition into a written record.
- Keep ADRs short - one to two pages maximum - to encourage both writing and reading
- Store ADRs in the repository they relate to, making them discoverable alongside the code
- Number ADRs sequentially and never delete them - superseded decisions are marked as such, not removed
- Write ADRs at the time the decision is made, not retroactively, to capture accurate context
- Make ADR creation part of your definition of done for significant technical decisions
ADR Template and Format
The most widely used ADR template includes five sections: Title (a short noun phrase describing the decision), Status (proposed, accepted, deprecated, or superseded), Context (the forces at play - technical, business, political, or social - that motivate the decision), Decision (the change being proposed or adopted, stated in active voice), and Consequences (the resulting impact, including both benefits and trade-offs).
Some teams extend this template with additional sections such as Alternatives Considered (other options that were evaluated and why they were rejected), Participants (who was involved in the decision), and Related ADRs (links to previous decisions that are relevant). Keep extensions minimal - the power of ADRs comes from their simplicity. A template that takes an hour to fill out will not get used.
Write ADRs in plain language that a new team member can understand without deep context. Avoid jargon, define acronyms, and explain the business reasons behind technical choices. The ADR should make sense to someone reading it six months or two years from now, not just to the people in the room when the decision was made.
Implementing ADRs in Your Team
Start small by writing ADRs for new decisions going forward rather than trying to document every historical decision retroactively. Pick a simple template, create a directory in your repository (typically docs/adr or docs/architecture/decisions), and write the first few ADRs yourself as examples. Demonstrating the practice is more effective than mandating it.
Integrate ADRs into your existing development workflow. The most natural integration point is the pull request process - significant architectural decisions should be proposed as ADRs in draft status, reviewed by relevant stakeholders, and merged alongside the implementing code. This ensures decisions are documented at the time they are made and reviewed with the same rigour as code.
Establish lightweight criteria for when an ADR is warranted. Not every decision needs one. A good rule of thumb: write an ADR when the decision is difficult to reverse, when it affects multiple teams or services, when it involves significant trade-offs, or when the same question has been debated more than once. This prevents both under-documentation and documentation fatigue.
Common ADR Pitfalls
The most common failure mode is ADRs that are written but never read. This happens when ADRs are stored in a wiki or document repository that is separate from the codebase. Developers rarely consult external documentation systems when making decisions. Storing ADRs in the code repository, close to the systems they describe, dramatically increases the likelihood that they will be discovered and referenced.
Another pitfall is writing ADRs that document the 'what' without the 'why.' An ADR that states 'we will use Kafka for event streaming' without explaining the context, alternatives considered, and trade-offs involved provides little value. The 'why' is the most important part of an ADR - the 'what' is usually evident from the code itself.
Some teams fall into the trap of requiring consensus before an ADR can be accepted. While input from stakeholders is valuable, requiring universal agreement can paralyse decision-making. Instead, designate a decision owner (usually the tech lead or architect for the relevant area) who is responsible for gathering input, considering alternatives, and making the final call. Document dissenting views in the ADR if they are significant.
Scaling ADRs Across the Organisation
As your organisation grows, you will need ADRs at multiple levels: team-level ADRs for decisions that affect a single service, domain-level ADRs for decisions that span multiple services within a domain, and organisation-level ADRs for company-wide technical standards. Create clear ownership and review processes for each level to avoid confusion about who can make which decisions.
Consider creating an ADR index or search mechanism that spans repositories. When an engineer is making a decision about caching strategy, they should be able to discover that another team already wrote an ADR evaluating Redis versus Memcached. Tools like Backstage, GitHub search, or a simple catalogue page can serve this purpose.
Use ADRs as onboarding material. When a new engineer joins a team, the collection of ADRs tells the story of how the system evolved and why it looks the way it does. This is far more valuable than a static architecture diagram because it captures the reasoning, trade-offs, and constraints that shaped each decision. Encourage new team members to read through the ADRs in their first week.
Key Takeaways
- ADRs capture the context and rationale behind architectural decisions, creating institutional memory
- Keep them short, store them in the code repository, and write them at decision time
- Integrate ADR creation into your pull request and review workflows
- Focus on the 'why' - the rationale and trade-offs are more valuable than the decision itself
- Use ADRs as onboarding material to help new team members understand system evolution
Frequently Asked Questions
- How do you handle ADRs for decisions that turned out to be wrong?
- Never delete or modify the original ADR. Instead, create a new ADR that supersedes the original, documenting what changed - new information, shifting requirements, or lessons learned from implementation. Update the original ADR's status to 'superseded by ADR-XXX.' This preserves the historical record and demonstrates that revisiting decisions based on new evidence is healthy, not a failure.
- Should ADRs require formal approval or review?
- ADRs should be reviewed but not necessarily formally approved. Treat them like code reviews - stakeholders should have the opportunity to comment and suggest changes, but the decision owner makes the final call. For organisation-wide ADRs that set standards across many teams, a more formal review process with explicit sign-off from affected teams is appropriate. The key is to match the review rigour to the decision's blast radius.
- What tools should we use for ADRs?
- Start with plain Markdown files in your code repository. Tools like adr-tools (a command-line utility) can help manage numbering and status updates. For discoverability across repositories, consider indexing ADRs in Backstage or a similar developer portal. Avoid using wikis or separate document management systems - the closer ADRs are to the code, the more likely they are to be maintained and referenced.
- How many ADRs should a team produce per quarter?
- There is no target number - it depends entirely on the volume and significance of decisions being made. A team building a new system from scratch might produce ten to fifteen ADRs in a quarter. A team maintaining a stable system might produce one or two. If your team is making significant architectural decisions without documenting them, you are under-producing. If engineers complain about ADR fatigue, you may be over-documenting trivial choices.
Explore Engineering Manager Templates
Download ADR templates, RFC frameworks, and decision-making toolkits designed to help engineering managers establish robust technical governance.
Learn More