ADR: architektonická paměť týmu

Skoro v každé firmě, do které přijdu na audit, narazím na stejnou scénu. Někdo nový se ptá: „Proč to je takhle?“ — a odpověď se po pár přeposláních na Slacku zastaví u věty „to dělal Tomáš, ten odešel předloni“. Kód je pořád tady. Rozhodnutí, které ho takhle vytvarovalo, odešlo s Tomášem.

01Rozhodnutí, na které se nikdo nepamatuje

Ta scéna se vždycky odehrává kolem něčeho konkrétního. Fronta tam, kde by stačilo přímé volání. Sloupec zduplikovaný proti všem pravidlům databáze. Služba, kterou by „přece bylo logické“ sloučit s jinou. Nový člověk to vidí jako chybu — a tady se tým rozdělí na dvě stejně špatné reakce.

Buď se to omezení stane posvátným: tým ho donekonečna obchází, protože „nějaký důvod to nejspíš má“, i když ten důvod nikdo nezná. Nebo se to „opraví“ — a původní důvod si tým připomene tím nejdražším způsobem: v produkci, zpravidla pod zátěží.

Příčina je jednoduchá. Kód ukazuje, co systém dělá. git blame ukáže, kdo a kdy. Ani jedno neukáže proč — jaký byl tehdy kontext, které alternativy se zamítly, jaký kompromis se vědomě přijal. A právě „proč“ se rozpadá nejrychleji, protože žije jen v hlavách lidí — a lidé odcházejí.

02Co je ADR

ADR — Architecture Decision Record, architektonický záznam rozhodnutí. Pojem rozšířil Michael Nygard v roce 2011 v článku Documenting Architecture Decisions. Je to záměrně malá věc: krátký dokument, typicky na jednu stránku, který zaznamenává jedno architektonicky významné rozhodnutí a úvahu za ním.

Nygardova šablona má čtyři části: Status (navržené, přijaté, nahrazené), Kontext (situace, která rozhodnutí vynutila), Rozhodnutí (co jsme zvolili) a Důsledky (co to přináší — to dobré i to špatné). Nic víc.

Jedna vlastnost odlišuje ADR od běžné dokumentace: rozhodnutí ani úvaha za ním se zpětně nepřepisují. Překlepy, doplněné odkazy nebo upřesnění poznámkou pod čarou jsou v pořádku; změna toho, co se tehdy rozhodlo nebo proč, ne. Když se realita změní, napíšete nový ADR, který ten starý nahrazuje, a starý označíte jako nahrazený. Vznikne tak append-only log: chronologický záznam toho, jak se uvažování týmu o architektuře vyvíjelo. Žije v repozitáři, pod verzí, vedle kódu — obvykle ve složce docs/adr/.

03Proč zrovna tak krátké a v repozitáři

Nabízí se námitka: na tohle přece máme architektonickou dokumentaci. Máme — a v tom je právě ten problém. Velký, samostatný dokument o architektuře hnije. Žije na wiki, kterou nikdo neotevírá, během pár týdnů se rozejde s kódem a po roce už aktivně mate — popisuje systém, který neexistuje.

ADR se tomu vyhne třemi omezeními. Je krátký — jedno rozhodnutí, jedna stránka; napsat ho je levné, takže opravdu vznikne. Je append-only — nikdy ho nemusíte „udržovat aktuální“, o změnu se postará nahrazení. Je v repozitáři — cestuje s kódem, recenzuje se ve stejném pull requestu a git log nad složkou ADR je doslova changelog architektury.

Thoughtworks zařadili odlehčené ADR do prstence „Adopt“ svého Technology Radaru — to je nejsilnější doporučení, které dávají — a výslovně radí držet je ve verzovacím systému, ne na wiki, právě aby zůstaly v synchronizaci s kódem. ADR nezařídí, že se rozhodnete správně; architektura je podle Ralpha Johnsona „rozhodnutí, u kterých si přejete, abyste je trefili brzy“. ADR ale zařídí, že rozhodnutí i jeho důvod budou později čitelné.

