Architecture Decision Record Log

Purpose

An Architecture Decision Record (ADR) log is a time-ordered journal of significant technical decisions. Each entry—one ADR—documents a specific choice: why it was made, what alternatives were considered, what consequences are expected, and who made the call. The log as a whole is the institutional memory of your system’s design.

Code tells you what the system does. Git history tells you when things changed. The ADR log is the only artifact that tells you why. Without it, every engineer who joins the project must reverse-engineer intent from implementation—a slow, error-prone process that leads to premature rewrites, contradictory decisions, and the silent loss of hard-won knowledge.

ADRs are not meeting notes or design docs. They are short, focused records of one decision at a time. The most useful ADRs are written in the moment of decision, not as a retrospective. They are never edited after being accepted—only superseded by new ADRs when the decision is revisited.

A healthy ADR log evolves with the project. A new backend service might start with three ADRs (database choice, deployment model, authentication approach) and grow to thirty over two years. The log is not a burden; it is a gift to future maintainers—including yourself six months from now.

Who needs this document

What separates a good version from a bad one

Criterion 1: Each ADR covers exactly one decision

✓ Strong: “ADR-0007: Use Redis for session storage over database-backed sessions. Context: 50ms p95 latency requirement for auth checks. Decision: Redis Cluster with 24h TTL. Alternatives: PostgreSQL sessions (too slow), JWT-only stateless (revocation complexity too high).”

✗ Weak: “ADR-0007: Backend infrastructure decisions. Covers: Redis for sessions, chosen ORM, deployment region, background job queue.” (Four decisions in one ADR makes supersession impossible and context search unreliable.)

Criterion 2: Alternatives considered are substantive

✓ Strong: “Alternatives considered: (1) Kafka — rejected due to ops overhead for a team of 2; would revisit above 10k events/s. (2) SQS FIFO — viable but AWS lock-in concern given current cost structure. (3) Postgres LISTEN/NOTIFY — chosen for simplicity; acceptable at current scale.”

✗ Weak: “Alternatives considered: other message brokers.” (Naming rejected options without reasoning teaches nothing. A future engineer cannot evaluate whether the trade-off still holds.)

Criterion 3: Status is accurate and maintained

✓ Strong: ADR-0003 has status: superseded with a link to ADR-0011 that replaced it. ADR-0011 notes the conditions that made the original choice obsolete.

✗ Weak: ADR-0003 says status: accepted but the decision was quietly reversed eight months ago and no new ADR was written. The log now actively misleads.

Criterion 4: Consequences are honest, including negative ones

✓ Strong: “Consequences: Positive: single deployment unit simplifies ops. Negative: cannot scale frontend and backend independently; will need to split if frontend becomes read-heavy. Neutral: increases Docker image size by ~40 MB.”

✗ Weak: “Consequences: This is the right choice for our use case.” (No specifics, no trade-offs disclosed.)

Common mistakes

Writing ADRs only when the decision was uncontroversial. Teams document the easy choices and skip the hard ones. The most valuable ADRs capture exactly the tense, contested decisions where context would otherwise be lost. If there was a whiteboard debate, write an ADR.

Using past tense for already-implemented decisions. Backdated ADRs lose the authentic “who was in the room and what did we know then” quality. A backdated ADR is better than none, but label it as such: “Recorded retrospectively — context may be incomplete.”

Numbering gaps that make engineers wonder what happened. If ADR-0008 and ADR-0009 don’t exist, future readers wonder if they were deleted. Use explicit status: withdrawn rather than deleting files.

Treating the ADR template as mandatory prose. Shorter is better. A 200-word ADR that answers “what, why, and what are we giving up” is more useful than an 800-word treatise that no one reads.

Storing ADRs outside the repository. ADRs in a wiki or Notion drift out of sync with the code. ADRs in docs/adr/ travel with every git clone and are versioned alongside the decisions they document.

How to use this document

When to create it

Start the ADR log before writing the first line of production code. The first ADR is often the simplest: “Why this tech stack?” Write one ADR per decision; never combine. Time-box writing: 20–30 minutes per ADR is the right effort level.

Who owns it

Every engineer on the team owns the ADR log collectively. The tech lead or architect owns the template and numbering convention. Any engineer may propose or draft an ADR; the decision-maker signs off by updating status to accepted.

How AI agents should reference it

get_standard_docs(type="backend_service", features=[])
→ adr_log in documents[]
→ agent reads existing ADR files before proposing architectural changes
→ agent cites "per ADR-0005" when reasoning about why a pattern exists
→ agent proposes new ADR draft if its suggestion would contradict an accepted decision

The prompt_snippet — “Maintain an architecture decision record log that captures context, alternatives considered, and consequences for every significant design choice” — tells the agent to verify the log exists and to treat it as authoritative context.

How it connects to other documents

The ADR log is downstream of the Requirements Specification (decisions are made to satisfy requirements) and upstream of the Architecture Overview (the overview summarizes the current state; ADRs explain how it got there). API Contract decisions often have corresponding ADRs for versioning strategy. The Technical Design Document may reference ADR numbers for significant implementation choices.

Recommended Reading

• Documenting Software Architectures: Views and Beyond by Paul Clements et al. — The standard reference for architectural documentation; the ADR concept fits within its “decisions view” framework.
• Building Evolutionary Architectures by Neal Ford, Rebecca Parsons & Patrick Kua — Chapter on fitness functions and architectural governance explains why decisions need to be explicit and revisitable.
• Thinking in Systems by Donella Meadows — Understanding second-order effects helps write better “Consequences” sections.