---

name: architecture-decision-records description: This skill should be used when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes. It provides ADR templates and best practices. allowed-tools: Read

Architecture Decision Records

Capture the context and rationale behind significant technical decisions using structured ADR formats.

When to Use This Skill

| Write ADR | Skip ADR | | -------------------------- | ---------------------- | | New framework adoption | Minor version upgrades | | Database technology choice | Bug fixes | | API design patterns | Implementation details | | Security architecture | Routine maintenance | | Integration patterns | Configuration changes |

Quick Start

1. Copy the template: cp docs/adr/template.md docs/adr/NNNN-your-title.md
2. Fill in: Context, Decision Drivers, Options, Decision, Consequences
3. PR for review (2+ senior engineers)
4. Update docs/adr/README.md index after merge

Core Concepts

An Architecture Decision Record captures:

• Context: Why we needed to make a decision
• Decision: What we decided
• Consequences: What happens as a result

ADR Lifecycle

Proposed --> Accepted --> Deprecated --> Superseded
                |
             Rejected

Read reference/adr-lifecycle.md for status transitions, deprecation patterns, and review checklists.

Process

1. Choose a Template

Pick the format that fits the decision's complexity:

| Decision Complexity | Template | |---------------------|----------| | Simple tech selection | Y-Statement (one paragraph) | | Medium decision | Lightweight ADR (0.5-1 page) | | Significant architecture change | Standard MADR (1-2 pages) | | Retiring a decision | Deprecation ADR | | Major cross-team proposal | RFC Style (2-4 pages) |

Read reference/adr-templates.md for all template formats ready to copy-paste.

2. Write the ADR

• Start with context -- explain the problem before the solution
• List 2-3 real alternatives with honest pros/cons
• State the decision clearly
• Document both positive and negative consequences with specifics

3. Review and Approve

• Submit as PR with 2+ senior engineer reviewers
• Consult affected teams
• Assess security, cost, and reversibility implications

4. Maintain

• Update ADR index after acceptance
• Create implementation tickets
• Never edit accepted ADRs -- write new ones to supersede

Read reference/adr-examples.md for complete worked examples (PostgreSQL selection, TypeScript adoption, MongoDB deprecation, event sourcing RFC).

Minimal Template (Copy-Paste Starter)

# ADR-NNNN: [Title]

## Status
Proposed | Accepted | Deprecated | Superseded by ADR-XXXX

## Context
[Why do we need to decide this? What's the problem?]

## Decision
We will [decision].

## Consequences
- **Good**: [benefits]
- **Bad**: [drawbacks]
- **Mitigations**: [how we'll address the bad]

Common Mistakes

| Mistake | Fix | |---------|-----| | Writing ADR after implementation | Write during design phase | | Listing only one option | Always include 2-3 real alternatives | | Vague consequences | Be specific: "Adds ~200ms latency to checkout" | | Editing accepted ADRs | Write new ADR that supersedes | | No decision drivers | List explicit criteria with priorities | | Missing rejected ADRs | Document rejected options too |

Directory Structure

docs/adr/
  README.md           # Index of all ADRs
  template.md         # Team's ADR template
  0001-use-postgresql.md
  0002-caching-strategy.md

Reference Files

| File | Contents | |------|----------| | reference/adr-templates.md | All formats: MADR, lightweight, Y-statement, deprecation, RFC | | reference/adr-examples.md | Complete worked examples for each format | | reference/adr-lifecycle.md | Status transitions, review checklists, automation with adr-tools |

Resources

• MADR Template
• ADR GitHub Organization
• adr-tools

Error Handling

Conflicting ADRs: When a new decision contradicts an existing ADR, create a superseding ADR that explicitly references and deprecates the old one.

Missing context: If the decision rationale is unclear or incomplete, flag it and request clarification before recording.