ADR
An Architecture Decision Record is a short document that captures a single architecture choice — what was decided, why, what alternatives were rejected, and what consequences the team accepts. ADRs are immutable: a new decision creates a new ADR that supersedes the old one. They live in the codebase or design tool so the rationale travels with the architecture.
ADRs typically follow a four-section structure: context (the problem), decision (what was chosen), consequences (what this commits the team to), and status (proposed / accepted / superseded). A team's ADR log is its institutional memory; without it, every architecture question gets re-litigated when a new engineer joins. The format was popularised by Michael Nygard's 2011 blog post and has become canonical for medium-to-large engineering organisations.
Long-form posts that explore adr in depth — when to use it, common failure modes, how AI helps.
- The connected delivery graph: one source of truth from PRD to prodMost teams ship software with five tools that don't talk to each other. The friction isn't any individual tool — it's the missing graph between them. This is the case for one connected graph.9 min read
- Should engineers write ADRs for every architecture decision?Yes — the bar isn't 'big decision', it's 'would a new engineer six months from now wonder why we did this?' Most teams under-write ADRs.8 min read
- How to migrate from Confluence to a structured doc toolThe 30-day playbook for leaving Confluence. The hard part isn't the content move — it's deciding what NOT to move.10 min read
Related terms
- Technical debt
Technical debt is the accumulated cost of shortcuts taken during development — code that's harder to change than it should be, missing tests, outdated dependencies, or architectural choices that no longer fit.
- Definition of Done
Definition of Done (DoD) is a team-wide checklist that every story must satisfy before being marked complete — typical entries include: code reviewed, tests passing, documentation updated, deployed to staging, AC verified.