ADR dla zespołów inżynierskich

Decyzje potrzebują pamięci

Każdy system, przy którym pracowałem, nosił w sobie decyzje, których nikt nie umiał już wyjaśnić. Dlaczego ta usługa jest właścicielem tamtej tabeli? Dlaczego uwierzytelnianie jest rozbite na dwa komponenty? Dlaczego odrzuciliśmy kolejkę, którą teraz wszyscy chcą wprowadzić? Ludzie, którzy to wiedzieli, odeszli, notatki ze spotkań przepadły, a wątek na czacie zasypały dwa lata szumu.

Architektura robi się droga dokładnie w tym momencie. Nie wtedy, gdy decyzja zapada — wtedy, gdy znika jej kontekst. Zespół bez pamięci decyzji co kilka kwartałów prowadzi od nowa te same debaty albo — gorzej — po cichu odwraca stare wybory, nie wiedząc, jakie ograniczenie zaraz naruszy.

Dobry zapis nie zastępuje osądu. Zachowuje tyle kontekstu, żeby przyszły osąd był tańszy.

Architecture Decision Record to najtańsze znane mi narzędzie na ten problem. Krótki dokument — strona, często mniej — który opisuje jedną decyzję: co wybraliśmy, dlaczego, co odrzuciliśmy i jaki koszt świadomie zaakceptowaliśmy. Pomysł pochodzi z eseju Michaela Nygarda z 2011 roku i przetrwał właśnie dlatego, że jest na tyle mały, iż da się go realnie utrzymać.

Co się psuje bez zapisów

Tryby awarii są przewidywalne — każdy z nich widziałem w działających organizacjach:

• Archeologia decyzji. Senior spędza dwa dni na rekonstruowaniu, dlaczego dana granica istnieje, zanim odważy się ją zmienić. Pomnóż to przez każdą istotną zmianę i masz realny podatek od dostarczania.
• Ciche odwrócenie. Nowa osoba w zespole „naprawia" coś, co było świadomym kompromisem. Pierwotne ograniczenie — wymóg compliance, charakterystyka obciążenia, limit vendora — wraca jako incydent.
• Amnezja spotkań. Ta sama debata architektoniczna odbywa się trzy razy z trzema różnymi wynikami, bo nic nie wiąże poprzedniej konkluzji z kodem.
• Onboarding przez folklor. Nowi inżynierowie poznają architekturę od tego, kto akurat odpisze na czacie — czyli poznają wersję częściową, a czasem błędną.

Żaden z tych problemów nie jest klasycznym problemem dokumentacji. Wiki pełne nieaktualnych diagramów ich nie rozwiązuje. To problemy decyzji — i dokładnie taki, wąski zakres powinien mieć ADR.

Praktyczny format

Trzymam ADR-y celowo małe: kontekst, decyzja, konsekwencje, rozważone alternatywy i linki do dowodów. Celem nie jest ceremonia, tylko przeszukiwalna pamięć zespołu, która przetrwa rotację ludzi.

Status: zaakceptowane
Data: 2026-04-14
Kontekst: usługi wymagają autoryzacji per tenant; wyciek danych między
          tenantami to najwyższe ryzyko w tej domenie
Decyzja: kontrole tenanta w serwisach aplikacyjnych ORAZ jako filtry
         na poziomie bazy (defense in depth)
Alternatywy: kontrola tylko w middleware (odrzucone: pojedynczy punkt awarii),
             samo RLS w bazie (odrzucone: niewidoczne w code review)
Konsekwencje: prostsza ścieżka review, jawne testy,
              mniejsze ryzyko wycieku, niewielki narzut na zapytanie

Kilka zasad, które utrzymują ten format w ryzach:

• Jedna decyzja na zapis. Jeśli w tytule potrzebujesz „i", prawdopodobnie potrzebujesz dwóch zapisów.
• Zapis zaakceptowany jest niezmienny. Nowa wiedza tworzy nowy ADR, który zastępuje stary — historia zostaje nietknięta.
• Alternatywy dostają uczciwe potraktowanie. „Nie rozważaliśmy niczego innego" to sygnał ostrzegawczy, nie zapis.
• Konsekwencje obejmują też te negatywne. Zapis wymieniający same korzyści to marketing, nie pamięć.

Jak pisać ADR-y, które ktoś przeczyta

Typowe podejście to pisanie ADR-ów jak formalnych specyfikacji: długo, defensywnie i „kompletnie". Z mojego doświadczenia to gwarancja, że nikt ich nie przeczyta. To, co robię naprawdę, to pisanie ich jak wiadomości do konkretnej osoby — inżyniera, który za półtora roku będzie patrzył na tę granicę i zastanawiał się, czy można ją bezpiecznie ruszyć.

Takie ujęcie zmienia sposób pisania. Przestajesz dokumentować wszystko i zaczynasz odpowiadać na trzy pytania: jakie ograniczenie wymusiło tę decyzję, co się zepsuje przy jej odwróceniu i jakie mieliśmy wtedy dowody. Jeśli przyszły czytelnik szybko odpowie sobie „czy to nadal prawda?", zapis wykonał swoją robotę.

