ADR Template

Copy the block below. Fill each section. Readable in under 2 minutes.

---
title: ADR-NNN[-subletter] — [Title]
adr: NNN              # number only (e.g. 12) — lets Bases sort numerically
sub: ""               # sub-letter (a/b/c) for a sub-decision; empty for a parent ADR
parent: ""            # "[[adr-NNN-slug]]" when this is a sub-decision; empty otherwise
status: Draft         # Draft | Accepted | Superseded | Deprecated
domain: []            # governance | backend | frontend | design-system | infra | process | business-rules
tags: [adr]
paths: []             # rule scoping (globs). Empty/omitted ⇒ loads every session.
                      # e.g. ["frontend/**"]  or  ["backend/**", "API.md"]
---
# ADR-NNN[-subletter] — [Title]

## Status

Draft

## Context

State the problem. List alternatives considered and why each was rejected.

## Decision

Each decision is a **bold-header paragraph** — not a numbered list, not a subsection.

**First decision.** Explain what is decided and why this option wins.

**Second decision.** Same pattern. One paragraph per decision point. Tables, code blocks, and bullet lists are allowed as supporting detail under a bold-header paragraph — but a table alone is not a decision.

## Consequences

What changes. Trade-offs. Impact on other ADRs.

If this ADR has sub-letters (a, b, c), add a ## Sub-decisions section between Decision and Consequences listing each child with a one-line description. Do not include it otherwise.

Frontmatter

Metadata above the H1 — read by Obsidian Bases (table/card views) and by Claude Code rules (the .claude/rules/ symlinks point back to these files). Keep every key present (leave it empty rather than dropping it) so Bases can filter without holes.

title — full ADR heading; mirrors the H1.
adr / sub / parent — identity. adr is the bare number (numeric sort); sub + parent tie a sub-decision to its umbrella ADR (parent as a [[wikilink]]).
status — lifecycle; mirrors the ## Status section, which stays canonical per ADR-001.
domain — one or more areas; drives Base grouping and guides paths.
tags — keep adr; add freely.
paths — Claude Code rule scoping. With globs, the ADR loads as a rule only when a matching file is touched; empty/omitted ⇒ it loads every session (reserve that for project-wide governance ADRs).

Pure Nygard format (ADR-001): Status, Context, Decision, Consequences — in that order, no other sections (frontmatter is metadata, not a section). Sub-decisions is the only permitted addition, and only when sub-letters exist.

Accepted ADRs are immutable. To change a decision, write a new ADR and mark the old one Superseded by ADR-NNN.

File naming: adr-NNN[-subletter]-slug-in-kebab-case.md. Add to docs/adr/README.md at creation time.