Architecture Decision Records: A Practical Guide for Engineering Teams

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.
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
- Which decisions deserve a record
- What an ADR template contains
- How to propose, review and approve ADRs
- Where to store ADRs and how to keep them current
- Why ADRs pay off, and how teams get them wrong
- ADRs and growing or distributed teams
- Our perspective
- Add engineers who fit a documented team
- FAQ
- Sources
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.

How to propose, review and approve ADRs
The review process matters as much as the template. AWS’s ADR process works like this:
- Create. Any team member can draft an ADR, but an owner is assigned. The owner submits it as Proposed.
- Review meeting. It opens with 10 to 15 minutes of silent reading while members add comments. Then the owner discusses each one.
- 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).
- 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.

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.
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
- Documenting Architecture Decisions, Cognitect
- Architecture Decision Record, Martin Fowler
- Why you should be using architecture decision records, Red Hat
- Using architectural decision records, AWS Prescriptive Guidance (PDF)
- Architectural decision record process, AWS
- Maintain an architecture decision record, Microsoft Learn
- Architecture decision records overview, Google Cloud
- Architecture decision records overview, Google Cloud Architecture Center
- When Should I Write an Architecture Decision Record, Spotify Engineering
- Question C-9-3, arc42 FAQ
- Design Decision Log, Engineering Fundamentals Playbook
- ADR characteristics, architecture-decision-record.github.io
- Distribute Design Authority with Architecture Decision Records, Agile Alliance
- Why Write ADRs, GitHub Blog
- Architecture Decision Records: Helpful now, invaluable later, 18F
- Exploring the Adoption and Effectiveness of Architecture Decision Records, Chalmers
- Has Your Architectural Decision Record Lost Its Purpose?, InfoQ
- Decision records, Software Engineering Guide
