Skip to content

Architecture Decision Records

Architecture Decision Records, or ADRs, document important technical decisions that should outlive a single PR description.

ADR Format

Each ADR should include:

  • Context
  • Problem
  • Options
  • Decision
  • Consequences

Naming Convention

Use zero-padded sequential names:

0001-settings-engine.md
0002-cache-strategy.md
0003-admin-settings-ui.md

When ADRs Are Required

Create an ADR for major architecture changes, cache systems, compatibility layers, large admin systems, frontend infrastructure decisions, persistence strategy changes, new dependency categories, or release/packaging architecture that changes project direction.

When ADRs Are Not Required

ADRs are not needed for small documentation edits, minor template changes, narrow bug fixes, or implementation details already covered by approved architecture docs.

Review Rule

An ADR should be introduced or updated through a focused documentation PR before or alongside the implementation PR that depends on it.