How to Write an Architecture Decision Record

Six months from now, someone will look at your architecture and ask "why did we do it this way?" If the answer lives in a Slack thread, a meeting that was not recorded, or someone's head, it is effectively lost. Architecture Decision Records capture the context, reasoning, and tradeoffs behind significant technical decisions so they survive team turnover, memory fade, and organizational growth.

Step 1: Know When to Write an ADR

Not every decision needs an ADR. Writing one for "we chose camelCase for variable names" wastes everyone's time. Writing one for "we chose PostgreSQL over MongoDB" prevents the same debate from recurring every quarter.

Write an ADR when:

• The decision is hard to reverse (database choice, API paradigm, auth provider)
• Multiple viable options were considered and the choice is non-obvious
• The decision affects multiple teams or services
• Future engineers will likely question the choice without context
• You are rejecting a popular or expected approach (choosing REST over GraphQL when the org defaults to GraphQL)

Skip an ADR when:

• The decision follows an established pattern (using the team's standard library)
• The choice is trivially reversible (a utility function's implementation)
• Industry consensus is overwhelming (using HTTPS, hashing passwords)

A good rule of thumb: if you spent more than an hour discussing the decision in a meeting, it deserves an ADR.

Step 2: Follow the Standard Format

Michael Nygard's original ADR format has five sections. It has endured because it is minimal and sufficient.

Each section has a purpose:

• Status — Current state: proposed, accepted, deprecated, superseded. Include the date.
• Context — The forces at play. What problem are we solving? What constraints exist? What options did we consider? Write this for someone who was not in the room.
• Decision — What we chose. One sentence.
• Rationale — Why we chose it. This is the most valuable section. Explain what made this option better than the alternatives for our specific situation.
• Consequences — What follows from the decision, both positive and negative. Be honest about downsides.

Step 3: Manage ADRs as a Living Log

ADRs are not write-once documents. They form an evolving record of your architecture's history.

File naming: Number them sequentially. adr-0001-use-nextjs.md, adr-0002-use-supabase.md. The number provides a chronological ordering. Never reuse numbers.

Storage: Keep them in the repository, typically in docs/adr/ or docs/decisions/. They should live next to the code they describe. They go through the same review process as code — pull requests with team review.

Superseding decisions: When a decision is reversed, do not delete or edit the original ADR. Create a new one that references it:

Update the original ADR's status to Superseded by ADR-0023. The history of why REST was originally chosen and why it was later replaced tells a more complete story than either decision alone.

Index file: Maintain a simple table of contents:

Step 4: Make ADRs Part of Your Culture

An ADR practice only works if the team actually uses it. These patterns help:

Write ADRs during the decision, not after. Writing the context and rationale while the discussion is fresh takes 20 minutes. Reconstructing it three months later takes hours and produces a worse result.

Review ADRs in pull requests. An ADR is a proposal when in "Proposed" status. Team members review the reasoning, suggest alternatives that were missed, and challenge assumptions. This is more productive than debating in a meeting because the arguments are written down and can be referenced later.

Reference ADRs in code. When someone encounters a surprising architectural choice, a comment pointing to the ADR saves them from re-investigating from scratch:

Review ADRs during onboarding. New team members should read the ADR log as part of their first week. It answers the "why" questions they would otherwise ask in every code review for the next three months.

The return on investment of ADRs is not immediate — it compounds. Each ADR saves 30 minutes of re-discussion the first time someone asks "why." Over a year, across a growing team, that compounds into weeks of saved time and significantly better decisions because the reasoning behind prior choices is accessible to everyone making new ones.