Spec-Driven Development (SDD)

1. Przegląd koncepcji i problem systemowy

Najczęstszym błędem początkujących developerów w podejściu „vibe coding” jest metoda „Prompt-and-Pray” (sformułowanie rozmytego zapytania w czacie i liczenie na to, że model odgadnie architekturę). Gdy prompt brzmi jak „Zrób billing przez Stripe dla subskrybentów”, model samodzielnie wybiera losowe schematy bazy danych, używa przestarzałych bibliotek, ignoruje webhooki, zapomina o idempotentności i nie uwzględnia przypadków brzegowych związanych z anulowaniem płatności. Gdy inżynier prosi o naprawę buga, model zaczyna gorączkowo łatać dziury, finalnie przekształcając bazę kodu w spaghetti code (AI Slop).

Spec-Driven Development (SDD, rozwój sterowany specyfikacjami) to dyscyplina inżynierska oddzielająca etap projektowania systemowego od etapu generowania kodu. Zanim dotkniemy bazy kodu, tworzony jest sformalizowany dokument specyfikacji (spec.md lub RFC.md). Dokument ten staje się jedynym źródłem prawdy (Single Source of Truth) oraz kontraktem, względem którego agent wykonuje i weryfikuje każdy kolejny krok.

2. Taksonomia architektury i model mentalny

Szkielet architektoniczny SDD opiera się na wyraźnej hierarchii artefaktów projektowych:

┌─────────────────────────────────────────────────────────────┐
│             HIERARCHIA ARTYKUŁÓW W ROZWOJU                  │
│             OPARTYM NA SPECYFIKACJI (SPEC-DRIVEN)           │
├─────────────────────────────────────────────────────────────┤
│ 1. Kontekst Produktu: Problem użytkownika i cel biznesowy   │
├─────────────────────────────────────────────────────────────┤
│ 2. Kontrakty Techniczne:                                    │
│    • Schematy danych (Schematy Drizzle / Prisma, SQL DDL)   │
│    • Kontrakty API (Schematy Zod, OpenAPI, typy TypeScript) │
│    • Inwarianty i Reguły Bezpieczeństwa                     │
│      (Idempotentność, RBAC, Uwierzytelnianie)               │
├─────────────────────────────────────────────────────────────┤
│ 3. Lista Kontrolna Zadań Atomowych (DAG):                   │
│    • Krok 1 ➔ Krok 2 ➔ Krok 3                               │
│      (Ścisła kolejność zależności)                          │
├─────────────────────────────────────────────────────────────┤
│ 4. Predykaty Weryfikacji: Maszynowe kryteria gotowości      │
└─────────────────────────────────────────────────────────────┘

1. Kontrakty techniczne (Interface-First):
   • Opis interakcji systemów przed implementacją logiki wewnętrznej. Definiowane są struktury żądań/odpowiedzi, schematy walidacji oraz stany błędów.
2. Atomowy graf zadań (Task Decomposition DAG):
   • Zadanie rozbijane jest na sekwencję drobnych, niezależnie weryfikowalnych podzadań. Każde podzadanie powinno modyfikować nie więcej niż 1–3 pliki.
3. Kryteria akceptacyjne weryfikowalne maszynowo (Acceptance Predicates):
   • Zamiast subiektywnego „sprawdź, czy wszystko działa”, specyfikacja zawiera konkretne komendy weryfikujące: „pnpm test auth.test.ts przechodzi pomyślnie, pokrycie gałęzi > 90%”.
4. Tracker cyklu życia statusu (Lifecycle Tracker):
   • Specyfikacja zawiera interaktywne pola wyboru ([ ] ➔ [x]), które agent aktualizuje po wykonaniu i zweryfikowaniu każdego kroku.

3. Pipeline techniczny i mechanika wewnętrzna

Cykl życia rozwoju w metodologii SDD:

