architecture-decision-records
Dokumentuj decyzje architektoniczne w zespole – kontekst, wybór, konsekwencje
Instalacja
Wybierz klienta i sklonuj repozytorium do odpowiedniego katalogu skilli.
Instalacja
O skillu
Skill do tworzenia i utrzymania Architecture Decision Records (ADR) – dokumentów, które utrwalają znaczące decyzje techniczne. Zapisujesz kontekst problemu, podjętą decyzję i jej skutki. Przydatne przy wyborze nowych technologii, dokumentowaniu trade-offów projektowych, onboardingu zespołu i przeglądzie historycznych wyborów architektonicznych.
Jak używać
Zidentyfikuj znaczącą decyzję architektoniczną – nową technologię, zmianę bazy danych, wzorzec API lub rozwiązanie bezpieczeństwa. Pomiń drobne zmiany wersji, poprawki błędów i rutynową konserwację.
Przygotuj kontekst decyzji: opisz problem, który wymusił wybór, ograniczenia techniczne, doświadczenie zespołu i wymagania biznesowe (np. skalę, wydajność, zgodność).
Użyj szablonu MADR (Markdown Architecture Decision Records) – zacznij od nagłówka ADR z numerem, ustaw status na "Proposed", następnie wypełnij sekcje Context, Decision Drivers i Decision.
Udokumentuj decyzję jasno: co wybrałeś i dlaczego. Wymień alternatywy, które rozważałeś, i powody odrzucenia każdej z nich.
Opisz konsekwencje – zarówno pozytywne (np. lepsza wydajność) jak i negatywne (np. krzywa uczenia się zespołu). To pomaga przyszłym członkom zrozumieć trade-offy.
Przechowuj ADR w repozytorium obok kodu – w katalogu
docs/adrlub podobnym. Aktualizuj status decyzji w miarę upływu czasu (Accepted → Deprecated → Superseded), gdy pojawią się nowe informacje lub zmieni się architektura.