# What is an architecture decision record (ADR)?

An architecture decision record (ADR) is a short document recording one significant technical decision: its context, the choice made and its consequences.

Updated on 22 October 2026.

## 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](https://nodary.ai/docs/export)
- [Decision log template with ADRs](https://nodary.ai/templates/decision-log)

Try it on your own documents. The Free plan needs no card. [Create a free workspace](https://nodary.ai/sign-up)

## Sources

- [Documenting Architecture Decisions, Michael Nygard, Cognitect, 2011](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
- [Architectural Decision Records, adr.github.io](https://adr.github.io/)
- [Maintain an architecture decision record, Microsoft Azure Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record)

## Related terms

- [Decision log](https://nodary.ai/glossary/decision-log): A 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)](https://nodary.ai/glossary/product-requirements-document): A product requirements document (PRD) says what a product or feature must do and why: the problem, users, goals, requirements and scope.
- [Canon document](https://nodary.ai/glossary/canon-document): A canon document is the version a team has agreed is true: when documents disagree, it decides and the others defer to it.

https://nodary.ai/glossary/architecture-decision-record