Implementacja Napędzana Specyfikacją

Wzorzec

Napisz specyfikację ZANIM napiszesz jakikolwiek kod. Specyfikacja jest kontraktem — definiuje jak wygląda „gotowe" zanim zacznie się implementacja.

Spec → Plan → Build → Weryfikacja → Ship

Dlaczego najpierw spec

Bez specyfikacji AI ma tendencję do:

• Pewnego rozwiązywania złego problemu
• Dodawania funkcji, o które nie proszono
• Podejmowania decyzji architektonicznych bez pytania
• Produkowania kodu, który „działa" ale nie pasuje do systemu

Specyfikacja zapobiega temu wszystkiemu, bo każda decyzja implementacyjna może być sprawdzona wobec napisanego wymagania.

Szablon specyfikacji

## Spec funkcji: {nazwa}

### Cel
{Jedno zdanie: jaki problem to rozwiązuje?}

### Wymagania
1. {Wymaganie — testowalne, konkretne}
2. {Wymaganie — testowalne, konkretne}
3. {Wymaganie — testowalne, konkretne}

### Nie-wymagania (jawnie poza zakresem)
- {Czego NIE budujemy}
- {Jaki edge case NIE obsługujemy}

### Ograniczenia
- Musi działać z: {istniejący system/API/wzorzec}
- Nie może zepsuć: {istniejąca funkcjonalność}
- Wydajność: {wymagania latencji/przepustowości/rozmiaru}
- Bezpieczeństwo: {wymagania auth, walidacji, obsługi danych}

### Kontrakt interfejsu
{Jak inny kod będzie wchodzić w interakcję? Kształt API, propsy, eventy, etc.}

### Kryteria akceptacji
- [ ] {Kryterium 1 — weryfikowalne}
- [ ] {Kryterium 2 — weryfikowalne}
- [ ] {Kryterium 3 — weryfikowalne}

Proces

Faza 1: Napisz spec (10 min)

1. Sformułuj cel w jednym zdaniu
2. Wylistuj wymagania (testowalne, konkretne)
3. Wylistuj nie-wymagania (czego NIE robimy)
4. Zdefiniuj ograniczenia (jaki istniejący kod musi być respektowany)
5. Zdefiniuj kontrakt interfejsu (jak kod będzie wywoływany/używany)
6. Napisz kryteria akceptacji (jak zweryfikujemy, że działa)

Faza 2: Plan (5 min)

1. Rozłóż spec na kroki implementacji
2. Zidentyfikuj pliki do stworzenia/modyfikacji
3. Zidentyfikuj zależności między krokami
4. Oszacuj: czy to 30 minut czy 3 godziny?

Faza 3: Build (większość czasu)

1. Implementuj krok po kroku, podążając za planem
2. Po każdym kroku sprawdź: czy to spełnia wymaganie ze specyfikacji?
3. Jeśli musisz odejść od specyfikacji — ZATRZYMAJ SIĘ. Najpierw zaktualizuj spec, potem kontynuuj.
4. Commituj po każdym ukończonym wymaganiu

Faza 4: Weryfikacja (10 min)

1. Przejdź przez każde kryterium akceptacji
2. Uruchom testy
3. Sprawdź każde wymaganie specyfikacji: czy jest zaimplementowane?
4. Sprawdź nie-wymagania: czy przypadkiem nie dodaliśmy pełzania zakresu?

Zasady operacyjne

1. Żadnego kodu przed akceptacją specyfikacji — spec musi być przejrzany zanim zacznie się implementacja
2. Zmiany specyfikacji wymagają jawnego potwierdzenia — jeśli wymagania się zmienią w trakcie build, zaktualizuj spec i zanotuj zmianę
3. Każdy PR odwołuje się do specyfikacji — identyfikowalność od kodu do wymagania
4. Nie-wymagania są święte — oprzyj się pokusie dodania „jeszcze jednej rzeczy"
5. Kryteria akceptacji to testy — napisz je jako testy przed pisaniem implementacji

Kiedy używać

• Każda funkcja wymagająca więcej niż 30 minut implementacji
• Zmiany dotykające więcej niż 3 pliki
• Każda praca obejmująca kontrakty API lub zmiany modelu danych
• Gdy wiele osób (lub sesji) będzie pracować nad tą samą funkcją
• Gdy koszt „źle" jest wysoki (auth, płatności, migracja danych)

Antywzorce

• Spec tak ogólnikowy, że może znaczyć cokolwiek („zrób lepiej")
• Spec tak szczegółowy, że jest już pseudokodem (to plan, nie specyfikacja)
• Pomijanie nie-wymagań (pełzanie zakresu wchodzi przez te drzwi)
• Niezaktualizowanie spec gdy wymagania zmieniają się w trakcie build
• Pisanie spec po napisaniu kodu (to dokumentacja, nie specyfikacja)