Skip to content
← All articlesEngineering

Architecture Decision Records: A Practical Guide for Teams

Architecture Decision Records (ADRs) capture why your software is built the way it is. Learn the template, workflow and pitfalls for in-house and offshore teams.

Every software product is the sum of thousands of decisions: which database to use, how services talk to each other, why authentication works the way it does. A year later, most of the reasoning behind those decisions has vanished. The people who made them have moved on, or simply forgotten. New developers then either undo good decisions out of ignorance or protect bad ones out of fear.

Architecture Decision Records (ADRs) are a lightweight fix. An ADR is a short document that records one significant decision, the context in which it was made, and the consequences. For founders and CTOs working with an external or offshore team, they are one of the cheapest ways to keep knowledge inside your company rather than inside someone’s head.

What an ADR is (and is not)

An ADR describes a single architecturally significant decision. It is:

  • Short: usually one page, rarely more.
  • Immutable once accepted: if the decision changes, you write a new ADR that supersedes the old one rather than rewriting history.
  • Stored with the code: in the repository, so it is versioned, searchable and reviewed like everything else.

It is not a full design document, a meeting minute or a requirements specification. A design document explains how something will work; an ADR explains why one option was chosen over the alternatives.

When to write one

Not every choice deserves an ADR. A good rule is to write one when a decision is hard to reverse, expensive to change, or likely to be questioned later. Typical examples:

  • Choosing a framework, language or primary database.
  • Picking a hosting model, such as containers or serverless.
  • Deciding on an API style, authentication approach or tenancy model.
  • Adopting or rejecting a third-party service for a core capability.
  • Setting a rule that affects every developer, such as a branching strategy.

Choosing a button colour or renaming a variable does not need one. If you are unsure, ask: “Would a new engineer in 18 months wonder why we did this?”

A simple ADR template

The format popularised by Michael Nygard is still the most widely used because it is small enough that people actually fill it in.

Section What to write
Title A short noun phrase, numbered, for example “ADR-007: Use PostgreSQL as the primary database”
Status Proposed, Accepted, Deprecated or Superseded by ADR-xxx
Context The forces at play: requirements, constraints, team skills, budget, deadlines
Options considered Two or three realistic alternatives, with honest pros and cons
Decision The choice made, stated plainly
Consequences What becomes easier, what becomes harder, and what risks you accept

The “options considered” section is the most valuable part. It stops future debates from restarting at zero, because the team can see that an alternative was already weighed and why it lost.

A lightweight workflow

ADRs work best when they ride on processes you already have rather than adding new ceremony.

  1. Draft: the engineer proposing the change writes the ADR as a pull request in a docs/adr/ folder, with the status set to Proposed.
  2. Review: teammates, and where relevant the product owner or your internal technical lead, comment on the pull request. Disagreement is captured in the discussion rather than in lost chat threads.
  3. Decide: when consensus is reached, or the accountable person makes the call, the status changes to Accepted and the pull request is merged.
  4. Link: reference the ADR number in related code, tickets and pull requests.
  5. Revisit: when circumstances change, write a new ADR and mark the old one Superseded. Never delete the old one.

Keep a simple index file listing every ADR with its status so people can scan the history in a minute.

Why ADRs matter more with outsourced teams

If part of your engineering is done by an external partner, ADRs give you three concrete benefits.

  • Ownership of knowledge. The reasoning lives in your repository, not in a vendor’s heads. This makes any later transition, whether to another vendor or to an in-house team, far smoother. See our software handover and vendor transition checklist for what else to capture.
  • Visibility without micromanagement. Reading the ADR stream tells a non-technical founder what significant choices are being made and why, without joining every technical call.
  • Asynchronous collaboration. When teams work across time zones, a written decision with clear options removes the need for a live meeting to align. This pairs naturally with the habits in our guide to offshore team communication rituals.

A useful contractual habit is to require that any decision affecting architecture, security or third-party cost is recorded as an ADR and approved by your nominated technical owner before implementation.

Common mistakes

  • Writing them after the fact. An ADR written months later is a justification, not a record. Write it while the decision is live.
  • Too long. If it takes more than 20 minutes to write, the scope is probably a design document in disguise.
  • Hiding the trade-offs. Every option has costs. An ADR that lists only benefits will not be trusted.
  • Editing accepted records. Rewriting history destroys the main value, which is an honest timeline.
  • No one reads them. Add the ADR folder to your onboarding checklist so every new developer reads the key ones in their first week.

Getting started this week

You do not need tooling. Create a docs/adr/ folder, add the template above, and write three ADRs for the biggest decisions already baked into your product. Doing this retrospectively is imperfect but still valuable, and it sets the habit going forward.

If you would like a delivery partner that documents decisions as a matter of routine, our dedicated development teams work inside your repositories and processes, so the knowledge stays with you. You can contact us to discuss how we would set this up for your product.

Let’s build what’s next.

Tell us about your platform, your product idea or the systems you want to modernise. Someone from our Chennai engineering team will get back to you personally.