TL;DR: ADR (Architecture Decision Record) je deník architektonických rozhodnutí. Za rok totiž bez něj nevíte, proč jste zvolili to a né tamto. Ukázka šablony z reálného projektu.
Co to je ADR?
Uvedu situaci. Přijde nový kolega na projekt. Podívá se na kód, něco mu tam nesedí a zeptá se: „Proč v tomhle projektu používáte RabbitMQ? Proč ne Kafku?“ No, a nikdo neví. Původní autor třeba odešel, nebo si to nepamatuje.
Nedávno se mi to stalo na mým projektu Webová Hlídka. Tedy nebyl to kolega, byl jsem to já sám po cca roční přestávce od projektu. Seděl jsem nad svým kódem a nevěděl, proč jsem se tak rozhodl (smutné, ale je to tak).
Dobré řešení na tyhle situace je právě ADR – Architecture Decision Record. Krátký markdown, který dokumentuje dané architektonické rozhodnutí: kontext, volbu, alternativy, dopady. Až se za rok podíváte na kód, už nebude zapotřebí hádat. Prostě se podíváte na dokument a zjistíte, proč to v daný okamžik dávalo smysl.
ADR je takový vzkaz kolegovi (nebo sobě). Není nutné to vést jako formální dokumentaci pro šéfa, stačí to většinou prostě jen nějak napsat, aby to dávalo smysl.
Šablona s pěti sekcemi
Co jsem zkoumal, tak tohle řešení mi nakonec po delší době dává smysl, proto se o něj zde dělím dál.
Context / Kontext
Proč toto rozhodnutí vůbec řešíme? Je to kvůli technickému omezení, business situace nebo předchozímu rozhodnutí?
Tahle sekce popisuje stav před daným rozhodnutím.
Decision / Rozhodnutí
Co jste se rozhodli udělat? Stačí jedna věta: „Zvolil jsem …, protože …“
Narazil jsem na takovou zajímavou poučku: Pokud rozhodnutí nedokážete napsat do jedné věty, možná jste se ještě nerozhodli.
Considered Options / Zvažované možnosti
Co jste zvažovali a proč jste to zamítli? Každá alternativa si zaslouží aspoň větu „Zvažoval jsem …, ale bylo to špatné/nevyhovující, protože….“
Tohle je strašně důležitá část, protože výsledek dlouhého zkoumání, proč jste alternativu zamítli do budoucna ušetří to samé zkoumání znova. Minimálně to připomene argumenty, které v daném okamžiku mohly dávat smysl.
Consequences / Důsledky
Klady i zápory daného rozhodnutí. Je dobré přiznat, co rozhodnutí komplikuje nebo zpomaluje. Vždy je to o nějakém kompromisu a je dobré si to poznamenat, abyste na základě toho mohli zvážit dané rozhodnutí třeba za rok.
Assumptions / Předpoklady
Za jakých předpokladů dané rozhodnutí platí? Je to určitý provoz na serveru? Počet uživatelů? Velikost týmu? Rozpočet? Je to pojistka k tomu, že se některá rozhodnutí mohou v budoucnu přehodnotit.
Kdy se k rozhodnutí vrátit? Pokud víte, že dané rozhodnutí je dobré v daný okamžik, ale jakmile nastane něco, co situaci změní, tak zde je dobré místo to napsat.
Je dobré být co nejvíc konkrétní: „Když cena za provoz přesáhne … Kč měsíčně“ nebo „Dokud provoz nepřekročí 1 000 requestů za minutu“ je fakt lepší než „nízký provoz“.
Reálné ADR z Webové Hlídky
# ADR-0003: Volba message brokeru pro asynchronní zpracování kontrol
**Datum:** 2026-03-12
**Status:** Accepted
## Context
Webová Hlídka původně zpracovávala kontroly webů synchronně v rámci HTTP requestu.
Při růstu na 200+ monitorovaných webů začaly requesty timeoutovat a fronta se ucpávala.
Potřebuju asynchronní zpracování, kde kontroly probíhají nezávisle na HTTP vrstvě.
Tým tvoří jeden vývojář (já), provoz na self managed VPS s 4 GB RAM.
## Decision
Zvolil jsem RabbitMQ jako message broker pro distribuci úloh kontroly webů.
## Considered Options
**Amazon SQS** byl první kandidát - managed služba, žádná správa, dobré SLA.
Zamítl jsem ho kvůli vendor locku na AWS a přidané složitosti infrastruktury
pro projekt, který zatím běží na jednom VPS. Cena nebyla problém, ale provozní
závislost na cloud provideru ano.
**Redis Streams** jsou dobrou volbou pro jednoduché queuing, jenže Redis
v projektu už používám jako cache. Míchat dvě zodpovědnosti do jedné instance
(cache + message broker) se mi nechtělo - failure jedné věci by ovlivnil druhou.
Oddělená Redis instance jen pro Streams přidává provozní složitost bez benefitu.
**Kafku** jsem zamítl rychle. Kafka řeší problémy, které zatím nemám:
retenci zpráv pro více consumerů, high throughput v řádu milionů zpráv za sekundu.
Pro 200 webů kontrolovaných každých 5 minut je Kafka přestřelená jak operačně,
tak koncepčně.
## Consequences
Kladné: RabbitMQ dobře zvládá task queuing se zaručeným doručením (ACK/NACK),
podporuje prioritní fronty pro urgentní kontroly, a PHP klient (php-amqplib) je stabilní.
Provoz v Dockeru je přímočarý, monitoring přes management plugin srozumitelný.
Záporné: Přidávám další službu do infrastruktury – RabbitMQ instance vyžaduje
správu, monitoring a zálohy. Při výpadku brokeru se zastaví všechny kontroly.
Tým (zatím jen já) musí znát RabbitMQ koncepty: exchanges, queues, bindings.
## Assumptions
Předpokládám, že počet monitorovaných webů nepřekročí 2 000 v příštích 12 měsících.
Předpokládám jednovláknového konzumenta – škálování na více workerů neřeším.
Předpokládám, že projekt zůstane na self-hosted infrastruktuře bez přechodu na AWS.
Přehodnotit, pokud: počet webů překročí 2 000 a latence kontrol roste,
pokud se tým rozroste a RabbitMQ operace brzdí onboarding,
nebo pokud se projekt přesune na AWS (pak dává SQS větší smysl).
Nenapsal jsem takhle každé rozhodnutí v projektu, to určitě ne. Ne každé rozhodnutí si ADR zaslouží. Smysl má tam, kde je rozhodnutí těžké zvrátit nebo kde alternativy nebyly triviální. Ale záleží zase na konkrétním projektu. U důležitých a velkých projektů bych se toho nebál psát co nejvíce.
Kam s ADR soubory?
Určitě do repozitáře, třeba do složky /docs/adr s číslem v názvu: 0001-volba-databaze.md, 0002-autentizace.md, 0003-volba-message-brokeru.md
Proč v repozitáři? Protože se to verzuje spolu s kódem, který s tím následně souvisí.
Proč ADR v době AI dává ještě větší smysl?
AI agenty (Claude Code) používám každý den. A čím déle s nimi pracuju, tím víc oceňuju, že mám v projektech ADR soubory.
Jednak píšu ADR mnohem rychleji, protože si je nechám vygenerovat první nástřel z výzkumu a poznámek k němu.
Druhak to pomáhá s kontextem pro AI. Lépe chápe to, proč se co jak používá a nemá tendenci to měnit a uhýbat jiným směrem.
AI prompt na první draft ADR
Jak jsem psal o pář řádků výše, první draft si nechávám generovat AIčkem. Zde je promp, který k tomu používám. Samozřejmě je potřeba za něj doplnit kontext, třeba markdown soubor s výzkumem, poznámky, emaily, zprávy atd. Samotné doladění už bývá rychlé. Status (ve chvíli, když ADR píšu) dávám automaticky Accepted, ale v budoucnu dané rozhodnutí může změnit jiné ADR: Superseded by ADR-XXX.
Jsi zkušený software architekt. Pomoz mi sepsat ADR (Architecture Decision Record)
podle této přesné šablony:
---
# ADR-NNN: [Krátký název rozhodnutí]
**Datum:** YYYY-MM-DD
**Status:** Accepted
## Context
Svět *před* rozhodnutím. Technická omezení, business situace, předchozí
rozhodnutí. Tak, aby tomu rozuměl i člověk, který projekt nezná.
## Decision
Jedna věta, aktivní hlas: „Zvolil jsem X" nebo „Zvolili jsme X". Bez pasiva.
## Considered Options
Pro každou alternativu: jméno, krátký popis, **proč** byla zamítnuta.
Konkrétně, ne „bylo to špatné". Co jí chybělo, co bylo lepší u zvolené varianty.
## Consequences
Kladné i záporné dopady, oboje. Žádný dokument bez záporů – pokud nemáš
trade-off, ještě jsi nepřemýšlel dost.
## Assumptions
Za jakých konkrétních předpokladů rozhodnutí platí. Konkrétní čísla,
ne „nízký provoz".
Konkrétní podmínka, kdy se k rozhodnutí vrátit. Ne „až to bude potřeba",
ale „Když překročíme X requestů" nebo „Když cena přesáhne Y Kč měsíčně".
INSTRUKCE:
- Když ti něco důležitého chybí (např. neznáš zvažované alternativy), zeptej se,
nedoplňuj hypoteticky.
- ADR cílí na 300–500 slov celkem.
- Jazyk: čeština, věcný tón, žádné marketingové fráze.
- Output: Markdown, přesně podle šablony výš. Žádné shrnutí na konci.
INPUT:
(sem vložit všechny podklady pro rozhodnutí - výzkum, poznámky, emaily, zprávy)
Zdroje
ADR jako koncept popsal v roce 2011 Michael Nygard v článku „Documenting Architecture Decisions“. Odtud beru první tři sekce (Context, Decision, Consequences).
cognitect.com/blog/2011/11/15/documenting-architecture-decisions
Druhý zdroj je sbírka šablon a příkladů:
github.com/architecture-decision-record/architecture-decision-record
Sekce Considered Options je v MADR (adr.github.io/madr/) a Assumptions mi jednou navrhla AI a mě to tam dává smysl.