Six months ago your team made a perfectly reasonable architectural decision. But today nobody remembers why that choice was made. Architecture Decision Records (ADRs) would have preserved the reasoning behind that decision.

In this guide, you’ll learn what ADRs are, how to identify decisions worth documenting, structure an ADR, record the alternatives, trade-offs and the common mistakes to avoid.

What is an Architecture Decision Record?

An Architecture Decision Records (ADRs) is a short document in which technical or architectural decisions, the context surrounding them, alternatives that were considered, and the trade-offs accepted are recorded.

The ADR approach was popularized by Michael Nygard in his article Documenting Architecture Decisions.

For example, a team could choose to use GitHub Actions for CI/CD or use REST instead of gRPC for service APIs.

What is important is not merely keeping a record of the team’s choice but also recording why the decision was made.

A few months later, someone might look at the architecture and ask: “Why was it built this way?”

An ADR gives them an answer without having to locate the engineer who made the decision.

Why Do Teams Need ADRs?

Architecture decisions often happen across multiple places such as meetings, Slack, pull requests, tickets, and conversations between engineers. As time goes on, that context is lost.

People leave, the systems change and teams grow with new engineers who have no knowledge of the reasons for the existing decisions. ADRs provide a way to preserve knowledge.

They help teams:

  • Understand why a technology was chosen.
  • Avoid repeating old discussions.
  • Understand trade-offs behind the architecture.
  • Onboard new engineers faster.
  • Revisit decisions when circumstances change.
  • Keep architectural history close to the code.

ADRs also make it easier to distinguish between deliberate decisions and something that had just happened.

That’s useful because not every part of an architecture was selected for a good reason; some of the decisions could have been temporary fixes, experiments, or compromises made when meeting tight deadlines.

An ADR provides that context a place to live.

What Decisions Deserve an ADR?

You don’t need an ADR for every technical decision. There’s no need for an ADR when changing something like the name of a variable, any more than correcting a typo or when choosing between identical libraries for a small feature.

Identifying decisions that are worth documenting as an Architecture Decision Record (ADR).

A decision is more likely to deserve an ADR when it:

  • Affects multiple parts of the system.
  • Introduces a significant technology or dependency.
  • Is difficult or expensive to reverse.
  • Creates important operational consequences.
  • Affects security, reliability, scalability, or performance.
  • Establishes a pattern other teams will follow.

A simple question you can ask yourself is:

“If we changed this decision later, would it require significant engineering work or affect multiple parts of the system?”

Another useful question is:

“Would a future engineer reasonably ask why we made this choice?”

If your answer is yes, an ADR is worthwhile.

What Makes a Good ADR?

There’s no reason for a good ADR to be long since it merely needs to provide anyone who wasn’t involved in the original discussion enough background information.

A good ADR explains the problem, decision, alternatives, and trade-offs.

A good ADR should include:

  1. Context: Explain the problem or situation that led to the decision.

    For example: “Our application needs a relational database with strong transaction support. The team also has significant PostgreSQL experience.”

This gives the reader the information they need to understand the decision.

  1. Decision: Make the decision clear and straightforward.

    For example: “We will use PostgreSQL as the primary database.”

Don't hide the decision within several paragraphs of explanation.

  1. Alternatives Considered: Record the other realistic options the team looked at.

For example:

  • MySQL
  • MongoDB
  • DynamoDB

Note that you don’t need to record every single technology since you should focus on the ones which were relevant to the decision.

  1. Consequences: All architecture decisions involve trade-offs. Document both the benefits and the costs.

For example:

Benefits

  • Strong relational and transaction support.
  • Existing team expertise can be reused.
  • Mature tooling and ecosystem.

Costs

  • Database operations require ongoing management.
  • Scaling may require additional planning as traffic grows.

Note: ADRs are not intended to make decisions look perfect; instead, they must explain those decisions honestly.

ADRs vs. Other Technical Documents

ADRs are often mistaken for other types of engineering documentation. You can easily tell them apart by the question each document answers.

Document

Main question

ADR

Why did we make this architectural decision?

Architecture diagram

What does the system look like?

Design document

How will we build or change the system?

RFC

What are we proposing for discussion?

API reference

What does the API expose?

Runbook

What should I do when something goes wrong?

README

What do I need to know to get started?

For readers who want to learn more about architecture diagrams, the C4 model provides a simple approach for visualizing software architecture.

ADRs vs. Design Documents

A typical design document will describe the method by which a system or feature will be built.

The ADR records the important architectural decision behind it.

For example, a design document might explain how a payment service will work while an ADR explains why the team chose an event-driven architecture for that service.

They can reference each other.

ADRs vs. RFCs

An RFC is usually a suggestion meant for discussion while the ADR contains the decision that results.

A team might create an RFC to discuss whether to move from REST to gRPC. Once the decision is made, an ADR can record the final choice and reasoning.

ADRs vs. Meeting Notes

Meeting notes record what happened during a meeting while the ADR records the architectural outcome.

