Architecture Decision Records (ADR) – jak dokumentować decyzje architektoniczne, które mają znaczenie

W każdym projekcie IT zapadają dziesiątki decyzji architektonicznych: o technologii, strukturze systemu, integracjach czy sposobie komunikacji. Problem w tym, że większość z nich żyje tylko w głowach ludzi albo w archiwalnych wątkach na Slacku.

Po kilku miesiącach (albo po zmianie zespołu) pojawia się klasyczne pytanie:

„Dlaczego my to właściwie zrobiliśmy w ten sposób?”

Na to pytanie odpowiadają Architecture Decision Records, czyli ADR-y.

Czym jest Architecture Decision Record?

ADR (Architecture Decision Record) to krótki dokument opisujący:

• kontekst decyzji,
• samą decyzję,
• jej konsekwencje.

ADR nie opisuje całej architektury systemu. Opisuje jedną konkretną, istotną decyzję architektoniczną.

Najważniejsze pytanie, na które odpowiada ADR, brzmi:

Dlaczego wybraliśmy to rozwiązanie, a nie inne?

Dlaczego warto stosować ADR-y?

1. Pamięć architektoniczna projektu

Kod pokazuje co zostało zrobione. ADR tłumaczy dlaczego.

Bez ADR-ów zespół traci kontekst decyzji, a kolejne zmiany są podejmowane „w ciemno”.

2. Lepszy onboarding

Nowa osoba w zespole:

• szybciej rozumie architekturę,
• wie, które decyzje są świadome, a które wynikają z kompromisów,
• nie próbuje „naprawiać” czegoś, co było celowym wyborem.

3. Świadome zmiany decyzji

ADR-y nie zamrażają architektury. Wręcz przeciwnie — ułatwiają jej zmianę.

Jeśli decyzja przestaje być aktualna:

• powstaje nowy ADR,
• stary otrzymuje status Deprecated lub Superseded,
• historia jest zachowana.

Co powinien zawierać ADR?

Najczęściej ADR mieści się na jednej stronie Markdowna i ma prostą strukturę.

Minimalny szablon ADR

# ADR-XXX: Tytuł decyzji

**Status:** Proposed | Accepted | Deprecated | Superseded  
**Data:** YYYY-MM-DD

## Kontekst
Opis problemu i ograniczeń.

## Decyzja
Opis podjętej decyzji.

## Konsekwencje
Pozytywne i negatywne skutki decyzji.

I to naprawdę wystarcza.

Przykład ADR – wybór bazy danych

ADR-001: Wybór bazy danych dla systemu zamówień

Status: Accepted
Data: 2026-02-05

Kontekst

System zamówień obsługuje dane transakcyjne (zamówienia, płatności, faktury). Wymagana jest spójność danych (ACID), relacyjny model oraz możliwość łatwego skalowania w chmurze.

Rozważane opcje:

• PostgreSQL
• MySQL
• MongoDB

Decyzja

Wybrano PostgreSQL jako główną bazę danych systemu.

Uzasadnienie

PostgreSQL został wybrany ze względu na pełne wsparcie dla właściwości ACID, co jest kluczowe dla systemu obsługującego zamówienia, płatności i faktury. Relacyjny model danych dobrze odpowiada strukturze domeny biznesowej oraz ułatwia egzekwowanie integralności danych (klucze obce, ograniczenia, transakcje).

Dodatkowo PostgreSQL oferuje:

• zaawansowane mechanizmy transakcyjne (MVCC),
• bogate wsparcie dla zapytań analitycznych,
• możliwość rozszerzania funkcjonalności (np. indeksy GIN/GiST, JSONB),
• bardzo dobrą integrację z dostawcami chmurowymi (AWS RDS, Azure Database, GCP Cloud SQL).

Te cechy czynią PostgreSQL rozwiązaniem bezpiecznym i przyszłościowym dla systemu o rosnącej skali.

Konsekwencje

Pozytywne

• pełne wsparcie transakcji,
• bogaty ekosystem,
• dobre wsparcie w chmurze.

Negatywne

• większe zużycie zasobów niż MySQL,
• konieczność monitorowania wydajności przy dużej skali.

Alternatywy

MySQL

MySQL był rozważany jako lżejsza alternatywa relacyjna, jednak:

• oferuje mniej zaawansowane mechanizmy transakcyjne i spójności danych niż PostgreSQL,
• ma ograniczenia w zakresie złożonych zapytań i rozszerzalności,
• w praktyce gorzej radzi sobie z bardziej skomplikowaną logiką domenową.

Z tego względu został odrzucony mimo niższego zużycia zasobów.

MongoDB

