Architecture Decision Records

Workflows for authoring, reviewing, planning, updating, and backfilling Architecture Decision Records (ADRs).

When to Use

• Creating a new ADR for a technology or architecture decision
• Reviewing an existing ADR for quality and completeness
• Deciding whether something warrants an ADR
• Updating ADR status (accepting, deprecating, superseding)
• Backfilling undocumented decisions from git history
• Adding ADR references to code for traceability

Workflows

Author

When creating a new ADR.

Process:

1. Determine next ADR number:

   ls docs/src/adr/ | grep -oP '\d+' | sort -n | tail -1

2. Create file: docs/src/adr/adr-NNN-title-in-kebab-case.md
3. Add frontmatter (per frontmatter.md rule):

   ---
   id: <uuidv4>
   project:
     id: <project-uuid>
   title: "ADR-NNN: <Title in Imperative Mood>"
   status: proposed
   tags: [adr, <domain>]
   related:
     supersedes: []
     depends-on: []
   ---

4. Fill required sections (see template in references/adr-template.md)
5. Include at least one Mermaid diagram
6. Mark incomplete sections with INVESTIGATE markers

Required Sections:

Section	Guidance
Status	Start with proposed
Context	Problem statement, constraints, why now
Decision Drivers	Prioritized factors influencing the choice
Considered Options	2+ alternatives with honest trade-offs
Decision Outcome	Specific choice with rationale
Diagram	Mermaid diagram showing architectural impact
Consequences	Positive, negative, and neutral outcomes

INVESTIGATE Markers:

For sections that cannot be filled from available information:

- [INVESTIGATE: Confirm scaling requirements with infrastructure team]
- [INVESTIGATE: Benchmark Option 2 vs Option 3 performance]

These signal incomplete sections for later follow-up without blocking the ADR.

Title Convention:

Use imperative mood — describe the action, not the outcome:

Good	Bad
Use PostgreSQL for user data	PostgreSQL was chosen
Adopt event sourcing pattern	Event sourcing decision
Migrate from REST to gRPC	REST vs gRPC comparison

Review

Use the E.C.A.D.R. checklist when reviewing ADRs.

## ADR Review (E.C.A.D.R.)

### Core Quality
- [ ] **E**xplicit problem statement — context clearly states the problem
- [ ] **C**omprehensive options — 2+ alternatives with trade-offs
- [ ] **A**ctionable decision — specific, implementable choice stated
- [ ] **D**ocumented consequences — positive, negative, and neutral listed
- [ ] **R**eviewable — readable by someone without current context

### Structure
- [ ] Frontmatter with id, status, project.id
- [ ] Status is valid (Proposed/Accepted/Deprecated/Superseded/Withdrawn)
- [ ] One decision per ADR
- [ ] Title in imperative mood
- [ ] At least one Mermaid diagram
- [ ] No placeholders or hand-waving
- [ ] Alternatives include honest trade-offs
- [ ] INVESTIGATE markers for known gaps (not silent omissions)

### Strategic Lenses (for significant decisions)
- [ ] Chesterton's Fence: if changing existing, original purpose documented?
- [ ] Path Dependence: irreversibility assessed, exit strategy defined?
- [ ] Second-System Effect: scope bounded, not over-engineering?

Common Issues:

Issue	Fix
Vague context ("we need a database")	Add constraints, requirements, and "why now"
Single option presented	Add 2+ alternatives with honest pros/cons
Missing trade-offs	Every choice has downsides — document them
No diagram	Add Mermaid diagram showing architectural impact
Placeholder sections ("TBD")	Use INVESTIGATE markers with specific questions
Multiple decisions in one ADR	Split into separate, focused ADRs
Passive title ("Database was selected")	Use imperative mood ("Use PostgreSQL for X")
Missing frontmatter	Add per frontmatter.md rule

Plan

Use when deciding what needs an ADR.

Decision Triggers:

Trigger	ADR?	Why
Technology choice (DB, framework, language)	Yes	Shapes system for years
Architectural pattern (microservices, event-driven)	Yes	Affects all future development
Infrastructure decision (cloud, deployment)	Yes	Lock-in implications
Security approach (auth, encryption)	Yes	Compliance and risk
API design (versioning, format)	Yes	External contract commitment
Build/CI pipeline architecture	Yes	Affects all contributors
Data model or schema design	Yes	Migration cost grows over time
Implementation detail (function names)	No	Too granular, easily changed
Temporary workaround	No	Not architectural
Minor tooling (linter config, editor settings)	No	Low impact, easily reversible
Standard library usage	No	No real alternatives

