How to Write an Architecture Decision Record (with Free Template)

An Architecture Decision Record (ADR) is a short document that captures a significant architectural decision along with the context that drove it, the options considered, and the consequences of the choice. ADRs are one of the most useful practices an architect can introduce to a team, and one of the most underused.

This post explains what an ADR is, why it matters, and walks through exactly how to write one. There is also a free ADR template on this site you can use directly.

Why architectural decisions need to be written down

Every software system accumulates decisions. Some are conscious and deliberate — "we will use event sourcing for the order domain." Others are implicit — "we put business logic in the service layer because that is what the first developer did." Over time, teams lose track of which decisions were made intentionally and which emerged by accident. New engineers join and cannot tell the difference. Existing engineers disagree about what was decided and why.

The cost is high: teams refight decisions already made, avoid changing things they do not understand, and build on assumptions that stopped being true years ago.

ADRs fix this by making decisions explicit and permanent. Once written, a decision has a record that can be referenced, questioned, and eventually superseded when it no longer applies.

The five parts of a good ADR

1. Title

Short and declarative. "Use PostgreSQL for transactional data" is better than "Database decision." The title should tell you what was decided, not just what was discussed.

2. Context

Describe the forces at play. What problem are you solving? What constraints exist? What was the situation that made this decision necessary? This is the most important section — a decision without context is nearly useless to someone reading it a year later.

3. Decision

State what you decided, plainly. "We will use PostgreSQL as the primary database for all transactional data." Avoid hedging. If the decision is not yet firm, the status (see below) should reflect that.

4. Status

One of: Proposed (under discussion), Accepted (decision made), Deprecated (no longer the right choice, but not yet replaced), or Superseded by ADR-XXXX (replaced by a later decision). The status is what makes ADRs a living record rather than a static archive.

5. Consequences

Describe what happens as a result of this decision — both positive and negative. What becomes easier? What becomes harder? What obligations does this create? Acknowledging negative consequences explicitly is one of the marks of a mature architectural record.

Optional: alternatives considered

For significant decisions, add a brief summary of the options you rejected and why. This prevents future teams from re-evaluating discarded options without knowing they were already considered. "We evaluated MongoDB but ruled it out because our query patterns are highly relational and we did not want to manage schema versioning at the application layer" is far more useful than silence.

What makes a bad ADR

The most common failure modes are: writing an ADR after the fact to justify a decision already implemented (it reads as a press release rather than a decision record); writing it too late, when context has been lost; writing it too early, before the key constraints are understood; and writing it so abstractly that it does not actually help anyone understand what was decided or why.

A good ADR is short — usually one page. It is specific. It is honest about trade-offs. And it is written at the time the decision is made, not six months later.

How to introduce ADRs to your team

Start with the decisions that are actively being debated. Do not try to backfill historical decisions — that creates busywork without value. Pick a lightweight format (the one on this site works well), put the ADRs in the repository next to the code, and review them as part of your architecture review process. Teams that treat ADRs as a natural part of design work rather than documentation overhead tend to maintain them. Teams that treat them as a compliance exercise tend to abandon them.