---
name: architecture-decision-record
title: Rekord Decyzji Architektonicznych
description: "Ustrukturyzowany framework do podejmowania i dokumentowania decyzji architektonicznych. Tworzy dokument ADR z kontekstem, ograniczeniami, analizą opcji, uzasadnieniem decyzji i konsekwencjami. Zapobiega problemowi „dlaczego tak to zrobiliśmy?\" miesiące później. Działa dla dowolnego stacku — od monolitu po mikroserwisy, od wyboru bazy danych po projektowanie API."
category: coding
tags:
  - architektura
  - podejmowanie-decyzji
  - dokumentacja
  - projektowanie-systemów
  - planowanie
requires:
  - Claude
source: https://madejski.ai/pl/skilloteka/architecture-decision-record
locale: pl
license: MIT
---

# 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:
| Kryterium | Opcja A | Opcja B | Opcja C |
|-----------|---------|---------|---------|
| Wydajność | ... | ... | ... |
| Doświadczenie dev | ... | ... | ... |
| Koszt | ... | ... | ... |

**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