# ADR Quick Reference

## What Is an ADR?

A short document capturing one architecture decision, its context, and consequences.

## Five Sections

| Section | Purpose |
|--------|---------|
| Title | Short, descriptive |
| Status | proposed, accepted, deprecated, superseded |
| Context | Options, constraints, forces |
| Decision | What we decided |
| Consequences | Positive, negative, follow-up |

## Status Lifecycle

```
Proposed → Accepted
Accepted → Deprecated (no replacement)
Accepted → Superseded (replaced by new ADR)
```

## When to Write

- Decision affects multiple teams or services
- Reversing would be costly
- Future developers will wonder "why?"

## When to Skip

- Trivial or easily reversible
- Temporary workaround
- Purely operational (unless architectural impact)

## File Layout

```
docs/adr/
  0001-use-redis-for-sessions.md
  0002-migrate-to-graphql.md
```

## Pitfalls to Avoid

- Writing too late
- One ADR with many decisions (split them)
- No link to implementation
- Only positive consequences (be honest)
- Never updating status when decisions change

## Tools

- **adr-tools** — CLI for create, link, supersede
- **Log4brains** — Web UI, Git integration
- **Markdown template** — Often enough