Amazing Devs

Architecture Decision Records: A Practical Guide for Engineering Teams

Architecture Decision Records: A Practical Guide for Engineering Teams

Sketches of records and decision diagrams

An architecture decision record (ADR) is a short document that captures one significant technical decision, the context behind it and its consequences. Teams that keep ADRs can add developers, in-house or nearshore, without losing the reasoning behind their system. A new engineer reads the log and learns why the system looks the way it does, instead of interrupting the two people who remember. At Amazing Devs we place Brazilian developers into US teams, and we see the same pattern: the teams that write decisions down onboard people faster.

Amazing Devs
Add Skilled Developers to Your Team
Explore nearshore IT talent from Brazil, with recruitment focused on technical skills, cultural fit, and business alignment.

TL;DR

  • An ADR records one architecturally significant decision: the context, the choice, its status and its consequences, in a page or two.
  • Start from a five-part template (title, status, context, decision, consequences) and add an alternatives section.
  • Store ADRs as Markdown in the repository and review them through pull requests, like code.
  • Never edit an accepted ADR. Write a new one that supersedes it and link the two.
  • ADRs are the fastest way to bring new or remote engineers up to speed on why, not just how.

Table of Contents

What an architecture decision record is

Michael Nygard proposed the format in a 2011 post on documenting architecture decisions. His idea: a short text file for each architecturally significant decision, meaning one that affects structure, non-functional characteristics, dependencies, interfaces or construction techniques.

Martin Fowler describes an ADR as a short document, just a couple of pages, that captures a single decision with its context and significant ramifications. It also lists the serious alternatives with their pros and cons.

An ADR is not a change log and does not replace good commit messages. Red Hat’s guidance says the same: records are for larger architectural decisions.

Which decisions deserve a record

Not every choice needs one. AWS Prescriptive Guidance recommends an ADR for every architecturally significant decision in these areas:

  • Structure: for example, a microservices pattern.
  • Non-functional requirements: security, high availability, fault tolerance.
  • Dependencies and interfaces: APIs and published contracts.
  • Construction techniques: libraries, frameworks, tools and processes.

Microsoft’s Azure guidance adds a useful filter: record choices that affect the system’s structure or key quality attributes, or that are hard to reverse.

Examples in Google Cloud’s overview include choosing Pub/Sub over Cloud Tasks, or running regional GKE clusters. A good rule of thumb: if a new hire would ask “why on earth did we do it this way?”, write the ADR.

Should you write an RFC first?

Spotify’s engineering team describes three cases. Backfill an ADR when a blessed solution exists but is undocumented. For large changes, write an RFC (a request for comments) first, then an ADR once it concludes. For small changes, write a lightweight ADR directly.

What an ADR template contains

The arc42 FAQ summarizes Nygard’s original five sections: title, context, decision, status and consequences. Status is proposed, accepted, deprecated or superseded. Consequences list positive, negative and neutral effects.

Section What goes in it
Title Number plus a short phrase, such as “0018 Confirm bookings asynchronously”
Date and status Proposed, Accepted, Rejected, Deprecated or Superseded
Context The forces at play, described neutrally: requirements, constraints, priorities
Options considered Serious alternatives with pros and cons
Decision One clear statement, in active voice
Consequences What gets easier, what gets harder, follow-on decisions, accepted risks

Microsoft’s Engineering Fundamentals Playbook uses a numbered title, date, status, context, decision and consequences, and starts decisions with “We will…”. AWS says the decision should be stated in imperative language.

A short worked example

0007. Use PostgreSQL for the orders service.
Status: Accepted, 2026-03-02.
Context: Orders need transactional integrity across line items and payments. The team has strong SQL experience and expects moderate write volume.
Options: PostgreSQL (strong consistency, familiar, vertical scaling limits); a document database (flexible schema, weaker multi-record transactions).
Decision: We will use PostgreSQL.
Consequences: Easier reporting and joins. Harder horizontal scaling if volume grows tenfold. We will revisit at that threshold.

That is about 80 words. If it runs past two pages, you are probably writing a design guide, which Microsoft’s guidance says to avoid.

Qualities of a good record

The ADR community’s definition names four: rationale, specificity (one decision per record), timestamps and immutability. Existing information is not altered. You amend by adding information or supersede with a new ADR.

Four qualities that make ADRs effective

How to propose, review and approve ADRs

The review process matters as much as the template. AWS’s ADR process works like this:

  1. Create. Any team member can draft an ADR, but an owner is assigned. The owner submits it as Proposed.
  2. Review meeting. It opens with 10 to 15 minutes of silent reading while members add comments. Then the owner discusses each one.
  3. Outcome. Accept (the owner adds a timestamp, version and stakeholder list, and the record becomes immutable), rework (it stays Proposed with action items) or reject (the owner records why).
  4. Change later. Create a new ADR that supersedes the old one.

