Architecture Decision Records

ADRs document significant technical decisions with their context and consequences.

When to Create an ADR

Create an ADR when:

• Choosing between technologies (database, framework, language)
• Defining system boundaries or integration patterns
• Establishing conventions that affect multiple components
• Making decisions that are hard to reverse

Do NOT create an ADR for:

• Trivial choices with obvious answers
• Temporary decisions or experiments
• Implementation details within a single component

ADR Format

# [NUMBER]. [TITLE]

**Status**: [proposed | accepted | deprecated | superseded by [NUMBER]]

## Context

[What situation prompted this decision? What constraints exist?
Keep factual - describe the problem, not the solution.]

## Decision

[What is the decision? Be specific and actionable.
Start with "We will..." or "Use..."]

## Consequences

[What are the results? Include both positive and negative.
- Positive: benefits, improvements
- Negative: trade-offs, new constraints, risks]

Status Lifecycle

• proposed: Under discussion, not yet decided
• accepted: Decision is final and in effect
• deprecated: No longer applies (context changed)
• superseded by [N]: Replaced by a newer decision

Writing Tips

• Title: Use short noun phrases ("Use PostgreSQL", "Event-Driven Architecture")
• Context: Focus on forces and constraints, not history
• Decision: One clear statement, not multiple options
• Consequences: Be honest about trade-offs

Naming Convention

Use sequential numbering: 001-use-postgres.md, 002-event-driven.md