You don't need to turn every architecture meeting into an ADR. Extract the important decision and its reasoning.

How to Write an ADR

Writing an ADR is a simple task.

  • Identify the Problem: You can start with the problem that requires a decision. Begin by explaining what the system requires before deciding on the technology you want to use.

  • Document the Options: List other alternatives considered. For each of the options, take note of the factors that affected the discussion.

  • Outline the Trade-offs: Find out what you get with each option and what it costs. When doing so, think about factors such as performance, cost, complexity, security, reliability, scalability, team expertise, operational effort, and vendor dependency.

  • Record the Decision: State the chosen option clearly.
    Avoid using vague language such as:

    “We decided to go with PostgreSQL because it seemed like the best option.”

    Instead use:

    “We will use PostgreSQL as the primary database because the application requires relational transactions and the team already has PostgreSQL expertise.”

  • Document the Consequences: You should describe the changes that arise as a  result of the decision. Include what the positive and negative consequences are. Also record any conditions that might lead the team to reconsider the decision at a later stage. For example:

    “Reconsider this decision if the system requires a globally distributed database with multi-region writes.”

    This makes the ADR more useful over time.

A Complete ADR Example

Here's what a simple ADR might look like:

# ADR 0001: Use PostgreSQL for the Primary Database - Status: Accepted - Date: 2026-09-24 ## Context The application stores relational data and requires transaction support. ## Decision We will use PostgreSQL as the primary database. ## Alternatives Considered - MySQL - MongoDB - DynamoDB ## Consequences ### Positive - Strong relational and transaction support. - Existing team expertise can be reused. ### Negative - Database operations require ongoing management. - Scaling requires additional planning.

A document drawn up under the ADR procedure does not have to include ten pages of explanation in order to be useful.

Where Should ADRs Live?

A simple solution is to keep the ADRs together with the source code for the project.

A common structure is:

docs/ └── decisions/     ├── 0001-use-postgresql.md     ├── 0002-use-redis-for-caching.md     └── 0003-adopt-kubernetes.md

Keeping them in Git gives you:

  • Version history.
  • Pull request reviews.
  • Change tracking.
  • Easy access for engineers.
  • A clear relationship between decisions and the codebase.

Why Git Works Well for ADRs

ADRs serve as documentation, yet they also form part of the project's history.

A typical workflow looks like this:

The ADR workflow from identifying an architectural problem to implementing the accepted decision.

You can use adr-tools which is a command-line tool for creating and managing ADRs, and its default approach stores ADRs as Markdown files inside the project. Source version controls platforms like GitHub, GitLab, and various documentation platforms including Docusaurus, MkDocs, Hugo, Zensical, Mintlify, and GitBook are also capable tools when creating ADRs.

If you want a more structured Markdown format, take a look at MADR (Markdown Architectural Decision Records). What’s important is making it easy to find and maintain the ADRs.

Common ADR Mistakes

Some common ADR mistakes include:

  1. Documenting Every Small Decision: ADRs do not serve as a record of all the things that the engineering team does. Pay attention to the decisions that have an effect on the architectural structure.
  2. Writing Too Much: A report from an ADR should set out the reasons behind the decision, not include a word-for-word record of all the conversations that took place. If it takes a person 20 minutes to grasp a simple decision, then the ADR is most likely too long.
  3. Writing Too Little: The opposite problem is also common, for example; “We picked Kubernetes because it's better.” But better in what way? Without any context being provided and without any trade-offs being discussed, the ADR fails to retain a great deal of useful information.
  4. Rewriting Old Decisions: If a decision does change, then do not rewrite the original ADR in silence. Rather, keep the original record and draft a new ADR that replaces it. The architectural history is thus preserved. For example:
0003-use-kubernetes.md ↓ 0012-move-to-managed-container-platform.md

The initial decision is still included in history.

Final Thoughts

ADRs offer a simple way of keeping architectural knowledge. They answer a question that code alone usually can't: “why was it built in this way?”

Ensure that they are kept short. Record the actual trade-offs. Keep them in a location where engineers can see them.

What we wish to achieve is not to keep a record of everything. The aim is for important decisions to remain understandable even after the initial conversation has ended.

Frequently Asked Questions

Are ADRs required for every architecture decision?

No.

Use them for decisions that are important enough for future engineers to understand.

How long should an ADR be?

As long as necessary to explain the decision clearly, but no longer.

Many useful ADRs fit on one or two pages.

Who should write an ADR?

Usually the engineer or team making the decision.

A technical writer or documentation engineer can help structure, edit, and maintain it.

Should you write an ADR before or after implementation?

Ideally, document the decision when it's made, before implementation begins.

But it's still useful to create an ADR afterward if an important decision was never documented.

Can an ADR be changed?

You can correct factual or formatting errors.

For a changed architectural decision, create a new ADR and mark the old one as Superseded.

What happens if a decision is rejected?

You can record rejected decisions too.

This can prevent teams from repeatedly discussing the same option without knowing why it was rejected.

Should an ADR include code?

Usually, no.

References