Record your architectural decisions
"We write Architecture Decision Records (ADRs) to capture the reasons behind our technical choices while they are fresh."
Why this exists
Undocumented decisions are our most expensive source of technical debt. I have seen databases built in ways that seemed obvious in month one become incomprehensible by month six because the context was lost. ADRs prevent teams from reversing decisions without understanding why they were made in the first place.
Operational Flow
Trigger: Write an ADR when choosing between two or more valid alternatives. If you spent more than 30 minutes weighing options, put it in writing.
Format: Use the Nygard format (Title, Status, Context, Decision, Consequences). Keep it under a single page.
File location: Save ADRs in `docs/adr/` in chronological order, such as `0001-use-postgres-over-mysql.md`.
Status updates: When deprecating a decision, change the status of the original ADR to Superseded and link directly to the new one. Keep the history intact.
Review: Significant decisions (like choosing an ORM or database) require at least one other engineer to review the ADR before you merge.
Index: List every ADR in `docs/adr/README.md` with its title, date, and status so onboarding engineers can find them quickly.
Timing: Write the record before writing the code. Documenting after implementation turns the ADR into a rationalization.
What good looks like
- A new engineer reads six ADRs in 20 minutes and knows exactly why we chose Postgres over Redis for our queue.
- When an old decision causes friction, the developer reads the original ADR, finds that we predicted this exact tradeoff, and writes a superseding ADR.
- Instead of asking about a design choice in a Slack DM, you find the answer in a linked ADR.
What NOT to do
- Do not write ADRs post-hoc to justify decisions you already made.
- Do not use ADRs as design proposals. ADRs record final choices, not plans.
- Do not host ADRs in Notion or Google Docs. Keep them in the repository alongside the code.
- Do not write an ADR for minor code changes or configuration tweaks.
We make architectural decisions under constraints that disappear from memory within months. The team size, the budget, the deadlines, and the rejected alternatives all vanish, leaving behind code that looks arbitrary. The next engineer might try to refactor a system, unaware that they are reintroducing a bug we spent three days fixing. ADRs are a cheap way to prevent this.
Write them short. The Nygard format fits on one page because people actually read one-page documents during code reviews. Date them, number them, and reference them in commit messages. When you change your mind, update the status field of the original file and write a new one. The history of how the system evolved is just as important as its current state.