How it works

Michael Nygard proposed the format in 2011: a title, a status, the context, the decision and its consequences, numbered in sequence. An ADR is not edited when minds change: a new one supersedes it.

The collection becomes the project’s memory. A new engineer reads why the system is the way it is, and nobody reopens a settled question without the reasons in front of them.

An example

ADR 14 records the choice of PostgreSQL over a document database: the data is relational, the team knows SQL, and reporting needs joins. Two years later, ADR 31 supersedes part of it for search, and links back.

Common mistakes

Recording decisions long after they were taken, without the context that was on the table.
Editing an old ADR instead of superseding it.
Keeping ADRs where the people who need them never look.

In Nodary

Nodary has an ADR template built in. A decision can be marked superseded by the record that replaces it, links say what it depends on, and the document’s history keeps its recent versions to compare and restore.

What Nodary does not do: it does not keep ADRs in your code repository: export them as Markdown if they must live beside the code.

Export from Nodary · Decision log template with ADRs

Try it on your own documents. The Free plan needs no card.

Create a free workspace

Sources

Documenting Architecture Decisions, Michael Nygard, Cognitect, 2011 · Architectural Decision Records, adr.github.io · Maintain an architecture decision record, Microsoft Azure Well-Architected Framework

Related terms

Decision logA decision log is a running record of a team’s decisions, each with its date, who decided, why, and the options set aside.
Product requirements document (PRD)A product requirements document (PRD) says what a product or feature must do and why: the problem, users, goals, requirements and scope.
Canon documentA canon document is the version a team has agreed is true: when documents disagree, it decides and the others defer to it.