Silent reading is the detail worth copying. It stops the loudest voice from setting the outcome, which matters when your team spans several time zones.

Route ADRs through pull requests

An Agile Alliance experience report from the WIRE team describes reviewing ADRs through GitHub pull requests. That brought more people into design decisions and made architectural changes visible as they happened. It also made architecture a team activity rather than one architect’s job.

GitHub’s mobile team found that writing the ADR before the pull request leads to better reviews, because reviewers already understand the system change. AWS adds that code reviewers can flag violations by linking the ADR so the author fixes the code before merge.

The same discipline applies to any process where decisions need an audit trail. For a view on how teams keep review and approval flowing as things change, see this piece on automation change management. If your reviewers are spread across locations, our guide to a remote code review process covers the mechanics.

Route ADRs through pull requests

Where to store ADRs and how to keep them current

Google Cloud recommends Markdown files near the code, ideally in the same version control system so earlier versions can be reviewed. A wiki or shared document works as a fallback, and key decisions can be mirrored there for easier access.

Microsoft’s playbook suggests a doc/adr or doc/arch folder with a decision-log.md table summarizing each record. A practical layout:

  • One file per decision, numbered sequentially, such as docs/adr/0018-asynchronous-booking-confirmation.md.
  • An index file listing every ADR with its status.
  • Links from the ADR to the code, and from pull requests back to the ADR.
  • Superseded records kept, not deleted, with a link to the replacement.

Microsoft’s guidance treats the log as append-only: when a decision changes, a new record supersedes the original and the two are linked. Fowler makes the same point: don’t modify, link to the superseding decision.

Why ADRs pay off, and how teams get them wrong

The 18F team lists benefits for writers (surfacing assumptions, finding unconsidered options, reaching consensus, preventing knowledge hoarding) and for readers (faster onboarding, less reliance on one person, knowing whether a change was already considered).

A Chalmers action research study found development teams perceived ADRs as useful. The practical challenges were culture, tacit knowledge, process and tooling, including worries about documenting too much or too little and keeping records current.

InfoQ’s authors warn that ADRs lose purpose when teams lack a clear definition of “architectural”, or use ADRs as the only place decisions are recorded. They also should not become a way to deflect responsibility. Keep records small, specific and tied to real forces.

ADRs and growing or distributed teams

A decision log gives every new engineer the same starting context, whether they sit in the office or in São Paulo. For startups and scaling companies this reduces the cost of each hire: less time asking “why”, more time shipping. It also lets a nearshore developer challenge a decision with evidence, since the alternatives are already on the page.

If you are weighing how to add capacity, our guides on build vs buy engineering and timezone management pair well with a written decision log. Teams hiring engineers who work with AI tools can also use ADRs to record which AI-assisted workflows and tools the team has agreed on; see AI-native development.

One more practical step for tooling: automated checks in CI can verify that a decision still holds, such as a rule that modules may not import across defined boundaries, as the Software Engineering Guide describes.

Our perspective

We think of an ADR as onboarding material that happens to be written by the people who made the decision. When a company brings in developers from outside its own walls, the quality of the written record decides how quickly they contribute.

That is why we pair technical and cultural-fit assessment with a hiring process that handles the contracts and paperwork. Your engineering leads should spend their time writing the context and consequences of a decision, not chasing hiring logistics.

Our advice: adopt a one-page template this week, put it in the repo, and require an ADR link on any pull request that changes structure. Then add the developers you need to the team that already explains itself.

Gabriel

Add engineers who fit a documented team

A team with a clear decision log is ready for more people. Amazing Devs provides pre-vetted Brazilian developers through nearshore staff augmentation, with technical and cultural fit assessment, and we handle contracts and bureaucratic work so you can scale without the usual hiring overhead.

Amazing Devs

If you want developers embedded in your own processes, our Team Extension Model is built for that.

FAQ

What is the difference between an ADR and a design document?

An ADR records one decision and its reasoning in a page or two. A design document describes how a whole solution will work. Microsoft’s guidance warns against turning decision records into design guides.

Can I edit an ADR after it is accepted?

No. Accepted records are immutable. If the decision changes, write a new ADR that supersedes the old one and link them, as the AWS process describes.

Where should we keep ADRs?

Keep them as Markdown files in the same repository as the code, so they are versioned and reviewed with it. Google Cloud also notes a central wiki works if the repo is not accessible to everyone.

How long should an ADR be?

Short: Fowler says a couple of pages at most. Capture one decision, its context, the alternatives and the consequences, then stop.

Sources