What Is an Architecture Decision Record (ADR)? | Vantage

Architecture Decision Record An Architecture Decision Record (ADR) is a short document that captures a significant architectural decision: the context that required the decision, the options considered, the decision made, and the rationale. ADRs are stored alongside the codebase (typically in a docs/decisions/ or adr/ directory) and are version-controlled. They are written in the present tense and are immutable once accepted — superseded ADRs are marked superseded, not deleted.

Why architecture decision record matters

Engineering organizations lose institutional knowledge constantly — through attrition, team growth, and time. ADRs prevent the question of why something was built a certain way by recording the context that justified a decision when it was made. Without ADRs, teams revisit the same decisions repeatedly, new engineers make changes that violate constraints they did not know existed, and the cost of the original decision is incurred again rather than building on it.

How it works

When a significant architectural decision is needed, an engineer writes a draft ADR documenting the context, constraints, options considered, and their recommendation. The draft is reviewed (often via PR) by the team. Discussion happens in comments or in a meeting. The decision is recorded, and the ADR is merged and numbered sequentially (ADR-0001, ADR-0002). Future ADRs that supersede earlier ones reference the superseded ADR by number.

Common mistakes

• Only writing ADRs for new decisions — existing decisions should also be documented retroactively when they are questioned

• Writing ADRs that are too long — an ADR should be readable in 5 minutes; detail belongs in linked documents

• Not making ADRs discoverable — stored in a directory no one knows about is as good as not written

• Ignoring the context section — the decision is obvious given the constraints; what future readers need is the constraints

• Treating ADRs as binding contracts that cannot be superseded — circumstances change; the process is to write a new ADR, not to pretend the old one does not exist