What does ADR stand for?

Architecture Decision Record: a short, numbered document that captures one architectural decision, the context around it, and its consequences.

Usually in a /docs/adr or /docs/decisions folder in the repository: one markdown file per decision, numbered in the order they were made. Keeping them next to the code they govern is the point.

What's the difference between an ADR and an RFC?

An RFC is a proposal written before the decision, to gather comments. An ADR is the record written after: what was decided and why. Many teams use both: the RFC drives the discussion, the ADR preserves the outcome.

Why do ADRs go stale?

They depend on filing discipline. Writing one is a manual step at exactly the moment the work feels finished, so decisions made in Slack or code review never get filed, and statuses stop being updated when decisions are superseded.

ADR (Architecture Decision Record)

An ADR is a short document recording one architectural decision (what you chose, what you rejected, and why), kept in version control next to the code.

An Architecture Decision Record (ADR) captures one significant decision in a short document: the context, the choice, the alternatives rejected, and the consequences. Michael Nygard proposed the format in 2011, and it stuck because it's small enough to actually write: a page, not a wiki.

The standard format

One file per decision, numbered, in the repo:

# 007. Use Postgres row-level security for tenant isolation

Status: Accepted
Context: We need tenant isolation without forking queries per tenant.
Decision: Enforce isolation with Postgres RLS policies, not app-level filters.
Consequences: Every new table needs a policy. Simpler app code; harder local debugging.

Status matters: Proposed, Accepted, Superseded by 019. A superseded ADR is never deleted; the history is the value.

ADR vs RFC

An RFC comes before the decision: a proposal circulated for comment. An ADR comes after: the record of what was decided. Teams that use both write the RFC to argue and the ADR to remember.

Where ADRs fall short

ADRs decay for one reason: filing is manual, and it happens at the exact moment the decision already feels handled. The decisions that actually change your architecture get made in Slack threads and PR reviews, and most never become ADRs at all. The folder becomes an archive of the decisions someone remembered to file. That's the start of decision drift and spec drift.

AI agents make the gap visible. An agent can't use a raw ADR folder well: it would have to read every file, work out which are superseded, and guess which apply to the current task. Nothing delivers the relevant, still-valid decisions at the moment of work. That delivery-and-freshness layer is what Lockstep adds on top of the record: it captures decisions where they happen and serves the approved ones to agents over MCP.

For the long version (history, templates, and failure modes), see the full ADR guide.