04Co je rozhodnutí hodné ADR

ADR si nezaslouží každé rozhodnutí. Když ho napíšete na všechno, log se zahltí a nikdo ho nečte. Filtr jsou tři otázky — ADR napište tehdy, když je rozhodnutí aspoň jedním z tohoto:

jeho zvrácení je drahé nebo rizikové,
omezuje budoucí práci,
je to věc, na kterou se někdo později podívá a zeptá se „proč to takhle je?“.

ADR si zaslouží volba databáze nebo způsobu perzistence; umístění hranice mezi moduly nebo službami; synchronní volání versus fronta a událost; model autentizace a oprávnění; přijetí — nebo vědomé zakázání — frameworku či větší knihovny. A hlavně vědomé rozhodnutí něco neudělat („zatím to nerozdělíme na služby, protože…“).

ADR si naopak nezaslouží pojmenování proměnných, formátování, výběr ze dvou téměř rovnocenných knihoven ani cokoli, co jde za odpoledne vzít zpět. Heuristika: pokud zvrátit rozhodnutí později znamená migraci nebo koordinovaný zásah napříč týmy, patří do ADR.

05Co do ADR patří — a hlavně co ne

Vraťme se ke čtyřem částem — záleží totiž na tom, jak se vyplní. Kontext jsou síly té chvíle: zátěž, velikost týmu, termín, co jste věděli a co jste jen tipovali. Pište ho v minulém čase, je to snímek okamžiku, ne věčná pravda. Rozhodnutí je to, co jste zvolili, v činném rodě — „Rozhodli jsme se…“. Jedno na záznam. Důsledky popište poctivě: co se zjednoduší a co zkomplikuje. ADR, ve kterém jsou samá pozitiva, není záznam, ale leták.

Nejcennější — a nejčastěji vynechaná — část v Nygardových čtyřech nadpisech vůbec není: zvažované alternativy a důvod, proč se zamítly, spolu s tím, co jste vědomě odložili. Na tom celá hodnota ADR stojí. Tým, který formát adoptuje, ale píše záznamy typu „zvolili jsme Postgres, protože je dobrý“, si vytvoří jen iluzi paměti — log existuje, ale je k ničemu. „Zvažovali jsme frontu a zamítli ji, protože tým neměl provozní kapacitu ji ustát“ naopak řekne budoucímu čtenáři všechno. Pokud z ADR ubíráte, ubírejte odjinud — tuhle část ne.

A co do ADR nepatří: implementační detail (to je práce kódu), návod krok za krokem a přesvědčování. ADR je záznam, ne obhajoba. Pokud čtenáře přemlouváte, píšete špatný dokument.

// Praktický pohled

Na auditu je rozdíl mezi týmem s ADR a bez nich znát hned — a není to množstvím dokumentace. Bez nich každá otázka „proč to takhle je?“ skončí u člověka, který už ve firmě není. S tenkým logem patnácti dvaceti ADR dokážu záměr architektury zrekonstruovat za odpoledne. A nejvíc se vyplatily ty záznamy, které říkaly „tohle jsme schválně neudělali, a tady je proč“ — protože přesně ta rozhodnutí vypadají pro nového člověka jako chyba.

06ADR a technický dluh

Nezdokumentované rozhodnutí je prvotřídní kandidát na to stát se neviditelným dluhem. Funguje to dvěma způsoby.

První: nový vývojář vidí omezení, které vypadá náhodně — workaround, podivnou hranici — vyhodnotí ho jako chybu a „opraví“ ho. To omezení přitom něco neslo; jen to nikdo neoznačil. Oprava vrátí do hry přesně tu chybu, které omezení bránilo.

Druhý: zkratka přijatá plně vědomě („pro launch to natvrdo zadrátujeme, spravíme v Q2“) se stává nevědomým dluhem ve chvíli, kdy ji její autor zapomene — a autoři zapomínají během měsíců. ADR drží vědomou zkratku vědomou: mění neviditelné rozhodnutí na viditelnou, recenzovatelnou položku, která se dá dát do backlogu. Je to stejná čára, jakou vede článek Technický dluh není bordel v kódu — ten nebezpečný dluh není ošklivý kód, ale rozhodnutí, které si nikdo nezapsal.

