architecture-decision-records
Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.
Installation
Pick a client and clone the repository into its skills directory.
Installation
About this skill
Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.
How to use
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.