Rekord Decyzji Architektonicznych (ADR)

Co robi ten skill

Prowadzi użytkownika przez podejmowanie decyzji architektonicznej i tworzy trwały zapis. ADR odpowiada na pytanie, które zawsze pojawia się 6 miesięcy później: „Dlaczego tak to zrobiliśmy?"

To nie jest dokumentacja dla samej dokumentacji. To mechanizm wymuszający decyzję, który:

1. Zmusza do wyartykułowania rzeczywistego problemu (nie objawu)
2. Mapuje ograniczenia przed przeskoczeniem do rozwiązań
3. Ocenia opcje wobec jawnych kryteriów
4. Zapisuje decyzję z pełnym uzasadnieniem
5. Wymienia konsekwencje, żeby przyszły-ty wiedział, jakie kompromisy zaakceptowano

Kiedy używać

• Wybór między stackami technologicznymi, frameworkami lub bazami danych
• Definiowanie kontraktów API, modeli danych lub granic serwisów
• Podejmowanie decyzji o strategiach wdrożenia, wzorcach CI/CD lub infrastrukturze
• Rozstrzyganie między konkurencyjnymi podejściami architektonicznymi w zespole
• Każda decyzja, która byłaby kosztowna do cofnięcia

Szablon ADR

1. Tytuł

ADR-{numer}: {Krótki tytuł decyzji}

2. Status

Proponowany | Zaakceptowany | Wycofany | Zastąpiony przez ADR-{n}

3. Kontekst

Jaki jest problem? Dlaczego ta decyzja musi zostać podjęta teraz? Jakie siły są w grze?

Zasady:

• Podawaj fakty, nie opinie
• Uwzględnij ograniczenia techniczne (wydajność, skala, kompatybilność)
• Uwzględnij ograniczenia organizacyjne (wielkość zespołu, umiejętności, harmonogram, budżet)
• Powołuj się na wcześniejsze decyzje, na których ta się opiera

4. Czynniki decyzyjne

Rankingowa lista kryteriów, które są najważniejsze:

• Wymagania wydajnościowe (opóźnienie, przepustowość, zużycie zasobów)
• Doświadczenie programisty (krzywa uczenia, narzędzia, debugowanie)
• Koszt operacyjny (hosting, utrzymanie, monitoring)
• Postawa bezpieczeństwa
• Czas implementacji
• Odwracalność

5. Rozważane opcje

Dla każdej opcji:

Zasady:

• Minimum 2 opcje, maksimum 5
• Zawsze uwzględnij „Nic nie rób / Status quo" jako opcję
• Zalety I wady dla każdej — żadna opcja nie jest idealna
• Bądź szczery co do niewiadomych: „Nie wiemy jeszcze X"

6. Decyzja

Jedno jasne zdanie: „Użyjemy [X], ponieważ [Y]."

7. Konsekwencje

Pozytywne:

• Co się poprawia w wyniku tej decyzji

Negatywne (zaakceptowane kompromisy):

• Co się pogarsza lub utrudnia
• Jakie ryzyka są wprowadzone

Neutralne:

• Co się zmienia, ale nie jest wyraźnie lepsze ani gorsze

8. Działania następcze

Konkretne kolejne kroki do wdrożenia decyzji.

Proces

1. Zbierz kontekst — zapytaj o problem, ograniczenia, zespół, harmonogram
2. Zidentyfikuj opcje — zaproponuj alternatywy (zbadaj jeśli potrzeba)
3. Zbuduj macierz porównawczą — oceń każdą wobec czynników decyzyjnych
4. Daj rekomendację — z jawnym uzasadnieniem
5. Udokumentuj — stwórz ADR w formacie markdown
6. Zakwestionuj — zagraj adwokata diabła wobec wybranej opcji

Antywzorce

• Dokumentowanie decyzji już podjętej, żeby odfajkować checkbox (analiza musi być autentyczna)
• Paraliż analityczny — jeśli opcje są blisko, powiedz to i wybierz jedną
• Ignorowanie „nic nie rób" — to często właściwa odpowiedź
• Ukrywanie kompromisów — każda opcja ma wady, wymień je
• Przerabianie ewaluacji dla trywialnych decyzji