Skip to content
Moteeb Asadimoteeb.asad@gmail.com

Blog

Architecture decision records: write down why

Six months from now, someone will open your code and ask why it was done this way. Most of the time, nobody knows. A short file per big decision fixes that: what was decided, why, what else was considered, and what it costs.

3 min read#architecture#adr#documentation#career

Six months from now, someone will open your code and ask why it was done this way.

Most of the time, nobody knows. The person who decided left, or forgot. So the code gets changed, and the same problem comes back.

One file per big decision

On my projects I keep a folder called docs/decisions. It has one short file for each big decision:

  • what was decided
  • why
  • what else was considered
  • what it costs

This is called an ADR, an architecture decision record.

docs/decisions/
  0001-record-architecture-decisions.md
  0002-use-postgres-for-the-job-queue.md
  0003-split-api-and-worker.md

Number the files so they stay in the order they were written. The name says the decision, not the topic.

What goes in one

Keep it short enough to write in ten minutes. A template like this is enough:

docs/decisions/0002-use-postgres-for-the-job-queue.md
# 2. Use Postgres for the job queue
 
Status: Accepted
Date: 2026-11-12
 
## Context
What problem are we solving? What constraints matter?
 
## Decision
What we chose, in one or two sentences.
 
## Alternatives considered
What else we looked at, and why we didn't pick it.
 
## Consequences
What this costs us. What gets harder because of it.

The example title is only an illustration. Write your own decisions in your own words.

The cost part matters most

Every choice has a downside. If it's written down, the next person knows it was accepted on purpose, not missed.

Without it, a known trade-off looks like a mistake. Someone "fixes" it, and walks straight back into the problem the decision was avoiding.

You can write it before it's built

A decision doesn't have to wait for the code. Write it when you decide, and mark it Proposed. One of mine is still marked proposed.

When it's built, change the status to Accepted.

Don't delete old decisions

If you change your mind, write a new decision that replaces the old one. Mark the old one Superseded, with a link to the new one.

The old file still matters. It shows what was tried, and why it stopped working.

Not for every small choice

Don't write one for every small choice. Only for things that are hard to undo:

  • the database
  • auth
  • background jobs
  • project structure

If changing it later would take a week, it gets a record. If it takes ten minutes, it doesn't.

A real example

The decision records for my Lead Follow-up project are public: lead-followup/docs/decisions.

If you're a junior, start now

Nobody will ask you to. The code shows what you did. Only you can write down why.

Write it while you still remember, because in three months you won't.

All posts