Architecture Decision Record
Six months from now you will open your own project and ask, out loud, why the database is SQLite when everything else in your life is Postgres. There was a reason. It was probably a good reason. It is gone now, and the person who could have told you was you, on a Tuesday, in a hurry.
An architecture decision record is the fix, and it is deliberately small: one markdown file per decision, a dozen lines, written the day you decide. Not documentation of the system. Documentation of the fork in the road: what you picked, what you didn't, and what would have to change for you to reverse it. The rejected options are the valuable part. "We chose X" is a fact you can read from the code. "We rejected Y because of Z" is knowledge that exists nowhere else, and it is exactly the knowledge that stops you from spending a weekend re-evaluating Y when Z is still true.
ADRs matter double when you work with a coding agent. A fresh agent session knows nothing about last month's reasoning, so it will cheerfully suggest the thing you already rejected, argue for it well, and you will half-remember disagreeing but not why. A folder of ADRs turns that argument into a file lookup. Point your CLAUDE.md or AGENTS.md at the folder and the agent stops relitigating settled questions.
Number them, never edit a decided one, and when a decision changes, write a new ADR that supersedes the old one. The history is the point.
# ADR-[number]: [Short decision title, e.g. "Use SQLite for local-first storage"]
Status: [proposed / accepted / superseded by ADR-NNN]
Date: [YYYY-MM-DD]
Deciders: [who was in the room, even if it was just you]
## Context
[2-5 sentences. What situation forced a decision? What constraints are real:
budget, deadline, team size, existing stack, traffic you actually expect
(not traffic you dream of)? Write this so a stranger understands why doing
nothing was not an option.]
## Decision
[One or two sentences, stated plainly. "We will use X for Y."
No hedging. If you can't state it in two sentences, the decision
isn't made yet.]
## Options considered
### Option 1: [the thing you chose]
- Why it fits: [1-3 bullets, concrete]
- What it costs: [be honest here; every choice costs something]
### Option 2: [the thing you rejected]
- Why it was tempting: [1-2 bullets]
- Why we rejected it: [the real reason. "Vibes" is not a reason.
"Adds a second service to run and we have no ops budget" is.]
### Option 3: [do nothing / the default you're leaving behind]
- Why we rejected it: [what breaks or stays broken if you don't decide]
## Consequences
- Good: [what gets easier now]
- Bad: [what gets harder, and you accept it]
- Neutral: [things that change without being better or worse]
## Revisit when
[The trigger condition, not a date. "If we pass 10k users." "If we hire
a second developer." "If the free tier goes away." A decision without a
revisit trigger silently becomes permanent.]Adaptation notes:
- Keep all ADRs in one folder in the repo,
docs/adr/ordecisions/, numbered in order: ADR-001, ADR-002. The number is an ID, not a ranking. - Write one for anything you spent more than an hour deciding, or anything a future you could plausibly undo by accident: database choice, hosting, auth approach, framework, "we don't do mobile."
- When a decision is reversed, do not delete or edit the old ADR. Write a new one, set the old one's status to "superseded by ADR-NNN", and move on. Editing history is how the confusion you were preventing comes back.
- Add a line to your CLAUDE.md or AGENTS.md: "Before proposing architecture changes, read docs/adr/ and do not re-propose rejected options unless the stated context has changed."
- The classic mistake is writing ADRs after the fact, in a batch, from memory. Those documents record what you wish your reasoning had been. Write it the same day or accept that the reason is gone.