Architecture Decision Records: The 1-Page Version

A one-page ADR is an Architecture Decision Record compressed to six fields — Title, Status, Context, Decision, Consequences, References — that fits on a single screen. It keeps everything that makes ADRs valuable and drops the ceremony of the canonical four-to-six-page format.

The canonical Michael Nygard format runs four to six pages, which feels disproportionate to most decisions and implies more formality than how decisions actually get made. By the time someone has time to write the full version, the decision is weeks old and the context is gone.

Write one when a decision is hard to reverse (more than a week of work to undo), has architectural consequences that aren't obvious from the code, or was contested before being made. Don't write one for library versions, implementation details, or anything fully captured in code or config.

In the repository, under docs/decisions/ as numbered markdown files like 0001-use-postgres.md. Keeping them with the code means they're versioned alongside it and survive Confluence and Notion migrations. Tools like adr-tools and log4brains help but are optional.

Proposed, Accepted, Superseded by ADR-NNN, and Deprecated. That is the entire state machine — no rejected, no under review — and the typical path is Proposed → Accepted, with a small fraction eventually marked Superseded.

Don't delete it. Mark the status as Superseded (or Deprecated) and keep both records in the repo. The original reasoning is part of the value: months later someone can read why the earlier decision was made and avoid recreating the same mistake.