Architecture Decision Records

What is it

An Architecture Decision Record (ADR) is a short document that captures a single architecturally significant decision — the context that prompted it, the decision itself, and its consequences. Popularized by Michael Nygard in 2011, the format deliberately mirrors the forces-and-resolution structure of design patterns. ADRs live alongside source code in version control, numbered sequentially and never deleted — only superseded when new information warrants revisiting a decision. The full collection of ADRs for a project forms its decision log, a traceable history of how the architecture became what it is.

My Opinion

ADRs are a must-have in every engineering organization, regardless of size. They answer the single most important question a new team member — or a future version of yourself — will ask when staring at a confusing piece of code: why was this done this way? Without that answer, you’re left either blindly accepting a decision you don’t understand, or blindly reversing one whose rationale is no longer visible. Neither is good.

The Delta View

The key mental model is the one I explored in Dual-Engine Knowledge System: ADRs are the delta — the step-by-step record of decisions that moved the architecture to its current state. Your architecture diagrams, API docs, and runbooks are the state view. Both are necessary, but they serve different purposes. ADRs are the source of truth for why; everything else describes what. Teams that treat ADRs this way stop arguing about decisions already made and spend that energy moving forward instead.

Structurally Simple, Queryable by Design

One of ADRs’ underrated strengths is that they are just Markdown. No special tooling required, no platform lock-in, no migration risk. A file with a title, context, decision, status, and consequences is all you need. That simplicity makes them naturally portable — they render in GitHub, Obsidian, Confluence, or any editor without modification. The structured fields (status, date, scope) also make them machine-readable, which means systems like Obsidian’s graph view, Confluence macros, or even AI agents can query and surface them automatically. As AI and coding agents become part of the development workflow, having decisions captured in plain structured text is increasingly valuable — agents can read them, reason about them, and avoid re-litigating settled questions.

Only Superseded, Never Deleted

The append-only nature of ADRs is a feature, not a limitation. When a decision changes, you don’t edit the old ADR — you write a new one that supersedes it. This preserves the full reasoning trail: you can see not just what the current decision is, but what it replaced and why. For people already on the team, this is the shared memory that keeps everyone walking in the same direction. For those arriving later, it’s onboarding material that no amount of architecture diagrams can substitute for.

The Discipline Problem

The honest challenge with ADRs is adoption discipline. Writing the first five is easy. Maintaining the habit when you’re moving fast is harder. Teams that treat ADR writing as a mandatory gate — requiring an ADR for any significant decision before it’s merged — succeed. Teams that treat it as optional documentation find the log drifting out of sync with reality. The tooling gap matters here too: there’s no dominant ADR ecosystem comparable to, say, a linter or test runner. You’ll find adr-tools, Log4brains, and various Confluence plugins, but nothing that enforces the practice automatically. The discipline has to come from the team.

Conclusion

ADRs are one of the highest-leverage documentation practices available to an engineering team, and the cost of entry is a Markdown file. The real value isn’t just documentation — it’s organizational alignment: decisions written down don’t get re-debated, new team members get context instead of folklore, and the “why” survives even when the people who made the call have moved on. Use them for any decision significant enough that you’d hate to explain it from scratch six months later.