Scope Check:

Before writing, verify the ADR is scoped to one decision:

• Can you state the decision in one sentence? If not, split.
• Does the ADR cover multiple independent choices? Split each into its own ADR.
• Is the decision reversible with minimal effort? Probably doesn't need an ADR.

Timing:

When	Approach
Before implementation	Ideal — decision drives the work
During implementation	Acceptable — capture as you learn
After implementation	Backfill — better late than never

Update

When changing ADR status or superseding decisions.

Status Transitions:

Proposed → Accepted     (team/lead approval)
Proposed → Withdrawn    (rejected before implementation)
Accepted → Deprecated   (no longer relevant, not replaced)
Accepted → Superseded   (replaced by newer ADR)

Supersession Workflow:

1. Create new ADR with the replacement decision
2. In new ADR frontmatter: related: { supersedes: [<old-adr-uuid>] }
3. In new ADR context: reference the old ADR and explain why it's being replaced
4. Update old ADR:
   • Change status: superseded
   • Add note: Superseded by [ADR-NNN](./adr-NNN-title.md)
5. Never delete the old ADR — it preserves decision history

Deprecation:

1. Update status: deprecated
2. Add context explaining why the decision is no longer relevant
3. No replacement ADR needed (unlike supersession)

Backfill

When reconstructing undocumented decisions from git history.

Process:

1. Classify files by architectural significance:

   Tier	Files	Signal Strength
   0	Dependency manifests (Cargo.toml, package.json)	Highest — every change is a choice
   1	Infrastructure (Dockerfile, CI configs, terraform)	High — how the system runs
   2	Domain structure (core modules, entry points)	Medium — system shape
   3	Interface contracts (API schemas, protobuf)	Medium — external commitments

2. Identify decision commits — look for structural changes, not edits:

   • New directory created
   • Dependency added/removed/major-bumped
   • New entry point or service
   • CI pipeline added or significantly changed

3. Cluster related commits into single decisions:

   • Related by intent, not just proximity
   • Typically spans days to weeks, not months
   • Should have a name you could say in a sentence ("the Redis migration")

4. Ask for context before generating — don't invent rationale:

   • What problem prompted this decision?
   • What alternatives were considered?
   • What trade-offs were accepted?

5. Generate ADR with reconstructed footer:

   ---
   *Reconstructed from commits abc123..def456 (2024-01-10 to 2024-01-12)*

Quality Bar:

A good backfilled ADR could have been written at the time of the decision. It captures "why", stands alone, and is honest about what's reconstructed vs confirmed.

Quick Reference

ADR Naming

docs/src/adr/adr-NNN-title-in-kebab-case.md

Required Frontmatter

---
id: <uuidv4>
project:
  id: <project-uuid>
title: "ADR-NNN: <Title>"
status: proposed  # proposed | accepted | deprecated | superseded | withdrawn
tags: [adr]
related:
  supersedes: []
  depends-on: []
---

Section Quick Reference

Section	Required	Content
Status	Yes	Current lifecycle state
Context	Yes	Problem, constraints, "why now"
Decision Drivers	Yes	Prioritized factors
Considered Options	Yes	2+ alternatives with trade-offs
Decision Outcome	Yes	Chosen option with rationale
Diagram	Yes	Mermaid showing architectural impact
Consequences	Yes	Positive, negative, neutral
References	No	Related ADRs, docs, links

aRustyDev Conventions

• ADRs live in docs/src/adr/ (mdBook documentation)
• ADR format documented in CLAUDE.md under "ADR Format"
• Frontmatter follows frontmatter.md rule (UUIDs, project.id, status)
• Related ADRs referenced by UUID in related: frontmatter, not file path
• ADRs linked from issues and plans when they drive implementation decisions

See Also

• references/adr-template.md — complete MADR template with frontmatter
• references/quality-checklist.md — full E.C.A.D.R. criteria and strategic lenses
• references/code-traceability.md — language-specific ADR references in code
• references/decision-triggers.md — detailed guidance on what warrants an ADR
• examples/technology-selection.md — example: choosing a CLI parsing library
• examples/architectural-change.md — example: adopting a new pattern
• tables/status-lifecycle.md — status transitions and governance