MongoDB zapewnia wysoką elastyczność schematu oraz łatwe skalowanie horyzontalne, jednak:

• nie jest bazą relacyjną, co utrudnia modelowanie silnie powiązanych danych,
• pełne wsparcie transakcji wielodokumentowych jest mniej dojrzałe i wiąże się z narzutem wydajnościowym,
• brak relacyjnych mechanizmów integralności danych zwiększa ryzyko niespójności w systemie finansowym.

Z tych powodów MongoDB nie spełnia kluczowych wymagań systemu zamówień.

Przykład ADR – monolit vs mikroserwisy

ADR-007: Architektura systemu – monolit na start

Status: Accepted
Data: 2024-06-03

Kontekst

Zespół liczy 4 osoby, produkt jest na wczesnym etapie rozwoju, a wymagania często się zmieniają. Czas dostarczenia funkcjonalności jest ważniejszy niż skalowanie horyzontalne.

Rozważane opcje:

• monolit modularny,
• architektura mikroserwisowa.

Decyzja

Na etapie MVP system będzie rozwijany jako monolit modularny.

Uzasadnienie

Monolit modularny pozwala zespołowi skupić się na szybkim dostarczaniu wartości biznesowej przy minimalnym narzucie architektonicznym. Przy niewielkim zespole i dynamicznie zmieniających się wymaganiach kluczowe są prostota rozwiązania, łatwość refaktoryzacji oraz krótki czas wdrożeń.

Zastosowanie wyraźnych granic modułów (np. na poziomie pakietów lub komponentów domenowych) umożliwia:

• zachowanie czytelnej struktury kodu,
• ograniczenie sprzężeń pomiędzy obszarami domeny,
• przygotowanie gruntu pod ewentualny przyszły podział na mikroserwisy.

Na tym etapie koszty operacyjne i złożoność architektury mikroserwisowej przewyższają potencjalne korzyści wynikające z niezależnego skalowania i wdrażania.

Konsekwencje

Pozytywne

• szybszy development,
• prostsze testy i wdrożenia,
• mniejszy narzut operacyjny.

Negatywne

• ograniczona niezależność skalowania modułów,
• konieczność refaktoryzacji przy przyszłym podziale na mikroserwisy.

Alternatywy

Architektura mikroserwisowa

Architektura mikroserwisowa została rozważona ze względu na:

• możliwość niezależnego skalowania komponentów,
• autonomię zespołów,
• elastyczność technologicznego rozwoju poszczególnych usług.

Jednak na etapie MVP została odrzucona, ponieważ:

• znacząco zwiększa złożoność systemu (komunikacja, obserwowalność, konfiguracja),
• generuje dodatkowy narzut operacyjny (CI/CD, monitoring, infrastruktura),
• spowalnia development w małym zespole,
• utrudnia szybkie zmiany w modelu domenowym.

Decyzja o mikroserwisach może zostać ponownie rozważona po osiągnięciu stabilnego produktu, większego zespołu lub wyraźnych problemów skalowalności monolitu.

Status ADR – dlaczego jest ważny?

Typowe statusy:

• Proposed – decyzja w trakcie rozważania,
• Accepted – decyzja obowiązująca,
• Deprecated – decyzja nieaktualna,
• Superseded – decyzja zastąpiona inną (z linkiem do nowego ADR).

Dzięki temu architektura ma swoją historię, a nie tylko aktualny stan.

Gdzie trzymać ADR-y?

Najlepsze miejsce to:

/docs/adr/
  ADR-001-database.md
  ADR-002-auth.md
  ADR-003-api-style.md

Dlaczego?

• są wersjonowane razem z kodem,
• zmiany decyzji są widoczne w historii Git,
• łatwo je przeglądać w PR-ach.

Częste błędy przy pisaniu ADR-ów

opisywanie oczywistych rzeczy
brak kontekstu („bo tak”)
zbyt długie dokumenty
brak negatywnych konsekwencji
brak aktualizacji statusu

Dobry ADR jest krótki, szczery i konkretny.

ADR jako narzędzie kultury technicznej

ADR-y to nie tylko dokumenty. To sygnał, że zespół:

• myśli o architekturze świadomie,
• potrafi uzasadniać decyzje,
• akceptuje kompromisy i ich konsekwencje.

Nie chodzi o perfekcyjne decyzje. Chodzi o dobre decyzje w danym kontekście.

Podsumowanie

Architecture Decision Records:

• porządkują myślenie architektoniczne,
• zapisują kontekst decyzji,
• ułatwiają rozwój i utrzymanie systemów,
• rosną razem z projektem.

Jeśli w projekcie regularnie pada pytanie „czemu tak?” — to znak, że czas na ADR-y.