Yiuno

Architecture Decision Records (ADRs)

9 min read

Architecture Decision Records (ADRs)

Short documents that capture a single architectural decision — the context, the options considered, the choice made, and the consequences — so future readers (and future AI sessions) know why things are the way they are.

What is an ADR?

An ADR is a snapshot of a decision. Not the code that resulted from it, not the requirements that led to it, but the decision itself — what was chosen, what the alternatives were, and why.

Software projects are full of choices: which database, which framework, which hosting provider, which data format. Each choice has trade-offs. Over time, the reasoning behind those choices fades. New team members, new AI sessions, and even your future self will look at the code and wonder: “Why is it done this way?”

Without ADRs, one of two things happens: either the question goes unanswered and the original reasoning is lost, or — worse — someone re-debates the decision and reverses it without understanding the original context. Both waste time and create risk.

An ADR is small by design — one decision, one page. It’s not a report. It’s not a justification essay. It’s a structured record that takes 10-15 minutes to write and saves hours of re-discovery later.

In plain terms

An ADR is like a judge’s written ruling. The judge doesn’t just announce the verdict (“guilty” or “not guilty”). They write down the facts of the case, the arguments from both sides, the law that applies, and the reasoning behind the decision. If someone appeals later, the ruling explains why — so the next judge doesn’t have to re-hear the whole case.

At a glance

How does an ADR work?

Every ADR has five parts. Each part answers a specific question that, if left unanswered, will cause confusion later.

1. Title

One line that names the decision. Not the topic, not the context — the decision itself. Use a verb that makes the choice clear.

Good titles:

  • “Use PostgreSQL instead of SQLite for the production database”
  • “Serve the frontend as static HTML, not a single-page app”
  • “Store translations in a database table, not in JSON files”

Bad titles:

  • “Database decision” (which decision?)
  • “Frontend architecture” (what about it?)
  • “Translations” (what was decided?)

The title test

If someone reads only the title and the status, they should know what was decided. “Use X instead of Y for Z” is the ideal format.

2. Status

Where the decision stands in its lifecycle. An ADR is a living document — it can evolve as circumstances change.

StatusMeaning
ProposedUnder discussion, not yet accepted
AcceptedActive and in effect
DeprecatedNo longer relevant (technology retired)
SupersededReplaced by a newer ADR (link to it)

Think of it like...

Legal precedent. A court ruling is “active” until a higher court overrules it (superseded) or the law it’s based on is repealed (deprecated). The old ruling isn’t deleted — it stays in the record with a note pointing to what replaced it.

3. Context

What situation prompted this decision? Describe the problem, the constraints, and the forces at play. This is the “why now” section.

Good context includes:

  • The technical situation (what exists now)
  • The constraints (budget, team size, timeline, compliance)
  • The trigger (why the decision is needed now)

4. Decision

What was chosen, and what were the alternatives? List the options considered and explain why the chosen option won.

Always list alternatives

An ADR that says “we chose X” without mentioning what else was considered is incomplete. The alternatives are what make the reasoning auditable. If you can’t name at least two alternatives, it may not be a decision worth recording.

5. Consequences

What follows from this choice? Be honest about both the benefits and the costs. Every decision has trade-offs.

Think of it like...

A medical consent form. Before surgery, the doctor explains the expected benefits, the known risks, and the alternatives. The patient (future reader) can then understand why this path was chosen and what to watch for.

Why do we use ADRs?

Four problems ADRs solve

1. Institutional memory. People leave, sessions expire, context is lost. ADRs preserve the reasoning behind decisions so it outlives any single person or conversation.

2. Re-debating settled questions. Without ADRs, the same “should we use X or Y?” discussion happens every few months. With them, someone can read the ADR and either accept the reasoning or write a new ADR that supersedes it.

3. AI agent drift. An AI agent in a new session doesn’t know about past decisions. Without ADRs, it may propose contradictory approaches. With ADRs loaded into context, it respects past choices.

4. Onboarding speed. A new team member can read the ADR log and understand the project’s key decisions in an hour instead of discovering them over weeks of code archaeology.

When do we use ADRs?

  • When making a decision that would be expensive to reverse (database, hosting, framework)
  • When there are multiple viable alternatives and the reasoning isn’t obvious
  • When someone (including future you) might question the choice later
  • When working with AI agents that need to respect past decisions across sessions
  • When a decision involves trade-offs that should be documented for future evaluation

Rule of thumb

If you spent more than 15 minutes deciding between options, write an ADR. The 10 minutes it takes to document the decision will save hours of re-discovery later.

How can I think about ADRs?

The lab notebook

An ADR is like a page in a scientist’s lab notebook.

  • The scientist runs an experiment (considers alternatives)
  • They record the hypothesis, the method, the result, and the interpretation — not just the conclusion
  • When a colleague asks “why did you use reagent X instead of Y?”, the notebook has the answer
  • When the scientist revisits the experiment months later, the notebook explains the reasoning they’ve forgotten
  • If a new experiment contradicts the old one, the old notebook page isn’t torn out — a new page references it and explains what changed

The notebook is the institutional memory of the lab. The ADR log is the institutional memory of the project.

The family recipe with notes

An ADR is like a recipe passed down through generations, with handwritten notes in the margins.

  • “Use butter, not margarine” (the decision)
  • “Tried margarine in 2018, the texture was wrong” (the context)
  • “Could also use coconut oil for dairy-free” (the alternatives)
  • “Butter costs more but the flavour is worth it” (consequences)
  • A later note: “Grandma switched to olive oil in 2023 — see her updated recipe” (superseded)

Without the margin notes, each generation re-discovers through trial and error. With them, the knowledge compounds.

Concepts to explore next

ConceptWhat it coversStatus
adr-statusesThe lifecycle of a decision: proposed, accepted, deprecated, supersededstub
decision-logHow to maintain and organise a collection of ADRs over timestub
technical-debtWhat happens when decisions accumulate costs that aren’t addressedstub

Some of these cards don't exist yet

They’ll be created as the knowledge system grows. A broken link is a placeholder for future learning, not an error.

Check your understanding

Where this concept fits

Position in the knowledge graph 

graph TD
    SD[Software Development] --> PR[Product Requirements]
    PR --> PRD[PRD]
    PR --> TS[Technical Specification]
    PR --> ADR[Architecture Decision Records]
    ADR --> AS[ADR Statuses]
    ADR --> DL[Decision Log]
    SA[Software Architecture] -.->|decisions recorded as| ADR
    style ADR fill:#4a9ede,color:#fff

Related concepts:

  • prd — the PRD defines what to build; ADRs record why specific implementation choices were made along the way
  • technical-specification — specs define how the system behaves; ADRs explain why it was designed that way
  • spec-driven-development — ADRs are an essential anti-drift tool in spec-driven workflows, preventing AI agents from contradicting past decisions

Further reading

Resources

Graph View

Backlinks