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:

proposed

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:

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:

frontmatter.md

Plan

Use when deciding what needs an ADR.

Decision Triggers:

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:

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

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