What Is an Architecture Decision Record?

The standard definition

An Architecture Decision Record, usually abbreviated ADR, is a short document that captures one significant architectural decision: the context that made it necessary, the decision itself, and its consequences. The convention was popularized by Michael Nygard's 2011 article "Documenting Architecture Decisions" and has since become a common practice across software teams, often kept as a numbered series of Markdown files in a repository (e.g. `docs/adr/0001-use-postgresql.md`).

What a typical ADR contains

Formats vary slightly between teams, but most ADRs cover the same core sections:

• Title and number — a short, specific name, numbered sequentially.
• Status — proposed, accepted, deprecated, or superseded (by a later ADR).
• Context — the situation and forces at play that make a decision necessary.
• Decision — the choice that was made, stated plainly.
• Consequences — what becomes easier or harder as a result, including tradeoffs accepted knowingly.

When teams write one

ADRs are typically reserved for decisions that are significant and relatively hard to reverse: choosing a primary database, adopting a new architectural pattern, picking a core dependency the rest of the system will build on. They're deliberately not meant for every decision — writing a full ADR for a small, easily-reversed choice is usually more ceremony than the decision warrants, which is part of why most engineering decisions never get one at all.

How ADRs relate to decision memory

An ADR is a specific, documented architecture decision. Decision memory is the broader idea: a system for capturing the reasoning behind decisions in general, not just architectural ones, and not just the ones significant enough to justify writing a formal document. The relationship is one of scope, not competition — a team can write ADRs for its handful of major architectural calls and use a decision memory system for the much larger number of smaller technical and non-technical decisions that never get a formal ADR but still deserve a recorded reason.

In practice, the gap ADRs leave is exactly the gap that causes the most "why is this built this way" confusion: the accumulation of dozens of smaller calls — a library swapped out, a workaround adopted under deadline pressure, a pattern changed halfway through a project — that individually didn't meet the bar for a formal ADR, but collectively shape the system just as much. See Decision Memory for Engineering Teams for how that plays out day to day.

Does Cadenzova Decisions replace ADRs?

No, and it isn't trying to. If your team already writes ADRs for major architectural decisions, keep doing that — it's a well-proven practice for exactly the class of decision it's designed for. Cadenzova Decisions is built for the same underlying structure (a decision, its reasoning, its outcome) applied more broadly and with much less ceremony, so the smaller decisions that never rise to "write a formal ADR" don't go completely unrecorded either.