1. Wywiad i synteza specyfikacji (Interview Phase): Inżynier formułuje zadanie. Model zadaje pytania doprecyzowujące dotyczące nietrywialnych szczegółów: jaka zachowanie oczekiwane jest przy zerwaniu połączenia sieciowego, jak obsługiwać duplikaty, jakie limity rate-limitingu obowiązują.
2. Utrwalenie specyfikacji w repozytorium: Tworzony jest artefakt (np. .specs/004-billing-integration.md), który zostaje dodany do systemu kontroli wersji Git.
3. Audyt ludzki i zatwierdzenie (Spec Approval): Inżynier przegląda zaproponowane schematy danych i kontrakty. Jeśli decyzja architektoniczna zawiera wady, są one korygowane na poziomie tekstu specyfikacji w ciągu 2 minut, co pozwala uniknąć godzin przepisywania kodu.
4. Etapowe delegowanie agentowi (Step-by-Step Execution): Agent wywoływany jest do realizacji konkretnego kroku ze specyfikacji:
   • Agent czyta kontekst specyfikacji.
   • Pisze testy zgodnie z kontraktami (TDD).
   • Implementuje funkcjonalność.
   • Uruchamia testy i rejestruje wykonanie podzadania.
5. Finalna weryfikacja i archiwizacja: Gdy wszystkie punkty specyfikacji zostaną oznaczone jako wykonane, przeprowadzany jest audyt end-to-end, a specyfikacja pozostaje w repozytorium jako żywa dokumentacja funkcji.

4. Praktyczne scenariusze inżynierskie w środowisku produkcyjnym

01. Rozwój krytycznego modułu płatniczego z idempotentnością

Przed napisaniem kodu integracji bramki płatniczej inżynier tworzy specyfikację:

• Ustala strukturę tabeli idempotency_keys z polami key, response_payload, status, expires_at.
• Opisuje dokładny algorytm zachowania przy otrzymaniu powtórnego webhooka z podobnym transaction_id.
• Agent implementuje moduł ściśle według specyfikacji; żaden przypadek brzegowy nie zostaje pominięty.

02. Równoległa praca agentów backendowych i frontendowych

Zespół tworzy nowy dashboard analityczny:

• Najpierw w specyfikacji opisane są schematy Zod oraz interfejsy TypeScript dla wszystkich wykresów i metryk.
• Agent frontendowy wykorzystuje te schematy do budowy komponentów z danymi mockowymi.
• Agent backendowy jednocześnie implementuje rzeczywiste zapytania SQL oraz route'y API pod ten sam kontrakt.
• Integracja przebiega bez żadnych konfliktów niezgodności typów.

03. Bezpieczna migracja dużego modułu legacy

Zastąpienie starej, autorskiej autoryzacji przez Better Auth:

• Specyfikacja opisuje zachowanie kompatybilności wstecznej sesji w Redis oraz etapowy plan migracji hashy haseł z bcrypt na Argon2id.
• Agent rozbija migrację na 7 izolowanych etapów, z których każdy jest testowany osobno.

5. Pułapki, typowe błędy i bezpieczeństwo

• Paraliż nadmiernego projektowania (Over-Engineering Paralysis): Napisanie 20-stronicowej specyfikacji dla drobnej poprawki wcięć lub zmiany koloru przycisku to bezsensowna strata czasu. Stosuj SDD dla zadań obejmujących więcej niż 2 moduły lub zawierających krytyczną logikę biznesową.
• Desynchronizacja kodu i specyfikacji (Spec Rot): Jeśli podczas rozwoju zajdzie potrzeba zmiany schematu, inżynierowie często poprawiają kod bezpośrednio, zapominając o aktualizacji spec.md. To dezorientuje kolejnych agentów, którzy ponownie przeczytają przestarzałą specyfikację.
• Stosowanie rozmytych sformułowań: Frazy typu „system powinien działać szybko” lub „zapewnić niezawodność” są katastrofalne dla AI. Specyfikacja musi operować konkretnymi wartościami: „czas odpowiedzi p99 < 150ms”, „zwracać HTTP 429 przy przekroczeniu 100 rpm”.
• Ignorowanie wersjonowania specyfikacji: Pliki specyfikacji powinny być częścią repozytorium Git wraz z kodem, co umożliwia śledzenie ewolucji decyzji architektonicznych poprzez historię commitów.