Přeskočit obsah

Architecture Decision Records (ADRs)

Append-only záznamy klíčových architektonických rozhodnutí. Jeden soubor = jedno rozhodnutí.

Pojmenování

YYYY-MM-DD-<kebab-slug>.md. Datum je den, kdy rozhodnutí bylo přijato (ne kdy se zapsalo).

Struktura ADR

# <Rozhodnutí v 1 větě>

**Date**: YYYY-MM-DD
**Status**: Proposed | Accepted | Superseded by `YYYY-MM-DD-xxx.md`

## Context
Co nás přinutilo rozhodovat. 2-4 věty.

## Decision
Co jsme zvolili. 1-2 věty. Bez detailních implementačních kroků.

## Alternatives considered
Co jsme zamítli a proč.

## Consequences
Co se tím usnadnilo, co zkomplikovalo, jakou dluh přijímáme.

## Revisit when
Konkrétní spouštěč pro revizi rozhodnutí (např. „Když Supabase přidá X" nebo „Při příchodu reálných dat").

Pravidla

  • Append-only. Když rozhodnutí ztratí platnost, vytvoř nové ADR se Status: Accepted a v něm Supersedes: <starý>; starý ADR dostane Status: Superseded by <nový>.
  • Žádné editace obsahu, jen status změna. Historie je hodnota.
  • Granularita: jedno rozhodnutí = jedno ADR. „Stack volba" je moc široké, „Použijeme Supabase místo Firebase" je správné.
  • Nepiš ADR pro každý PR — píšeš ho pro rozhodnutí, ke kterému by se mohl příští tým chtít vrátit.

Kontext

ADRs jsou jedna ze tří vrstev I³ metodologie: - Intent (docs/intent/) — co a proč feature dělá. - Invariants (docs/invariants.md) — pravidla, která nesmí padnout. - Decisions (ADRs) — proč X, ne Y. Tady.

ADR vzniká typicky při /architect-review — výstup architect agenta. Občas i mimo (PO se rozhodne, retro identifikuje).