Skip to content
CS Capstone Handbook

Architecture Decision Record (ADR)

Your team is about to commit to a database, an authentication provider, or a hosting platform, and it will live with that choice long after anyone remembers the meeting where it was made. This page covers the architecture decision record: which decisions deserve one, what goes in it, and how to review it, store it, and replace it when the decision changes. It doesn’t cover the design document that describes the whole system.

An architecture decision record (ADR) is a short file that records one technical decision and the reasons for it. The format comes from Michael Nygard’s 2011 post, which is itself written as an ADR. His case for it centers on a newcomer who finds a past decision with no rationale attached. That person can only accept the decision blindly or change it blindly. Accepting is fine while the decision still fits, but not once the context has changed. Changing it can damage the project without anyone noticing, for instance when the decision protected a non-functional requirement nobody has tested yet. A record of the context and the consequences lets the newcomer do neither blindly.

Readable code and tests don’t make the record redundant. Thoughtworks, whose Technology Radar placed lightweight ADRs in its “Adopt” ring, argues that code and tests can replace much documentation but that certain design decisions still need recording for future team members. Code shows what you built, but not the options you rejected or the constraint that ruled them out.

What is an ADR?

Section titled “What is an ADR?”

An ADR is a Markdown file, one or two pages long, as Nygard proposed, recording a single decision. His format has five parts. MADR (Markdown Architectural Decision Records), a later template, keeps them and adds a list of the options considered, and so does the structure below:

  • Title: a short noun phrase naming the decision, with its number: “ADR-004: PostgreSQL for the main database”.
  • Status: where the decision stands in its lifecycle (below).
  • Context: the forces at play, whether technical, political, social, or particular to the project, stated as facts. Nygard asks for value-neutral language here. Keep it that way, so a reader who disagrees with the decision can still agree with the context.
  • Options considered: the alternatives you evaluated, each with the reason it lost.
  • Decision: what you’ll do and why it wins, in full sentences and the active voice (“We will use…”).
  • Consequences: everything that follows from the decision, the costs as well as the benefits.

The reasons for rejecting the alternatives are the part that goes missing. In a survey of 81 practitioners who design architectures, about 36% said they don’t document discarded decisions, and the authors observe that why a design was chosen over its alternatives appears usually not to be documented (Tang et al., 2005). The most common reason respondents gave for not documenting rationale was lack of time or budget (60.5%), while 9.9% said it isn’t useful (Tang et al., 2005). Those reasons feel obvious on the day you write them, which is also the day they’re cheapest to write. Six months later, the teammate who joined halfway through can’t tell whether PostgreSQL was a considered choice or an accident, and neither can you.

Status

Section titled “Status”

An ADR’s status tells a reader whether to act on it. MADR’s template names the five values below and leaves room for others; they extend Nygard’s original four with “rejected”:

  • Proposed: written and under discussion; the team hasn’t agreed yet.
  • Accepted: the team agreed, and the decision is in force.
  • Rejected: the team considered the proposal and said no. Keep the file and the reason, so the same debate doesn’t start again from scratch next month.
  • Deprecated: the decision no longer applies. Nygard allows deprecated or superseded for a decision a later ADR replaced; use deprecated only when nothing replaced it, so a reader knows whether to look for a replacement.
  • Superseded: a later ADR replaced this one. Name the replacement and link it, and have the new ADR link back.

Keep the status current, because it’s the line that tells a reader a year from now whether the rest of the page still describes the system.

Proposals and Records

Section titled “Proposals and Records”

A proposal that argues for a decision before the team makes it (some organizations call it an RFC, for request for comments, or a design doc) and the record of the decision can be the same file. Write the proposal under headings that carry the record’s parts (the problem and its context, the options, the recommended decision, its consequences) and give it the status “proposed”. It runs longer than a record, because it carries the analysis of each option. When the team decides, change the status, record who decided and the date, and the proposal becomes the record. If the proposal grew too long to skim, condense it into a short ADR that links the full document.

Martin Fowler argues that writing the record is valuable in itself, because a document of consequence often surfaces different points of view in a group and forces them to be discussed. That’s a reason to draft the ADR while the decision is still open rather than after it’s settled.

Which Decisions Deserve an ADR?

