Also called ADR, Architectural decision record, Decision record
In depth Architectural decision records: capture the why: a template, when to write one, and how to recover decisions you never wrote down.
How an ADR is structured
Michael Nygard described the format in his 2011 post "Documenting Architecture Decisions": one short file per decision, numbered, kept with the code, and left unedited after acceptance except for its status. The five parts:
| Part | What it holds |
|---|---|
| Title | A short noun phrase: "Use Postgres for the job queue" |
| Status | Proposed, accepted, deprecated or superseded |
| Context | The forces: constraints, deadlines, what else was considered |
| Decision | What the team will do, in active voice |
| Consequences | What it gains and what it costs, good and bad |
A minimal record:
# 7. Use Postgres for the job queue
Status: Accepted
## Context
We need retries and delayed jobs. We already run Postgres, and a broker
is another service to operate for a 2-person team.
## Decision
Use a jobs table with SELECT ... FOR UPDATE SKIP LOCKED.
## Consequences
No new infrastructure. Throughput is capped at a few thousand jobs per
second; revisit if we pass that.When a decision changes, you write a new record and mark the old one superseded. The history of what was believed, and when, stays readable.
Why ADRs matter
Code shows what a system does. Tests show whether it works. Neither says why it has this shape, so an unusual retry loop or a wrapper around a library looks like a mistake someone should clean up. Without the record, the next engineer (or coding agent) either keeps it out of fear or removes it and repeats the original incident. A two-paragraph ADR is cheaper than that archaeology. It also gives code review one place to argue about a decision, instead of in every later pull request.
How to write ADRs yourself
- adr-tools (Nat Pryce): shell scripts that create numbered Nygard-style files and mark records superseded.
- MADR (Markdown Architectural Decision Records): a template that adds considered options and pros and cons, maintained at adr.github.io alongside other tooling.
- Plain Markdown in
docs/adr/: a numbered file and a pull request is enough. Pick one template and keep it.
Write one for decisions that are expensive to reverse, such as a datastore, a service boundary or an auth model. Skip choices a pull request description already covers. The manual approach has one gap: it only captures decisions someone remembered to write down at the time.
How repowise handles ADRs
repowise reads ADRs you already have and also recovers decisions nobody recorded. During repowise init and repowise update it mines these sources (listed in docs/layers/DECISIONS.md):
- ADR files in folders such as
docs/adranddocs/decisions(Nygard and MADR headings), parsed directly with no model. - Inline markers such as
# WHY:and# DECISION:in comments, also with no model required. - Commit messages, pull request bodies and rationale comments, which need a configured LLM and are skipped when none is set.
- Local coding-agent sessions, off by default.
Capture from ADR files, markers, agent sessions, conventions and manual or agent entry needs no LLM; commit, pull request and comment mining need a model. Extraction only proposes candidates. A person, a signed agent, or a committed ADR with status accepted that names what it governs makes a record govern.
Each record is linked to the files it governs and gets a staleness score from 0 to 1: the share of those files changed since the decision was recorded. At 0.5 or above an accepted decision is marked needs_review.
Agents read decisions through the get_why MCP tool, one of the 10 repowise MCP tools. On the CLI, repowise decision has add, list, show, confirm, dismiss, deprecate, health, candidates, export and other subcommands. See the decisions feature and the decision records guide.