Most teams don’t skip Architecture Decision Records because they don’t see the value. They skip them because the templates they’ve seen are a full page of headers — Context, Decision, Consequences, Alternatives Considered, Status, Date, Author, Related Decisions — and nobody has time to fill that out for a decision that took twenty minutes to make.

You don’t need that. You need three paragraphs.

The three-paragraph format

# ADR: Use Postgres row-level locking instead of a separate lock table

We need to prevent two workers from processing the same job twice.
The naive approach was a separate `job_locks` table with a TTL,
but that adds a second source of truth that can drift from the
jobs table if a worker crashes mid-lock.

We're using `SELECT ... FOR UPDATE SKIP LOCKED` on the jobs table
itself. One worker claims a row, others skip it and move to the
next unclaimed row. No separate table, no TTL to tune, no drift.

Tradeoff: this only works because we're already on Postgres and
job volume is low enough that row locks don't contend. If we ever
shard the jobs table or move to a queue service, revisit this.

Paragraph one: the problem, and the option you didn’t pick. Paragraph two: what you’re doing instead. Paragraph three: the tradeoff, and the condition under which this decision should be revisited.

That’s it. No status field — the file existing means it’s active; delete it or supersede it when it’s not. No “alternatives considered” section — the option you didn’t pick is already in paragraph one, which does the same job with fewer words.

Why this length wins

A one-page ADR template has a hidden cost: it makes writing one feel like a big deal, so people only write them for “big” decisions, and everyone disagrees about what counts as big. A three-paragraph version is cheap enough to write for anything with a real tradeoff — which means you actually get a trail, not just the two decisions per quarter that someone remembered to formalize.

The real value of an ADR isn’t the decision, it’s the option you rejected and why. Six months from now, someone will propose the job_locks table again, because it’s the obvious first idea. The ADR saves that conversation.

Where to put them

In the repo, next to the code, not in a wiki. docs/adr/0001-job-locking.md, numbered sequentially. A wiki page drifts out of sync with the code and nobody notices. A file in the repo gets reviewed in the same PR as the change it justifies, and shows up in git blame when someone’s confused later.

When to write one

Write one when you catch yourself explaining a decision verbally for the second time. The first time, it’s a conversation. The second time, it’s a pattern — someone else will ask the same question, and it’s cheaper to write it down than to keep repeating yourself in Slack.

Skip it for decisions with only one reasonable option. An ADR for “we’re using Git” is noise. An ADR is for the fork in the road, not the only road there was.

Superseding old decisions

Don’t edit an old ADR to reflect a new decision — that destroys the historical record of what you believed and why, at the time. Add a new one, and put a single line at the top of the old file:

> Superseded by 0014-move-to-queue-service.md

Now anyone who finds the old decision via search or git blame gets redirected instead of misled. The trail of “we believed X, then we believed Y, here’s why” is worth more than either decision on its own — it’s the only artifact that shows your team’s reasoning actually evolved instead of just changing its mind.