Section titled “Which Decisions Deserve an ADR?”

Decide by how expensive the decision is to reverse. Jeff Bezos’s 2015 letter to Amazon shareholders separates Type 1 decisions, which are consequential and irreversible or nearly so and should be made methodically and carefully, from Type 2 decisions, which are changeable and reversible and should be made quickly by individuals or small groups with good judgment. He observes that as organizations grow, they seem to apply the heavy Type 1 process to many Type 2 decisions, and that the result is slowness. Microsoft’s Azure Well-Architected guidance draws a similar line for ADRs: include only the choices that affect the system’s structure or key quality attributes, or that are difficult to reverse.

Your database engine, your authentication approach, your data model, and your deployment target are hard-to-reverse decisions, and each deserves an ADR. Your logging library is an easy-to-reverse decision: if it turns out wrong, swapping it takes an afternoon.

MADR draws its line lower. Its authors focus on architectural decisions but offer the template for capturing any important decision, and they list a choice between two Java logging libraries as an example of an architectural one. A post on Spotify’s engineering blog goes further and argues for recording small decisions too, because undocumented ones usually lead to duplicated effort or competing solutions, such as two third-party libraries that do the same thing, though the post calls that cost hard to measure. That works for a team that finds records cheap to write and easy to search. Set a threshold anyway, because the records for trivial choices bury the few a newcomer needs.

The threshold still leaves judgment calls. In an action research study at one company, practitioners sometimes struggled to decide whether a decision was architecturally significant enough for an ADR; they prioritized by the complexity of the logic involved, the impact of the change on the system, and the number of developers or teams affected (Ahmeti et al., 2024). When the reversibility test doesn’t settle it, use those three as tiebreakers.

Addressing an Architectural Problem

Section titled “Addressing an Architectural Problem”

Start the ADR from the problem, not the solution you’ve already picked. The context section states what the problem is, who it affects, and why it matters now, in enough detail that a reader could weigh the options without you in the room. “We need a database” is not a context. “The app stores users, projects, and the tasks that link them; most screens join all three; two people editing the same task must not overwrite each other” is one, because it tells the reader which properties the database has to have.

Write the context down because the finished system won’t show it. Jansen and Bosch (2005) argue that an architecture embeds the results of its design decisions without representing the decisions themselves, so knowledge about them is lost, which they call knowledge vaporization. They believe this is part of why architectures become expensive to change and erode over time.

What Makes a Good ADR?

Section titled “What Makes a Good ADR?”

A good ADR is specific about the problem, names the options that were actually on the table, and states the costs of the choice as plainly as its benefits. Here’s one:

# ADR-004: PostgreSQL for the main database


Status: Accepted on YYYY-MM-DD. Deciders: Ana, Ben, Chloé. Reviewer: Priya.


## Context
The app stores users, projects, and the tasks that link them, and most
screens join all three. Two people editing the same task must not overwrite
each other. Our host includes a managed PostgreSQL or MySQL instance at no
extra cost. Two of us have used PostgreSQL; nobody has used MySQL.


## Options considered
- PostgreSQL (managed by the host): relational, transactional.
- MySQL (managed by the host): meets the same needs; rejected because
  nobody on the team has used it.
- MongoDB (separate vendor): rejected; our data is relational, so joins
  would move into application code, and it adds a second bill.
- Keep the SQLite file: rejected; the host wipes local disk on redeploy.


## Decision
We will use the host's managed PostgreSQL through the `pg` library.


## Consequences
- Good: transactions protect concurrent task edits; one vendor.
- Bad: two teammates must learn PostgreSQL; schema changes need migrations.
- Bad: we depend on the host's PostgreSQL version and backup schedule.


## Confirmation
A test runs two concurrent edits on one task and checks both are applied.

Notice what the example does that a weak ADR doesn’t: it names alternatives that were actually considered, including keeping what already exists, and gives a specific reason each one lost. “PostgreSQL is the best fit” records nothing, because it would be equally true of any choice.

Write the costs into Consequences as plainly as the benefits, because they’re what the next reader needs to judge whether the decision still holds. Nygard asks for every consequence, positive, negative, and neutral. Tang et al. (2005) found that 27.2% of the practitioners they surveyed never or seldom document a design’s weaknesses, and suspect a tendency to present good news rather than bad news during design.

