Write down your architecture decisions

Every system is the sum of decisions: which database, which messaging service, synchronous or asynchronous, one deployable or several. The decisions survive in the code. The reasons usually don't.

Then someone new joins, or you revisit a choice a year later, and the conversation starts again from scratch. Sometimes a good decision gets reversed because the constraint that drove it was forgotten. Sometimes a bad one survives because nobody dares to touch it.

#What an ADR is

An architecture decision record is a short document that captures one significant decision: the situation, what was decided and what follows from it. The format most teams use comes from Michael Nygard:

# 7. Use Azure Service Bus for order events

## Status
Accepted (2025-12-15)

## Context
Order, billing and shipping need to react to order changes. Billing must
process events in order per customer, and we can't lose events when a
consumer is down for maintenance. Volume is about 50,000 events a day.

## Decision
Publish order events to an Azure Service Bus topic, with one subscription
per consuming service. Use sessions keyed by customer ID where ordering matters.

## Consequences
- Consumers can be offline for days without losing events.
- Each consumer must handle duplicate messages.
- Adds a Service Bus namespace to provision and monitor.
- Event Grid was rejected because it doesn't guarantee ordering.

That's the whole thing. Most ADRs fit on one screen.

#What makes a good one

• One decision per record. Small records are easier to find, review and supersede.
• Context is the important part. Constraints, volumes, deadlines and team skills are exactly what gets forgotten.
• Name the alternatives you rejected, and why. That's the question people will ask later.
• Be honest about the downsides. Every decision has some. Writing them down shows they were considered.

#Where to keep them

In the repository, next to the code they describe, for example in docs/adr/, numbered in order:

docs/adr/
  0001-record-architecture-decisions.md
  0002-use-modular-monolith.md
  0007-use-service-bus-for-order-events.md

Because they're in the repo, an ADR can be reviewed in a pull request like any other change, and it's versioned with the code it explains.

#Don't edit history

When a decision changes, don't rewrite the old record. Write a new one, and mark the old one Superseded by ADR 12. The trail of decisions, including the ones you reversed, is the valuable part.

#When to write one

Write one when a decision is hard to reverse, affects more than one part of the system, or has been debated. You don't need one for every library upgrade.

#Takeaway

Spend ten minutes writing down the context, decision and consequences whenever you make a significant architectural choice. Keep the records in the repo, never edit old ones, and future you, along with everyone who joins after you, will know why the system looks the way it does.