← cd ../blog

Why I write Architecture Decision Records

· 3 min read · #architecture #adr

Six months after a decision, nobody remembers why it was made. The person who made it may have moved on, and the context lives in a meeting nobody recorded. An Architecture Decision Record (ADR) fixes that with one short document per decision.

The format I use

# ADR-0007: Use AWS CDK for new platform stacks

## Status
Accepted

## Context
What problem are we solving? What constraints apply?

## Decision
What we chose, in one or two sentences.

## Consequences
What gets easier, what gets harder, what we must watch.

What makes a good ADR

What it changed for us

In architecture groups I've been part of, ADRs gave us a shared place to discuss trade-offs before building, and a quick answer for every new team member who asks "why is it like this?". The time spent writing them is small compared with the meetings they save.

If a decision is worth arguing about, it's worth writing down.