The Confirmation section comes from MADR, where it’s optional: it says how you’ll check that what gets built matches the decision, whether by a design or code review or by a test. Add it for any decision that code could quietly drift away from.

Where ADRs Live

Section titled “Where ADRs Live”

Keep ADRs in the repository, one file per decision, under docs/adr/. Number them sequentially and never reuse a number, as Nygard specifies, so 0004-postgresql-for-main-database.md keeps its number even after it’s superseded. Thoughtworks recommends source control over a wiki because the records then stay in sync with the code. Keeping them there also lets a teammate review the decision in the same pull request as the change it explains. adr-tools, a small shell utility by Nat Pryce, creates numbered records and marks superseded ones; a directory of Markdown files works just as well without it.

Write the date of the decision into the status line when you accept the ADR. The Git history records when the file changed, which isn’t always when the team decided, and it doesn’t travel with a copy read outside the repository.

Validation

Section titled “Validation”

Have someone who wasn’t part of the decision review each ADR while its status is still “proposed”, and mark it accepted only after they have. A person who was in the room fills the gaps from memory without noticing them. The guidelines in the action research study above required each ADR to be reviewed by another developer before it was published (Ahmeti et al., 2024). When the decision affects the people you’re building for (their budget, their data, their systems), they should read it too.

AWS’s ADR process starts each review meeting with a slot for reading, in which every reviewer reads the ADR and adds comments and questions before anyone discusses them; AWS judges 10 to 15 minutes enough on average.

Whatever form your review takes, have the reviewer answer these questions:

  • Can I restate the problem from the Context section alone?
  • Is each option one a reasonable person might have picked, and is keeping the current approach among them?
  • Does each rejected option have a specific reason?
  • Does Consequences name at least one cost?
  • Is this one decision, or two joined by “and”?
  • Could I disagree with the decision using only what’s on the page?

A failed check looks like a reviewer asking a question the ADR should have answered. Put the answer in the ADR rather than in the chat thread, and leave the status at “proposed” until it’s there, as the AWS process does.

Measuring Success

Section titled “Measuring Success”

The practice is working when the records get used, not just written. The signals to look for:

  • A “why did we…” question gets answered with a link to an ADR instead of a meeting.
  • Code review cites ADRs. In the AWS process, a reviewer who finds a change that violates an accepted ADR links the ADR and asks for the change to be reworked.
  • Reversals arrive as superseding ADRs rather than as silent changes someone discovers later.
  • More than one person writes them. In a study of public GitHub repositories, 84% of those with at least 10 ADRs had ADRs from more than one contributor, and the authors conclude that where the practice is adopted, recording decisions is a team activity (Buchgeher et al., 2023).
  • A newcomer can skim the directory’s titles and come away with the project’s history.

Best Practices for Writing ADRs

Section titled “Best Practices for Writing ADRs”

The rules below condense the page into a checklist to run before you mark an ADR accepted.

  • Write one decision per ADR. If the Decision section contains “and”, split it.
  • Write the ADR the week you make the decision, even roughly.
  • Name every option you considered, including keeping the current approach, and say why each lost.
  • State the costs in Consequences.
  • Record your confidence in the decision, as Microsoft’s guidance suggests, so whoever revisits a low-confidence one knows it was a bet.
  • Link related ADRs to each other, and link the ADR from the pull request that implements it.
  • Record deliberate non-decisions, such as “we will not support offline mode”, when someone is likely to ask.
  • Supersede instead of editing. Change an accepted ADR only to fix a typo, update its status, or add the link to its replacement.
  • In an inherited codebase, write ADRs for the past decisions you can confirm, and say in each that it was reconstructed after the fact. Microsoft’s guidance recommends generating records retroactively for an existing system when the information is available.

Some Truths about ADRs

Section titled “Some Truths about ADRs”

An ADR written weeks after the decision is a reconstruction. By then the rejected options have faded, and the rationale gets written to justify what was already built, which is the opposite of what a record is for. The telltale sign is an options section listing alternatives nobody seriously considered. An inherited system is the one place a reconstruction is worth writing, marked as one. For your own team’s decisions, write the ADR in the same week, even in rough form, because a rough record with the real alternatives is worth more than a polished one with invented ones.

