← All guides
Architecture decision records

Architecture decision records: why engineers repeat bad migrations

A new staff engineer opens a repository six months after handoff, sees a rigid retry queue or an unconventional SurrealDB schema boundary, and finds zero explanation in tickets or commit titles. Without the historical context, she has only the two bad moves Michael Nygard warned about in November 2011: blindly leave an outdated constraint in place, or rip it out blindly and re-break an edge case that took two outages to discover.

Author: Escherbridge. Published . Last reviewed: , America/Denver.

In "Documenting Architecture Decisions" (15 November 2011), Nygard noted why heavy architecture wikis rot while motivation gets lost: "Large documents are never kept up to date," whereas "An architecture decision record is a short text file in a format similar to an Alexandrian pattern." Each ADR captures "a set of forces and a single decision in response to those forces" for architecturally significant choices—anything shaping dependencies, interfaces, construction rules, or non-functional boundaries. When context shifts, old records stay in git marked deprecated or superseded rather than overwritten.

Whether your call governs idempotent HTTP retries or pins schema boundaries for BIM and IFC file exchanges, the operational cost is identical: five minutes of clear writing beats five days debugging why an invariant existed.

Anatomy of a decision record engineers actually read

Nygard's lightweight structure splits into five focused sections: Title ("ADR 1: Deployment on Ruby on Rails 3.0.10" is his canonical example), Context (the constraints and pressures, described neutrally), Decision (active voice: "We will …"), Status ("proposed", "accepted", "deprecated", or "superseded" pointing to its replacement), and Consequences (the resulting trade-offs). Stored monotonically as numbered Markdown files—Nygard's own convention sits at doc/arch/adr-NNN.md—they live right next to code diffs instead of vanishing in slide decks.

That handoff habit pairs directly with Architecture decision records on a delivery program when external engineering vendors transfer live systems to internal operators.

Scope and boundaries

Nygard's doc/arch/ layout, Rails example, and Markdown format are his conventions. They are not a PrimusNeo rule, and teams can organize files wherever maintainers look. This guide does not invent rework-savings metrics. It is not a certification.

A situation like this

An engineer simplifies a settlement consumer to retry failed POSTs automatically, unaware a three-year-old gateway quirk causes double debits—because the original guard lived only in a closed Slack thread instead of a decision record.

Sources

  1. Michael Nygard, "Documenting Architecture Decisions," 15 November 2011. https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
  2. Delivery sibling: Architecture decision records on a delivery program https://overseasgenai.com/guides/architecture-decision-records

Also in this section

The useful next step is to write a short record of the next architecturally significant decision, or to read the guides index. If something on this page is wrong, write to us.