Spec-Driven Development z Claude Code — rok później, podsumowanie

12 miesięcy temu napisałem post o Spec-Driven Development w Claude Code. Polegał na metodologii: requirements → design → tasks → implementation, każdy krok jako artefakt w .kiro/. Rok później mam wystarczająco danych żeby ocenić co działa, a co nie.

Co potwierdziło się

1. Requirements jako EARS są game-changer

Format: When [event], the system shall [response]. Wymusza myślenie "warunki + zachowanie", a nie "fajna funkcjonalność do dodania".

Po roku: 90% requirementów które piszę w EARS są łatwe do testowania, łatwe do review. Niewspółmiernie więcej niż "user-stories".

2. Faza design oszczędza czas

Pisanie design.md przed kodem w stylu "tu dokumentuję wybory architektoniczne, alternatywy które rozważałem, dlaczego wybrałem to", zwraca się 3:1.

Konkretnie: ostatni feature (auth refactor), 1 godzina design + 4 godziny kodu = 5h total. Wcześniej (bez design) podobne robiłem w 8h, z 2 falstartami.

3. Spec → tasks decomposition działa świetnie z AI

Agent dostaje requirements.md + design.md, wypluwa tasks.md z konkretną listą. 80% tasków jest dobrze rozłożonych. 20% wymaga manual cleanupu. Akceptowalne.

Czego się NIE potwierdziło

1. Strict gate'ing między fazami

Pierwotnie: nie zaczynaj design'u dopóki requirements zaakceptowane, nie zaczynaj implementacji dopóki tasks zaakceptowane.

W praktyce: między design'em a implementacją wracam do requirements wielokrotnie. Strict gate to LARP. Real-world workflow to zigzagi.

Co zmieniłem: przeszedłem na "soft phases", artefakty istnieją, ale można je modyfikować równolegle.

2. Task estimation w godzinach

tasks.md miał kolumnę "estimated time". Po 6 miesiącach okazało się że estymaty są ±200% rzeczywistości. Zrezygnowałem.

Co zostawiłem: kolumnę "complexity (S/M/L)". Mniej dokładnie, ale pokrywa się z reality.

3. SDD na małe taski

Spec dla feature'u "dodaj toggle switch w settings" to overkill. Próbowałem przez 2 miesiące, w końcu zrezygnowałem. SDD ma sens dla rzeczy > 4 godzinowych.

Kiedy SDD WYRAŹNIE pomaga

Trzy klasy zadań gdzie zwrot jest ewidentny:

1. Multi-file refactors. Zmiana dotykająca 5+ plików. Bez specy → drift, scope creep, zmiana 1/3 zostaje na potem. Ze specem → jeden ruch, predictable.

2. Cross-team features. Cokolwiek wymagającego review przez kogoś innego. requirements.md + design.md to kontekst który ktoś czyta zamiast 50-message Slack thread.

3. Risky migrations. Schema change, infrastructure rewrite, auth flow change. Spec wymusza myślenie o rollback i backwards compatibility. Bez spec'u, większy szansa na produkcyjne fuckup.

Kiedy SDD WYRAŹNIE szkodzi

1. Eksploracja "co tu w ogóle jest". Nie wiesz co chcesz, spec to performance theater. Najpierw eksploracja, potem spec.

2. Hot fix. Bug w produkcji, klienci dzwonią. SDD = 30 minut overhead. Naprawiaj, dokumentuj potem.

3. UI iteration. "Zmień kolor, zobacz". Każda zmiana to nowy design.md? No way. Dla UI używam pl-quick-iter workflow bez SDD.

Liczby z roku

Z mojego workspace:

Łączna liczba spec'ów: 47
Średnia długość requirements.md: 35 linii
Średnia długość design.md: 80 linii
Średnia długość tasks.md: 25 zadań
Procent spec'ów które poszły do produkcji bez modyfikacji design'u: 60%
Procent gdzie spec został porzucony w połowie: 12%

12% porzuceń to znaczący wskaźnik. Część była "zorientowałem się że to zły pomysł" (good outcome, spec zatrzymał mnie wcześniej). Część była "scope poszedł w bok" (bad, koszt sunk).

Mój workflow dzisiaj

Triaging: zadanie < 4h → bezpośrednio. Zadanie > 4h → SDD.
Requirements: max 1 strona, EARS. Jak wymyka się na 3 strony, scope za duży, podziel.
Design: tylko sekcje "Key Decisions" + "Alternatives Considered" + "Critical Files". Reszta zbędna.
Tasks: 5-15 zadań. Mniej = za grube. Więcej = nie SDD a bug-tracker.
Implementation: w plan mode dla nietrywialnych. ExitPlanMode → execute.
Po-implementacji: aktualizuję design.md jeśli rzeczywistość zboczyła od pierwotnego planu.

Co bym sobie powiedział rok temu

Nie traktuj SDD jak religii. To narzędzie. Działa świetnie dla pewnych klas zadań, kompletnie nie dla innych. Reguła decyzyjna ważniejsza niż checklista.

Inwestuj w design.md, oszczędzaj na requirements.md. Design rozwiązuje 80% przyszłych pytań. Requirements jest sprawdzaczem ostatniej obrony.

Akceptuj porzucenia. 12% spec'ów porzuciłem. Nie żałuję. Tych 12% w starej metodologii skończyłbym przez "skoro już zacząłem". Now that's sunk cost fallacy.

SDD po roku: zostaje jako mój default dla średnich i dużych zadań. Ze świadomymi modyfikacjami i bez ortodoksji. Najważniejsza nauka: forma artefaktu jest mniej ważna niż rytuał myślenia który wymusza.