The busywork criticism is fair. Buchgeher et al. (2023) found 921 public GitHub repositories that recorded at least one decision as an ADR; more than half hold between one and five, and for many of those the authors assume the practice was tried and not adopted. The study doesn’t say why teams stop. Set the reversibility threshold before you write the first ADR anyway, because it caps what the practice costs: a handful of records for the decisions that matter, not one for every library.

A team that tries to keep every ADR current will find the format exhausting, and it doesn’t have to. An accepted ADR describes a decision at a point in time, not the current system, so a change to the system doesn’t make it wrong; it makes it superseded. AWS and Microsoft both treat accepted ADRs as immutable, and Microsoft describes the collection as an append-only log. In the GitHub study, about half of 6,362 ADR files were committed once and never modified again, which the authors read as a sign that ADRs aren’t meant to change often (Buchgeher et al., 2023). Maintenance costs one new file and one status line on the old one.

Writing decisions down can also push a team to over-deliberate, treating every choice as consequential. In his 2016 letter to shareholders, Bezos argues that most decisions should probably be made with somewhere around 70% of the information you wish you had, that waiting for 90% in most cases probably means you’re slow, and that if you’re good at course correcting, being wrong may cost less than you think, while being slow is expensive for sure. Write a faster ADR rather than skipping it: record the options and what worried you, and don’t hold up the decision while someone polishes the record.

ADRs in Industry and Academia

Section titled “ADRs in Industry and Academia”

In open source, Nygard’s format dominates: of the 921 GitHub repositories in the study above, 723 used mainly his template and 129 mainly MADR (Buchgeher et al., 2023). AWS’s Prescriptive Guidance describes a full process, from ownership through review to superseding, and Microsoft’s Well-Architected Framework calls the decision log, which it names the ADR, one of the most important deliverables of a solution architect. The Spotify post describes how ADRs helped new owners get up to speed on a system when its ownership moved from one team to another.

In standards, ISO/IEC/IEEE 42010:2022 is the international standard for architecture descriptions. The conceptual model on the standard’s website shows every architecture description including architecture rationale, unchanged from the 2011 edition, which defined it as the reasoning behind the architecture’s decisions and the alternatives not chosen. A collection of ADRs is one way to keep that rationale.

In research, architecture decisions have been studied at least since the knowledge vaporization argument and the rationale survey cited above, both from 2005, but evidence on ADRs in practice is thinner: the authors of the action research study note that few approaches to documenting architectural decisions have empirical evidence of their usefulness in practice (Ahmeti et al., 2024). At the one company they studied, the teams cooperated more after introducing ADRs, though the authors note that documenting decisions doesn’t always strengthen cooperation and expect corporate culture and team dynamics to have shaped that result, and they found that where the documentation was stored had a strong influence on how useful practitioners found it (Ahmeti et al., 2024).

References

Section titled “References”
  • Tang, A., Babar, M. A., Gorton, I., and Han, J. (2005). A Survey of the Use and Documentation of Architecture Design Rationale. Proceedings of the 5th Working IEEE/IFIP Conference on Software Architecture (WICSA). https://doi.org/10.1109/WICSA.2005.7
  • Ahmeti, B., Linder, M., Groner, R., and Wohlrab, R. (2024). Architecture Decision Records in Practice: An Action Research Study. Software Architecture, 18th European Conference (ECSA), Lecture Notes in Computer Science. https://doi.org/10.1007/978-3-031-70797-1_22
  • Jansen, A., and Bosch, J. (2005). Software Architecture as a Set of Architectural Design Decisions. Proceedings of the 5th Working IEEE/IFIP Conference on Software Architecture (WICSA). https://doi.org/10.1109/WICSA.2005.61
  • Buchgeher, G., Schöberl, S., Geist, V., Dorninger, B., Haindl, P., and Weinreich, R. (2023). Using Architecture Decision Records in Open Source Projects: An MSR Study on GitHub. IEEE Access. https://doi.org/10.1109/ACCESS.2023.3287654

Additional Readings

Section titled “Additional Readings”

Sources and further reading

Activities that exercise this