Długość znaczy mniej niż gęstość. Jedne z najbardziej użytecznych zapisów, jakie napisałem, mają sześć zdań. Najgorsze miały trzy strony asekuracji i nie przesądzały niczego.

Rytm przeglądu, który przeżyje dostarczanie

Zapis ma sens tylko wtedy, gdy jest do niego przypięty rytm. Najczęstszy błąd, jaki widzę: zespół pisze ADR-y podczas akcji „dokumentujemy wszystko", a potem nigdy do nich nie wraca. Zapisy bez wyzwalaczy gniją dokładnie tak samo jak kod bez testów.

Rytm wiążę ze zdarzeniami dostarczania, nie z kalendarzem. Przeglądy kalendarzowe wypadają pod presją; przeglądy zdarzeniowe dzieją się same, bo zdarzenie i tak wymusza pytanie.

Link w pull requeście to nawyk o największej dźwigni z całej tabeli. Kosztuje sekundy, a zamienia ADR z dokumentu w żywy punkt odniesienia, na który reviewerzy natykają się w normalnej pracy.

Narzędzia i miejsce w repozytorium

ADR-y należą do repozytorium, obok kodu, który opisują — docs/adr/ albo docs/decisions/, czysty Markdown, numeracja po kolei. Powody są praktyczne:

• Podróżują z kodem przez forki, migracje i zmiany vendorów. Wiki nie.
• Da się je przeszukiwać narzędziami, których inżynierowie i tak używają — grep, wyszukiwarka IDE, interfejs code review.
• Można je reviewować jak kod. Pull request z ADR-em to design review z pisemnym artefaktem na końcu.
• Historia gita daje autorstwo i datowanie za darmo.

Narzędzia ponad to są opcjonalne. adr-tools i podobne CLI są przyjemne, ale nigdy nie widziałem, żeby praktyka ADR upadła z braku narzędzi — widziałem za to kilka, które upadły, bo ciężki szablon zamienił pisanie w wypełnianie PIT-u. Zacznij od pliku Markdown i konwencji nazewnictwa; narzędzia dołóż, gdy wolumen to uzasadni.

Antywzorce, które zabijają praktykę

Większość inicjatyw ADR nie upada głośno. Gaśnie. Na te wzorce aktywnie uważam:

• Archiwum wstecz. Ktoś w heroicznym sprincie dokumentuje czterdzieści historycznych decyzji. Archiwum robi wrażenie i natychmiast się starzeje, a zespół uczy się, że ADR to projekt, nie nawyk.
• Bramka akceptacyjna. ADR staje się obowiązkowym krokiem z wymaganymi recenzentami i SLA. Pisanie zaczyna smakować biurokracją, więc inżynierowie tak tną zakres pracy, żeby bramki nie uruchomić.
• Konkurs esejów. Zapisy puchną ponad stronę, bo drobiazgowość mylona jest z jakością. Czytanie staje się pracą; nikt jej nie wykonuje.
• Prywatny notes. Jeden architekt pisze świetne zapisy, do których nikt inny nie dokłada. Gdy odchodzi, praktyka odchodzi z nim.

Uwagi z produkcji

Kilka rzeczy, które ujawniają się dopiero po dłuższym czasie działania praktyki:

• Łańcuchy zastąpień wymagają higieny. Po roku będziesz mieć zapisy zastępujące zapisy. Utrzymuj linki w obie strony — stary zapis wskazuje nowy, nowy stary — inaczej nawigacja szybko się sypie.
• Decyzje między repozytoriami potrzebują domu. Decyzje obejmujące wiele usług (model uwierzytelniania, konwencje schematów zdarzeń) trzymaj w repozytorium platformowym i linkuj z usług. Duplikowanie gwarantuje rozjazd.
• Incydenty to Twój zestaw walidacyjny. Najuczciwsze pytanie każdego post-mortem brzmi: „które zapisane założenie okazało się fałszywe?". Jeśli odpowiedź brzmi „żadne" — albo system jest wyjątkowo stabilny, albo zapisy są zbyt mgliste, by dały się sfalsyfikować.
• Nowe osoby to Twój test użyteczności. Poproś inżynierów w pierwszym miesiącu o przeczytanie indeksu ADR i oznaczenie tego, czego nie dało się zrozumieć. Ich konsternacja mapuje się dokładnie na brakujący kontekst.

Podsumowanie

• ADR rozwiązuje problem pamięci decyzji, nie problem dokumentacji — trzymaj tak wąski zakres.
• Jedna strona, jedna decyzja, uczciwe alternatywy, konsekwencje razem z negatywnymi.
• Pisz dla inżyniera, który za półtora roku zakwestionuje tę granicę.
• Przeglądy wiąż ze zdarzeniami dostarczania — nowe granice, PR-y, incydenty, migracje — nigdy z samym kalendarzem.
• Zapisy trzymaj w repo jako Markdown; narzędzia dokładaj dopiero przy większym wolumenie.
• Uważaj na ceremonię: bramki akceptacyjne i zapisy-eseje zabijają praktykę po cichu.