07Jak ADR zavést bez procesního balastu

ADR se snadno promění v byrokracii a byrokratický ADR do měsíce umře. Pár pravidel ho udrží odlehčený.

Začněte teď, ne zpětně

Nedoplňujte padesát ADR ke starým rozhodnutím. Nikdy to nedokončíte a rekonstruovaná úvaha by stejně byla dohad — přesně to, čemu má ADR bránit. Začněte u nejbližšího významného rozhodnutí.

Držte je v repozitáři a postarejte se, aby se daly najít

Složka docs/adr/, číslované soubory (0001-volba-databaze.md), append-only. Číslo je pořadí; nikdy se nepřečíslovává. U dvaceti záznamů stačí složka; u sto padesáti už ne. Vyplatí se index s krátkými popisky, štítky podle oblasti (data, autentizace, hranice modulů) a hlavně odkazy z kódu zpátky — komentář // viz ADR-0017 u podivně vypadající části udělá pro objevitelnost víc než celá wiki.

Šablona musí být malá

Nygardova, nebo MADR. Pokud psaní jednoho ADR trvá víc než zhruba dvacet minut, je šablona moc těžká — zkraťte ji. Jde o proč jednoho rozhodnutí, ne o úplnost.

Pište ADR, když rozhodnutí padá

Ve stejném pull requestu, který ho implementuje. Recenzujte ADR jako kód — úvaha dostane druhý pár očí, dokud ji mají všichni čerstvě v hlavě. ADR psaný o tři měsíce později je rekonstrukce, ne záznam.

Jedna výjimka stojí za zmínku: některá rozhodnutí vypadají v okamžiku, kdy padají, jako triviální výběr ze dvou rovnocenných knihoven a teprve za půl roku se ukáže, že se kolem nich nabalila polovina kódu. Pokud k tomu dojde, napište ADR teď — ne zpětnou rekonstrukci, ale upřímný záznam toho, že se rozhodnutí ukázalo jako významné dodatečně a co se mezitím změnilo.

ADR není schvalovací brána ani povinné gesto

Je to log, ne schvalovací proces. Ve chvíli, kdy potřebuje podpis tří lidí, umírá. Stejně tak umírá ve chvíli, kdy se ADR začne psát proto, že „to k PR patří“ — výsledkem jsou prázdné záznamy, které matou víc, než kdyby nebyly. Pravidlo je opačné: pokud k rozhodnutí nemáte co napsat do sekce alternativ a důsledků, ADR nepište. Když se rozhodnutí změní, starý ADR neupravujete — napíšete nový, odkážete zpět a starý označíte jako nahrazený.

08Závěr: levná pojistka proti dražší ztrátě

ADR není dokumentace v tom byrokratickém smyslu. Je to architektonická paměť týmu — to „proč“, které jinak odchází s lidmi. Stojí zhruba dvacet minut tehdy, když už víte, co jste rozhodli a proč. U rozhodnutí, kde je ADR opravdu cenný, ovšem to „proč“ obvykle vzniká až psaním a celá deliberace bere déle — pořád je to ale zlomek ceny pozdějšího znovuobjevení — obvykle v produkci a obvykle člověkem, který netušil, že to omezení něco neslo.

A vyplatí se nejvíc právě ve chvíli, kdy refaktorujete. Budoucí refaktoring je levný, když umíte rozlišit, která omezení jsou záměrná a nosná a která jsou jen náhoda, o které nikdo nerozhodl. Bez toho záznamu začíná každý refaktoring archeologií — a cena každé změny s ní roste.

ADR nezaručí, že se rozhodnete správně. Zaručí, že za rok bude jasné proč — i když člověk, který ho psal, je dávno jinde.

ADR: architektonická paměť týmu, která šetří budoucí refaktoring