Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Architecture Decision Record

Pattern

A reusable solution you can apply to your work.

An architecture decision record captures a single design decision — the context, the options, the choice, and the reasoning — so future readers don’t have to guess why the system is built this way.

Also known as: ADR, Decision Record

Understand This First

  • Judgment – every ADR records the output of a judgment call.
  • Design Doc – a design doc describes the overall technical approach; an ADR captures one specific decision within or beyond that doc.
  • Tradeoff – the core of an ADR is the tradeoff it resolves.

Context

This is a strategic pattern. You’ve been making decisions throughout the project: which database to use, how to handle authentication, whether to split a service or keep it monolithic. Some of those decisions are recorded in design docs or buried in pull request comments. Most live only in the memories of the people who made them.

Six months later, a new team member looks at the codebase and asks: “Why are we using message queues instead of direct API calls?” Nobody remembers. The person who made the decision left the team. The Slack thread where it was debated has scrolled into oblivion. The new developer either accepts the status quo without understanding it, or revisits the decision and changes it without knowing what constraints made the original choice necessary.

In agentic workflows, the problem compounds. An AI agent operating across sessions has no memory of past decisions unless those decisions are written down. Every new session is a blank slate. Without recorded decisions, the agent makes fresh choices each time, potentially contradicting earlier ones or re-introducing problems that were already solved.

Problem

How do you keep track of design decisions so that anyone who encounters the system later, whether human or agent, can understand not just what was decided, but why?

Design docs capture the initial plan, but they don’t track the dozens of smaller decisions made during implementation. Code comments explain local choices but miss the larger picture. Meeting notes are scattered and unsearchable. You end up with a system shaped by hundreds of decisions that nobody can trace back to their reasoning.

Forces

  • Decisions made without documentation get relitigated. Team members waste time debating questions that were already resolved.
  • Writing decisions down takes time that could be spent building. The overhead needs to be small enough that people actually do it.
  • Decisions need enough context to make sense months or years later, but they shouldn’t require a PhD to write. Heavyweight formats discourage adoption.
  • Some decisions are easy to reverse; others lock you in. The format should distinguish between the two.
  • Agents need written context. A decision that lives only in someone’s head can’t guide an agent’s behavior.

Solution

Record each significant design decision as a short, structured document: the architecture decision record. An ADR follows a consistent format that makes it quick to write and easy to find.

The canonical structure, introduced by Michael Nygard, fits in a single page:

  • Title. A short noun phrase describing the decision. “Use PostgreSQL for the primary data store.” “Adopt event sourcing for the order pipeline.”
  • Status. One of: proposed, accepted, deprecated, or superseded. A superseded ADR links to the one that replaced it.
  • Context. What situation prompted this decision? What constraints, requirements, or forces shaped the options? Two to four sentences is usually enough.
  • Decision. What you chose to do. State it in active voice: “We will use PostgreSQL as the primary data store” rather than “It was decided that PostgreSQL would be utilized.”
  • Consequences. What changes as a result of this decision, including the benefits and the costs. What becomes easier? What becomes harder? What new constraints does this create?

Nygard summarized the decision sentence as: “In the context of [situation], facing [concern], we decided [decision] to achieve [goal], accepting [tradeoff].” That single sentence captures the essence of any ADR. If you can write that sentence clearly, the rest is supporting detail.

Store ADRs alongside the code they govern. A docs/decisions/ or adr/ directory in the repository works well. Number them sequentially (001-use-postgresql.md, 002-adopt-event-sourcing.md) so they form a chronological record. Version control gives you the audit trail for free: who proposed the decision, when it was accepted, and how the reasoning evolved through review.

Not every decision deserves an ADR. A useful filter: write one when the decision is hard to reverse, when it affects more than one component, or when you find yourself explaining the same choice to different people. “Which variable name to use” doesn’t need an ADR. “Which authentication protocol to adopt” does.

Tip

When directing an agent to make structural changes, point it at the ADR directory first. An agent that reads existing ADRs before proposing changes is less likely to contradict earlier decisions or reintroduce problems that were already solved.

How It Plays Out

A startup’s backend team debates whether to use REST or GraphQL for their public API. Two hours of meeting, two legitimate sides: REST is simpler and better supported by their client SDKs, but GraphQL would cut over-fetching for the mobile app. They pick REST. Mobile traffic is light, and SDK compatibility matters more right now. A developer writes ADR-012 in fifteen minutes: the context, the two options, the decision, and an explicit note that they’d revisit GraphQL if mobile traffic grows past 40% of requests. Eight months later, mobile traffic hits 35%. The team pulls up ADR-012 and reviews the original reasoning instead of restarting the debate from scratch.

An engineer working with a coding agent notices the agent keeps trying to add a caching layer in front of the database. Three separate sessions, three attempts at Redis integration. The engineer writes ADR-019: “Do not add a read cache until latency exceeds 200ms at P99. Current P99 is 45ms. Premature caching adds operational complexity without measurable benefit.” They add the ADR to the agent’s instruction file. The agent stops proposing caches. When latency eventually does climb, a future engineer reads ADR-019, understands the original reasoning, and writes ADR-031 to supersede it.

Consequences

ADRs create a searchable history of design reasoning. New team members learn why the system looks the way it does. Reviewers can evaluate proposed changes against the constraints that shaped earlier decisions. Agents operating in future sessions inherit the team’s accumulated judgment rather than starting from nothing.

The overhead is deliberately small. A well-written ADR takes ten to twenty minutes. That’s a fraction of the cost of relitigating the decision later, and it’s far less effort than a full design doc. The constraint is cultural: teams that adopt ADRs must actually write them, which means the format needs to stay lightweight enough that people don’t skip it under deadline pressure.

ADRs work best when you treat them as a living record. Mark superseded decisions rather than deleting them. The history of why you stopped doing something is as valuable as the history of why you started. A deprecated ADR that says “We stopped using message queues because latency was unacceptable” prevents a future developer from proposing the same approach without understanding why it failed.

The risk is a different kind of staleness than design docs face. Design docs go stale because the implementation drifts from the plan. ADRs go stale because the context changes: the constraint that drove the decision may no longer apply, but nobody has written a superseding record. Periodic reviews catch this drift before it becomes a trap. Ask “do our ADRs still reflect our actual constraints?” once a quarter, and update or supersede the ones that don’t.

  • Depends on: Judgment – every ADR is the written output of a judgment call.
  • Depends on: Tradeoff – the decision sentence in an ADR names the tradeoff being resolved.
  • Complements: Design Doc – a design doc describes the whole approach; ADRs capture individual decisions that arise during or after design.
  • Complements: Specification – specs describe what to build; ADRs explain why you’re building it that way.
  • Uses: Constraint – the context section of an ADR names the constraints that shaped the decision.
  • Enables: Memory – ADRs are a form of project memory that persists across sessions and team changes.
  • Enables: Instruction File – ADRs feed directly into the instruction files that govern agent behavior.

Sources

  • Michael Nygard introduced the architecture decision record format in his blog post “Documenting Architecture Decisions” (2011). His lightweight template and the “In the context of… we decided…” sentence structure became the de facto standard.
  • The me2resh/agent-decision-record project on GitHub extends Nygard’s ADR format with an agentic variant (AgDR) designed for documenting decisions made by AI coding agents, adding fields for agent identity, confidence level, and human review status.
  • Joel Parker Henderson maintains adr-tools, a collection of ADR templates, examples, and command-line utilities widely used by teams adopting the practice.