Technical Architecture Decision Records That Last

Why Architecture Decisions Need a Paper Trail

Michael Nygard introduced Architecture Decision Records in 2011 as a lightweight method for capturing significant technical decisions. The format has since been adopted by organizations including Spotify, ThoughtWorks, and the UK Government Digital Service. The core insight is simple: decisions are only useful if future engineers can understand why they were made, not just what was decided.

Without ADRs, teams repeatedly revisit settled decisions because no one remembers the context. A 2024 survey by the Software Engineering Institute found that engineering teams spend an average of 3.2 hours per week relitigating past architectural choices due to missing documentation. That time compounds across team members and years.

ADRs also protect against hindsight bias. When a system encounters problems, it is tempting to blame the original architecture without understanding the constraints under which it was designed. A well-written ADR captures those constraints -- budget limitations, team expertise, time pressure, regulatory requirements -- making it clear whether the original decision was sound given what was known at the time.

The ADR Format and Writing Process

The standard ADR format includes five sections: Title, Status, Context, Decision, and Consequences. The Title is a short noun phrase like 'Use PostgreSQL for transaction data.' Status tracks whether the decision is proposed, accepted, deprecated, or superseded. Context describes the situation and forces at play. Decision states what was decided. Consequences list the results, both positive and negative.

The Context section is the most important and most frequently underwritten. It should answer three questions: What problem are we solving? What constraints are we working within? What alternatives did we consider and why did we reject them? A context section that says 'We need a database' is useless. One that explains the query patterns, consistency requirements, team expertise, and budget constraints gives future readers everything they need.

Write ADRs at the time of the decision, not afterward. Memory degrades rapidly, and the nuances that drove the choice -- a conversation with a vendor, a benchmark result, a constraint from the security team -- are lost within weeks. ThoughtWorks recommends treating ADR creation as a required step in the architecture review process, just like code review is a required step in the development process.

When to Write an ADR

Not every technical choice deserves an ADR. Reserve them for decisions that are costly to reverse, affect multiple teams or services, or establish patterns that other decisions will follow. Choosing a primary database, selecting an API protocol, defining a service communication pattern, or establishing an authentication strategy all qualify. Choosing a date formatting library does not.

A useful heuristic from the Spotify engineering blog: if a decision would require more than one sprint to reverse, it warrants an ADR. This threshold captures infrastructure choices, data model designs, and integration patterns while excluding routine implementation decisions that can be changed in a pull request.

Organizational decisions also belong in the ADR log. The choice to adopt trunk-based development, to require 90% test coverage for critical services, or to use feature flags for all production deployments are architectural in nature even though they do not involve technology selection. These decisions shape how the team works and are just as prone to being forgotten or questioned as technology choices.

Maintaining ADRs Over Time

ADRs are immutable once accepted -- they represent a point-in-time decision. When a decision is superseded, create a new ADR that references the original and explains what changed. Update the status of the original to 'Superseded by ADR-047' so readers can follow the chain. This preserves the historical record while directing current readers to the active decision.

Store ADRs in the repository they affect, typically in a docs/adr or docs/architecture/decisions directory. This keeps decisions close to the code they govern and ensures they are versioned alongside the codebase. Teams using monorepos can maintain a single ADR directory. Teams with multiple repositories may need a central ADR repository for cross-cutting decisions.

Review the ADR backlog quarterly. Identify decisions that are no longer relevant because the system has changed, decisions that should be revisited because the original constraints no longer apply, and gaps where significant decisions were made without documentation. GitHub's engineering team reports that quarterly ADR reviews surfaced an average of four undocumented decisions per team per quarter during their first year of adoption.

Building an ADR Culture in Engineering Teams

Adopting ADRs requires cultural change, not just a template. Engineers accustomed to making decisions in Slack threads or whiteboard sessions need a reason to invest time in documentation. The most effective incentive is demonstrating value -- when a new team member reads an ADR and immediately understands a design choice that would have taken hours of conversation to explain, the format sells itself.

Start with a lightweight tool like adr-tools, a command-line utility that generates ADR files from a template and manages numbering and status. Lower the barrier to creation and teams will create more ADRs. Require ADRs as part of the design review process for any project that takes more than two weeks of engineering time.

Make ADRs visible by referencing them in pull requests, design documents, and onboarding materials. When a PR implements a pattern established by an ADR, link to it. When a new engineer asks why the system is designed a certain way, point them to the relevant ADR. This consistent reinforcement builds the habit of both writing and consulting ADRs as part of normal engineering work.