Architecture Decision Records

This directory holds ADRs — short, dated documents capturing significant architectural decisions, the alternatives considered, and the rationale for the choice.

The format follows Michael Nygard's original proposal: numbered, markdown, structured. Each ADR is immutable once merged — supersede with a new ADR rather than editing.

#Index

#Template

Copy this for new ADRs:

# NNNN. Title

**Status**: Proposed | Accepted | Deprecated | Superseded by NNNN
**Date**: YYYY-MM-DD

## Context

What is the situation that prompts this decision? What forces
are at play?

## Decision

What we're going to do.

## Alternatives considered

Other options we looked at, with honest trade-offs.

## Consequences

What becomes easier, what becomes harder, what we'll have to
watch for.

## References

Links to commits, discussions, external sources.

#Numbering

Four-digit left-padded, monotonically increasing. Don't renumber. If an ADR is superseded, the new one references it explicitly and the old one's status becomes Superseded by NNNN.

#When to write an ADR

Write one when the decision:

• Would be hard to revisit (affects API shape, dependencies, module boundaries).
• Trades off between plausible alternatives in a non-obvious way.
• Encoded reasoning future readers would want to understand without re-deriving from git history.

Skip for:

• Pure implementation choices reversible with a local refactor.
• Conventions covered by a style guide or lint rule.
• Individual bug fixes.

Rule of thumb: if explaining the decision would take a multi-paragraph git commit message, it probably deserves an ADR.