Skip to content
CS Capstone Handbook

Architecture Decision Record (ADR)

Read this when your team is about to make a technical choice it will live with; it gives you the ADR format and the habit of recording why.

Architecture Decision Records (ADRs) are the backbone of a well-documented software project. They capture the key decisions that shape your system’s architecture, technology choices, and design patterns, so that developers, stakeholders, and future maintainers all understand why things are the way they are. Without clear ADRs:

  • Teams forget why decisions were made, leading to repeated debates or mistakes.
  • New contributors struggle to understand the rationale behind the architecture.
  • Projects risk inconsistency, technical debt, or costly rework.

ADRs are concise, focused documents that bridge the gap between architectural ideas and their implementation. They detail the context, options considered, reasoning, and consequences of decisions, serving as a living record for your project.

The format comes from Michael Nygard’s 2011 post, which is worth reading in full because it is about two pages and makes the case better than any summary. His observation was that architecture documents go stale because they describe a system that keeps changing, while decisions do not change: a decision made in fall week 4 was still made in fall week 4, even after you reverse it in winter. So record the decisions, timestamped and immutable, and let the current state of the system be read from the code. That reframing is the whole idea.

An ADR is also the natural second life of a proposal. A document that argues for a decision does its job once, at the moment of the argument; the record of what was decided and why outlives it, and the two are different artifacts even when they start from the same draft.

What is an ADR?

Section titled “What is an ADR?”

An ADR is a short Markdown file, usually under a page, recording one decision. The five parts below are the common core; the widely used MADR template adds a few optional fields, and Joel Parker Henderson’s collection catalogs the variants if you want to compare them before picking one.

  • Decision: What architectural or technical choice was made?
  • Context: What problem, need, or situation led to this decision?
  • Options considered: What alternatives were evaluated?
  • Rationale: Why was this option chosen? What were the trade-offs?
  • Consequences: What are the implications, risks, or follow-up actions?

Of those five, context and rationale are the ones that decay if you skip them, and they are also the ones teams skip, because at the time of writing they feel obvious. They are obvious to you, this week. They are not obvious to the teammate who joins in winter, to your successor team next year, or to you in spring when someone asks why the database is Postgres and you genuinely cannot remember whether it was a considered choice or an accident.

The hard part is deciding what deserves an ADR at all, and the most useful filter is how expensive the decision is to reverse. Jeff Bezos’s 2016 letter to shareholders frames this as one-way and two-way doors: a two-way door can be walked back cheaply, so decide fast and do not ceremonially document it; a one-way door is expensive or impossible to undo, so it deserves deliberation and a record. Your database engine, your authentication approach, your data model, and your deployment target are one-way doors. Your logging library is not.

Addressing an Architectural Problem

Section titled “Addressing an Architectural Problem”

The best ADRs address a real architectural problem or challenge. When you tackle a problem affecting your system’s structure, scalability, or maintainability, you clarify what you want to achieve, why, and how. A good ADR starts with a problem statement: clear, concise, and specific. It should describe the problem, who is affected, and why it matters.

Just as with requirements, the problem statement in an ADR is a living document. High-performing teams revisit and refine their architectural problems as they learn more about the system and its context.

What Makes a Good ADR?

Section titled “What Makes a Good ADR?”

Good ADRs are clear, concise, and justified. Use simple, unambiguous language. Avoid jargon or vague terms. Document the alternatives considered and the reasoning behind your choice. For example:

# ADR-001: Use PostgreSQL for the main database


**Status:** Accepted


**Context:**
We need a reliable, scalable database for our web application. Requirements include ACID compliance, support for complex queries, and compatibility with our hosting provider.


**Decision:**
We will use PostgreSQL as the primary database for the project.


**Options Considered:**
- PostgreSQL
- MySQL
- MongoDB


**Rationale:**
PostgreSQL offers strong ACID guarantees, advanced query capabilities, and is well-supported by our cloud provider. MySQL lacks some features we need, and MongoDB is less suitable for relational data.


**Consequences:**
- Team members need to learn PostgreSQL basics.
- We will use the pg library for Node.js integration.
- Future migrations may require careful planning.


