What is an Architecture Decision Record?
An Architecture Decision Record is a short document that captures a single architectural decision, its context, the options considered, and the rationale for the choice made. It is institutional memory encoded in version control.
Why do teams need a formal system for recording decisions?
Without written records, architectural decisions live in the memories of the people who made them, and those people leave, forget, or remember differently.
I have seen the same architectural debate happen 3 times in 18 months at a single company because nobody wrote down the outcome of the first discussion. The team spent approximately 12 hours per recurrence (across 6 engineers) relitigating a decision about message queue selection. That is 36 hours of senior engineering time spent answering a question that had already been answered. An ADR takes 30 minutes to write.
How should an ADR be structured?
An effective ADR follows a consistent template with 6 sections that capture context, decision, and consequences in under 2 pages.
Step 1: Title and Number
Use a sequential number and a short noun phrase. Format: ADR-0023: Use PostgreSQL for Event Store. The number provides chronological ordering. The title provides searchability. Store these as Markdown files in your repository at docs/adr/.
Step 2: Status
Every ADR has exactly one status: Proposed, Accepted, Deprecated, or Superseded. When a new decision replaces an old one, update the old ADR’s status to “Superseded by ADR-00XX” and link to the new record. This creates an auditable chain of architectural evolution.
Step 3: Context
Describe the forces at play. What technical constraints exist. What business requirements drove this decision. What was the team’s experience level with the options. Write 3 to 5 sentences. Be specific: “The team has 2 engineers with PostgreSQL experience and 0 with Cassandra” is useful context. “We need a database” is not.
Step 4: Decision
State the decision in a single declarative sentence. “We will use PostgreSQL 16 as the event store, with a partitioned table structure using monthly partitions.” No hedging. No qualifications. The decision section is the verdict.
Step 5: Options Considered
List each option that was evaluated with 2 to 3 bullet points summarizing its tradeoffs. This is the section that prevents relitigation. When someone asks “why didn’t we use Kafka,” the answer is already written. Include at minimum: the chosen option, the runner-up, and the option the team initially favored if different from the chosen one.
Step 6: Consequences
Document both the positive and negative consequences of the decision. Every architectural decision involves tradeoffs. If your consequences section only lists benefits, you have not thought hard enough. Include operational implications, maintenance burden, and known limitations. “PostgreSQL partitioning requires monthly maintenance scripts” is an honest consequence. Documenting it now prevents a 2 AM incident 8 months later.
What workflow ensures ADRs actually get written?
ADRs must be embedded in existing workflows, specifically pull request reviews, to become habitual rather than aspirational.
- Trigger rule: Any PR that introduces a new dependency, changes a data store, modifies an API contract, or alters deployment topology must include an ADR or reference an existing one. Enforce this with a PR template checkbox.
- Review process: ADRs are reviewed alongside code. At least 2 engineers must approve an ADR before its status moves from Proposed to Accepted. This ensures shared understanding, not just shared documentation.
- Lightweight tooling: Use
adr-tools(a CLI written by Nat Pryce) or a simple shell script that generates the template file with the next sequential number. The creation friction must be under 30 seconds. - Monthly review: Once per month, the team reviews the last 30 days of ADRs in a 15-minute standing meeting. This catches decisions that should have been recorded but were not, and surfaces ADRs that may need updating based on new information.
How do ADRs connect to the Stoic practice of reflective writing?
Both ADRs and Stoic journaling share the same core mechanism: externalizing thought to examine it honestly, transforming implicit assumptions into explicit statements that can be evaluated and revised.
The Stoics did not journal for posterity. Marcus Aurelius’s Meditations were never intended for publication. They were a tool for thinking clearly under pressure. ADRs serve the same function for engineering teams. The act of writing forces precision. You cannot write “we chose this because it felt right” in an ADR and have it pass review. You must articulate the actual reasons, which sometimes reveals that the reasons are weaker than you assumed.
I require every team I work with to adopt ADRs within the first 2 weeks of an engagement. The resistance is always the same: “we’re too busy shipping to document decisions.” The response is always the same: “you’re too busy relitigating undocumented decisions to ship.” Within 3 months, every team reports that ADRs save more time than they cost. The median estimate is 4 hours per week per team saved on repeated discussions. Over a year, for a team of 8 engineers billing at $150 per hour, that is approximately $124,800 in recovered engineering time. The ROI on 30-minute documents is difficult to argue with.