# Architecture Decision Records (ADR)

> Document architectural decisions with context, alternatives, and consequences.

## When to Use
- Significant technical decision (database choice, framework, architecture pattern)
- "Why did we choose X?" — the ADR answers this in 6 months
- Team onboarding — new members understand the reasoning

## ADR Template
```markdown
# ADR-[NUMBER]: [Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Context
[What is the issue we're facing? What forces are at play?
2-3 paragraphs maximum.]

## Decision
[What did we decide to do? Be specific.]

## Alternatives Considered
### Option A: [Name]
- Pros: [list]
- Cons: [list]
- Why rejected: [1 sentence]

### Option B: [Name]
[Same structure]

## Consequences
### Positive
- [What gets better]

### Negative
- [What gets worse or becomes harder]

### Risks
- [What could go wrong with this decision]

## Review Date
[When should we revisit this decision?]
```

## Principles
- Write ADRs at decision time, not after — context fades fast
- Include rejected alternatives — future you needs to know what was considered
- Keep them short — one page maximum
- Number them sequentially — ADR-001, ADR-002
- Never delete, only supersede — the history matters