**References:**
- [PostgreSQL documentation](https://www.postgresql.org/docs/)
- Team discussion notes, fall week 3

Add the date and author to the ADR if not in version control.

Notice what that example does that a bad ADR does not: it names alternatives that were genuinely considered, and it says something specific about why each was rejected. “We chose PostgreSQL because it is the best fit” records nothing, because it would be equally true of any choice. The test is whether a reader could reconstruct the argument well enough to disagree with it.

Validation

Section titled “Validation”

A validated ADR should answer:

  • Is the decision valuable to the project or users?
  • Is it feasible given technical constraints?
  • Is it viable for the business or organization?
  • Is it understandable to future team members?

Review ADRs with stakeholders, mentors, or team members to catch misunderstandings or ambiguities early. Revisit ADRs as the project evolves.

Measuring Success

Section titled “Measuring Success”

Success for an ADR means the decision leads to positive outcomes: improved system quality, easier maintenance, or better team alignment. Optionally track the impact of architectural decisions through metrics like system performance, developer productivity, or user satisfaction.

Best Practices for Writing ADRs

Section titled “Best Practices for Writing ADRs”
  • Be concise. Focus on the decision and its reasoning.
  • Use clear, unambiguous language.
  • Document alternatives, even briefly.
  • Update status (accepted, deprecated, superseded) as decisions evolve.
  • Link related ADRs to show connections.
  • Review and update ADRs regularly.
  • Make uncertainties explicit.
  • Prioritize impactful decisions.
  • Separate decisions from explanations.
  • Consider listing non-decisions (what you chose NOT to do).
  • If your ADR has “and” in the decision, break it down.

Some Truths about ADRs

Section titled “Some Truths about ADRs”

The honest version first: most student teams write their ADRs in a batch, the week a deadline arrives, about decisions they made long before. Those documents are archaeology, not records, and they are noticeably worse than the real thing, because the alternatives have been forgotten and the rationale gets reconstructed to justify what was already built. Everyone involved can tell. If you take one operational habit from this page, make it writing the ADR in the same week as the decision, even badly, rather than a polished one later.

The busywork criticism is fair and worth meeting directly. An ADR for every library choice is a tax that produces a directory nobody reads, and teams that try it abandon the practice by winter, which leaves them with no records at all. The failure is not documentation; it is the absence of a threshold. Use the one-way door test and expect a nine-month project to produce something in the range of five to fifteen ADRs. If you have forty, you are recording preferences. If you have one, you are not recording decisions.

ADRs go stale in a specific and manageable way, and it helps to know that staleness is by design. An ADR is not a description of the current system, so it does not become wrong when the system changes; it becomes superseded. The maintenance burden is therefore much smaller than it looks: you do not update old ADRs, you write a new one that supersedes the old one and link them. A team that believes it must keep every ADR current has misunderstood the format and will, reasonably, find it exhausting.

There is a real counter-argument worth stating. Writing decisions down can encourage a team to over-deliberate, treating every choice as consequential and slowing itself down, and the decide-and-commit instinct is often right: an imperfect decision made in week 3 usually beats a perfect one made in week 8, because you learn from the thing you built. The resolution is not to write fewer ADRs but to write them faster and with less ceremony, which is the argument behind lightweight ADRs. A record that took twenty minutes and says what you were worried about is worth more than a polished one that delayed the decision by a week.

Finally, ADRs are most valuable to people who are not in the room, which is why their value is hard to feel while writing them. The audience is your winter self, your successor team, and the partner who asks in spring why the system works this way. None of them can ask you a follow-up question, which is exactly why the reasoning has to be on the page.

ADRs in Industry and Academia

Section titled “ADRs in Industry and Academia”

In industry, ADRs are used by software teams, open-source projects, and organizations practicing agile or DevOps. They make decisions visible, auditable, and collaborative. Some companies use formal templates; others prefer lightweight records. The key is capturing reasoning and context.

Both AWS and Microsoft publish prescriptive guidance on the practice (AWS’s ADR process and Microsoft’s Well-Architected architecture decision record page), which is a reasonable signal that the format has stopped being a niche enthusiasm. Tooling exists too, though it is optional: adr-tools is a small shell utility for creating and superseding numbered records, and a directory of Markdown files works fine without it.

In academia, ADRs help student teams reflect on design choices, justify decisions to instructors or peers, and learn from past projects. They support critical thinking and communication skills.

Additional Readings

Section titled “Additional Readings”

Start with Nygard: the original post is two pages and explains why the format is shaped the way it is, which no summary quite manages. The template collections are there so you can pick one rather than inventing your own in week 3.

Sources and further reading

Activities that exercise this