Chapter 21: Architectural Decisions
fsa architectural-decisions adrs decision-records
Status: Notes complete
Overview
Chapter 21 addresses one of the most neglected responsibilities in software architecture: making and recording decisions in a durable, discoverable way. The chapter introduces three antipatterns that describe how architectural decision-making breaks down in practice, then presents Architectural Decision Records (ADRs) as the primary solution. By capturing the context and reasoning behind decisions — not just the decisions themselves — architects create living documentation that survives team turnover and prevents revisiting settled questions. The chapter closes with guidance on how generative AI can assist (but not replace) the architect’s judgment in this process.
Architectural Decision Antipatterns
These three antipatterns describe failure modes that architects fall into when managing decisions. Recognizing them is the first step toward fixing them.
Covering Your Assets Antipattern
Definition: The architect avoids or endlessly delays making architectural decisions out of fear of being wrong. The decision sits in limbo while the team waits for certainty that never comes.
Why it happens: Architects feel that a wrong decision reflects badly on them personally. They gather more and more information hoping to eliminate all risk before committing.
Why it fails: Delayed decisions are themselves decisions — usually bad ones. The team cannot make progress; downstream choices pile up waiting for the blocked decision. Paralysis has a higher cost than an occasionally wrong but well-reasoned call.
Solution: Make the decision with clearly documented reasoning. If it turns out to be wrong later, the documentation shows the reasoning was sound given what was known at the time. Own mistakes openly rather than hiding from decisions.
Groundhog Day Antipattern
Definition: The same architectural decision gets relitigated repeatedly in meetings. Every time the topic comes up — in a new sprint, with a new stakeholder, or in a new context — the team debates the same ground from scratch, never converging.
Why it happens: There is no record of why a prior decision was made. Team members who weren’t present, or who disagree with the outcome, re-open the discussion. The “why” has been lost even if the “what” is vaguely remembered.
Why it fails: Teams waste enormous meeting time. Trust erodes. Engineers disengage because decisions feel arbitrary and reversible.
Solution: Document decisions in ADRs so the rationale is captured, searchable, and authoritative. When someone wants to re-open a decision, they read the ADR first. If the context has genuinely changed, they propose a superseding ADR — otherwise the discussion ends.
Email-Driven Architecture Antipattern
Definition: Architectural decisions are made in email threads (or Slack/Teams messages), buried in inboxes, and never captured in a shared, searchable location.
Why it happens: Email is the path of least resistance. Decisions happen organically in conversation and no one takes the extra step to formalize them.
Why it fails: Architectural knowledge decays rapidly. New team members have no access to the history. Existing members can’t find the thread from 18 months ago. The institutional memory of the architecture exists only in the heads of a few senior people, creating dangerous key-person risk.
Solution: Any decision of architectural significance must leave email/chat and be recorded in a version-controlled ADR. Email threads can inform the ADR’s context section but are not a substitute for it.
Architectural Significance
Not every technical decision is an architectural decision. Treating all decisions as architectural creates noise and buries the truly important choices. Architects must distinguish decisions that warrant an ADR from those that can be delegated to developers or teams.
Criteria for Architectural Significance
A decision is architecturally significant if it meets one or more of these criteria:
| Criterion | Description | Example |
|---|---|---|
| Significant tradeoffs | The decision forces a meaningful tradeoff between competing quality attributes | Choosing eventual consistency vs. strong consistency |
| Affects nonfunctional characteristics | The decision directly influences performance, security, scalability, reliability, etc. | Choosing a caching strategy |
| Affects multiple teams | The decision constrains or coordinates work across team boundaries | Selecting a shared API style (REST vs. gRPC) |
| Hard to reverse | The decision is expensive or disruptive to change later | Choosing a primary database technology |
Delegating Non-Architectural Decisions
Decisions that are low-cost to reverse, affect only a single component, and carry no nonfunctional consequences can and should be delegated. Architects who over-claim decision authority become bottlenecks. Architectural governance should focus energy on the decisions that truly deserve it.
Architectural Decision Records (ADRs)
An Architectural Decision Record (ADR) is a short, structured document that captures a single architecturally significant decision. ADRs were popularized by Michael Nygard and have become a standard lightweight architecture documentation practice.
Core Philosophy
The critical insight is that the context and reasoning behind a decision are more valuable than the decision itself. Code and diagrams show what was built; ADRs explain why. Without the why, future architects either blindly follow past decisions or blindly overturn them.
Basic ADR Structure
Every ADR contains at minimum five fields:
| Field | Purpose | Notes |
|---|---|---|
| Title | Short imperative phrase naming the decision | e.g., “Use PostgreSQL as the Primary Database” |
| Status | Current state of the decision | Proposed / Accepted / Deprecated / Superseded |
| Context | Why this decision is needed; forces at play | Describes the situation without the solution |
| Decision | The chosen approach, stated positively | ”We will use X” not “We decided not to use Y” |
| Consequences | Tradeoffs — what becomes easier and what becomes harder | Both positive and negative consequences |
ADR Status Values
- Proposed: Decision is under discussion; not yet adopted
- Accepted: Decision has been approved and is in effect
- Deprecated: Decision is no longer recommended but not actively superseded
- Superseded: Decision has been replaced by a newer ADR (link to the new one)
Status transitions create a traceable history. A superseded ADR is never deleted — it remains in the record with a reference to what replaced it, preserving the full audit trail.
Extended ADR Fields
For more complex decisions, the basic structure can be extended:
- Alternatives Considered: Other options that were evaluated, with brief explanations of why each was rejected. This is especially important for preventing the Groundhog Day antipattern — it shows the team already considered the alternatives.
- Governance: How the decision will be enforced. Who reviews compliance? What is the exception process?
- Notes: Timestamps, authors, meeting references, links to related tickets or discussions.
Filled ADR Example
The following is a complete ADR illustrating all fields:
# ADR-0004: Use PostgreSQL as the Primary Relational Database
**Status**: Accepted
**Date**: 2025-03-14
**Authors**: Platform Architecture Team
---
## Context
Our order management service requires a relational database with strong ACID
guarantees for financial transaction records. The team has evaluated three
options: MySQL 8, PostgreSQL 16, and Amazon Aurora PostgreSQL. We need full
support for JSON columns (for flexible order metadata), robust full-text
search, and a rich extension ecosystem. Operational expertise on the team
is stronger in PostgreSQL than MySQL. Aurora is PostgreSQL-compatible but
adds vendor lock-in to AWS.
## Decision
We will use **PostgreSQL 16** as the primary relational database for the
order management service. All financial transaction records, customer
profiles, and order line items will be stored in PostgreSQL.
## Consequences
**Positive:**
- ACID guarantees eliminate a category of consistency bugs.
- JSON/JSONB columns allow flexible metadata without schema migrations.
- Strong community support; team has existing expertise.
- Rich extension ecosystem (PostGIS, pg_trgm for fuzzy search, etc.).
- No cloud vendor lock-in; can run locally, on-prem, or any cloud.
**Negative:**
- Horizontal write scaling requires application-level sharding or
read replicas; not natively multi-master.
- Operational burden of managing PostgreSQL clusters (vs. managed Aurora).
- Connection pooling (PgBouncer) needed at scale.
## Alternatives Considered
- **MySQL 8**: Rejected. JSON support is less mature; team expertise is
lower; no meaningful advantage over PostgreSQL for this use case.
- **Amazon Aurora PostgreSQL**: Rejected at this time due to AWS vendor
lock-in concerns. May be revisited if managed operations become a
priority. See ADR-0012 for cloud strategy.
## Governance
All new services requiring relational storage must use PostgreSQL unless
a superseding ADR is approved. Exception requests go through the
Architecture Review Board.
Storing ADRs in Version Control
ADRs should live alongside the code in the same version-control repository:
- Location:
/docs/adr/directory at the root of the repository - Naming convention:
NNNN-short-title-in-kebab-case.md(e.g.,0004-use-postgresql.md) - Format: Markdown — readable in any editor, renderable on GitHub/GitLab
Storing ADRs in version control means:
- Every ADR change has a commit history
- ADRs are reviewed in pull requests alongside the code they govern
- The architecture documentation is always co-located with the implementation
Never store ADRs in a wiki if the wiki is disconnected from the codebase — wikis go stale, lose history, and are abandoned when teams change.
ADRs as Living Documentation
Unlike architecture diagrams that rot as soon as the system changes, ADRs remain accurate because each new decision creates a new ADR rather than updating an old one. The history of decisions is the documentation. Superseded ADRs are preserved, not deleted.
ADRs for Team-Wide Standards
ADRs are equally effective for documenting team standards — coding conventions, testing requirements, deployment constraints. A standard documented as an ADR has context, rationale, and a governance section, making it far more persuasive and enforceable than a bare rule on a wiki page.
ADR Archaeology
When joining an existing system with no ADR history, architects can perform decision archaeology: reconstruct past decisions by examining the codebase, commit history, and any surviving documentation, then write ADRs retroactively. This is imperfect (the original context may be lost) but is far better than no record. Mark retroactive ADRs clearly with their reconstruction date and confidence level.
Leveraging Generative AI in Architectural Decisions
Large language models (LLMs) can accelerate the ADR authoring process in several concrete ways:
| AI Capability | How It Helps | Limitation |
|---|---|---|
| Draft generation | Given a brief description of the decision, an LLM can generate a complete ADR draft | LLM doesn’t know your system’s specific constraints |
| Alternatives enumeration | LLMs can suggest alternatives the architect may not have considered | Suggestions may be generic or inapplicable |
| Consequence identification | LLMs can brainstorm positive and negative consequences | May miss domain-specific or organizational consequences |
| Consistency checking | LLMs can compare a proposed ADR against existing ADRs for contradictions | Requires feeding existing ADRs as context |
AI as a Starting Point, Not a Decision Maker
The most important limitation: LLMs do not know your context. An LLM cannot know your team’s skill set, your organization’s risk tolerance, your existing vendor relationships, or the history of past decisions. An AI-generated ADR draft will be generic. The architect’s job is to edit it ruthlessly — filling in the specific context, validating the consequences against reality, and making the actual judgment call.
Generative AI is best used to:
- Overcome the blank-page problem when starting an ADR
- Pressure-test your reasoning by asking the LLM to argue for the alternatives
- Check your consequences section for blindspots
It should never be used to make the decision itself or to produce a final ADR without significant human editing and review.
Common Antipatterns
Covering Your Assets: Architect delays all significant decisions indefinitely, waiting for perfect information that never arrives. The cost is team paralysis and compounding downstream risk.
Groundhog Day: Decisions are made verbally but never documented. The same debate recurs every quarter because no one can point to a canonical record of what was decided and why. ADRs are the cure.
Email-Driven Architecture: The architecture lives in email threads and Slack messages. New team members can’t access the history, and the architecture becomes tribal knowledge held by a shrinking group.
ADR Inflation: Treating every trivial technical choice as an ADR. This buries important decisions in noise and makes the ADR corpus too large to navigate. Use the architectural significance criteria to filter.
Stale ADRs: Writing ADRs once and never updating statuses. An ADR for a decision that was superseded two years ago, still marked “Accepted,” actively misleads readers. ADR maintenance must be part of the architecture process.
Key Takeaways
- Covering Your Assets: Avoiding decisions out of fear of being wrong has a higher cost than occasionally making wrong decisions with documented reasoning.
- Groundhog Day: When the “why” behind a decision is not recorded, teams relitigate the same choices endlessly; ADRs break this cycle.
- Email-Driven Architecture: Decisions buried in email threads create architectural amnesia; any significant decision must be extracted into a durable, searchable record.
- Architectural Significance Criteria: A decision warrants an ADR if it involves significant tradeoffs, affects nonfunctional characteristics, crosses team boundaries, or is hard to reverse.
- ADR Core Fields: Every ADR needs Title, Status, Context, Decision, and Consequences — the Context and Consequences fields are the most valuable and most often neglected.
- Status Lifecycle: ADR statuses (Proposed → Accepted → Superseded) create an audit trail; superseded ADRs are preserved, never deleted.
- Version Control Colocation: ADRs stored alongside code in
/docs/adr/are reviewed, versioned, and maintained with the same discipline as the code itself. - AI Assistance: LLMs can draft ADRs and enumerate alternatives, but they cannot supply organizational context or make the judgment call — that remains the architect’s responsibility.
- ADR Archaeology: For systems with no existing ADR history, retroactively reconstructing decisions is worth the effort even if imperfect.
- Delegation Discipline: Not every technical decision needs an ADR; over-claiming architectural authority makes architects bottlenecks and buries important decisions in noise.
Related Resources
- ch22-analyzing-architecture-risk — Companion chapter on risk techniques; ADRs feed into risk documentation
- ch01-introduction-to-software-architecture — Foundational definition of architectural decisions
- ch02-architectural-thinking — How architects reason about tradeoffs, which ADRs must capture
Last Updated: 2026-05-29