Template 08 — Architecture Decision Record (ADR)

Copy and fill to record a significant technical decision. One ADR per decision; number them; never delete (supersede).

ADR-<NNN>: <short title>

Status: <proposed / accepted / superseded by ADR-XXX> · Date: <date> · Deciders: <names>

Context

<The situation, constraints, and forces. What problem are we solving? What's true today (volume, latency/cost targets, compliance, team)?>

Decision

<The decision, stated clearly. "We will use X for Y because Z.">

Options considered

Consequences

• Positive: <what gets better — cost/latency/reliability/safety/velocity>
• Negative / tradeoffs: <what we accept>
• Risks & mitigations: <...>
• Reversibility: <easy/hard to undo; exit plan>

LLM-specific checks (if applicable)

• Cost impact (per resolved task) considered (Phase 15.05)
• Latency (p95) impact considered
• Eval/regression-gate impact (Phase 12.08)
• Security/privacy impact (Phase 14)
• Model-dependence / portability (can we swap providers? Phase 8)

Example (filled)

ADR-007: Put a gateway in front of all LLM calls. Context: Two providers, growing cost, no failover, keys scattered in services. Decision: Adopt a self-hosted proxy (LiteLLM-style) — provider adapters + routing + fallback + metering + key custody. Consequences: +resilience, +cost control, +no client keys; −one more service to run. Reversible (OpenAI-compatible). (Phase 8)

ADRs make your reasoning legible — exactly what senior/principal interviews and code reviews look for.