Spec Driven Development jako inżynierska odpowiedź na „vibe coding”

W poprzednim wpisie – Vibe Coder vs Software Engineer – nowa wojna światów? – pisałem o tym, czym różni się podejście vibe codera i inżyniera do programowania z AI. Ktoś mógłby słusznie zapytać: no dobra, ale jak to wygląda w praktyce? Co właściwie odróżnia „mówię do AI, czego chcę” od „mówię do AI, czego chcę, i wiem, co robię”? Z boku przecież wygląda to identycznie – człowiek siedzi przed czatem i pisze.

Odpowiedź podsunął mi film Spec-Driven Development in 7 Minutes (otwiera się w nowej karcie), który ostatnio wpadł mi w oko na YouTube. Okazuje się, że podejście inżynierskie do pracy z AI ma już swoją nazwę, metodologię, a nawet gotowe narzędzie od GitHuba. I o tym będzie właśnie ten wpis.

Od razu uczciwe zastrzeżenie: tego narzędzia jeszcze nie testowałem. Zamierzam to zrobić na nowym projekcie, ale dziś będzie od strony teorii – co to jest, skąd się wzięło i dlaczego mnie zaciekawiło. Praktyka i ewentualne wtopy – w kolejnym odcinku 🙂

Co jest nie tak z vibe codingiem?

Typowa sesja z AI wygląda mniej więcej tak: opisujesz, czego chcesz, AI pisze kod, uruchamiasz i… prawie. Działa, ale nie do końca tak, jak to sobie wyobrażałeś. Więc poprawiasz prompt. AI poprawia kod. Teraz działa to, co wcześniej nie działało, ale przestało działać coś innego. Poprawiasz prompt jeszcze raz. I jeszcze raz…

Kto pracował z AI, ten zna. Szkoda czasu (i tokenów, za które ktoś przecież płaci), ale to nie jest największy problem. Największy problem jest taki, że po drodze tracimy kontrolę nad decyzjami. AI musi jakoś uzupełnić każde niedopowiedzenie w prompcie – więc zgaduje. Czasem trafnie, czasem nie. A my często nawet nie wiemy, że jakaś decyzja w ogóle zapadła.

Wyobraźmy sobie, że zamawiamy u stolarza meble kuchenne słowami: „chcę ładną kuchnię”. Stolarz coś zrobi. Pewnie nawet ładnego. Ale wysokość blatu, kolor frontów i miejsce na zmywarkę wybierze sam. A potem się zaczyna: „to przerobić, tamto przesunąć, a tu miała być szuflada…”. Każda poprawka kosztuje, a gotowe szafki przerabia się dużo trudniej niż rysunek na kartce.

Autor filmu dorzuca jeszcze jedną obserwację: z całego procesu tworzenia oprogramowania – wymagania, projekt, budowa, testy, wdrożenie, utrzymanie – vibe coding skupia się praktycznie tylko na budowie. Reszta dzieje się „przy okazji” albo wcale.

Najpierw testy, teraz specyfikacja

Kto w branży trochę siedzi, ten zna TDD (Test Driven Development) – najpierw piszemy test, który sprawdza, czy kod robi to, co powinien, a dopiero potem kod – tak długo, aż test zaświeci się na zielono.

Spec Driven Development (w skrócie SDD) idzie o krok dalej – a właściwie o krok wcześniej. Zanim powstanie test i zanim powstanie kod, powstaje specyfikacja: dokument, który opisuje, co ma robić funkcja i dlaczego, ale nie mówi ani słowa o tym, jak ma to być zrobione. Żadnych frameworków, baz danych ani nazw plików. Tylko potrzeby użytkownika i zasady działania.

Brzmi jak papierologia? Trochę tak. Ale dobra specyfikacja wyciąga na wierzch decyzje, które w vibe codingu zapadają po cichu. Co ma się stać, gdy ktoś zostawi puste pole? A gdy wpisze coś dziwnego? Jakie są ograniczenia? I wreszcie – czego ta funkcja ma nie robić? Ten ostatni punkt jest moim zdaniem mocno niedoceniany. AI uwielbia robić „trochę więcej, niż prosiłeś”, a lista rzeczy poza zakresem to najprostszy sposób, żeby je przed tym powstrzymać.

Kod na usługach specyfikacji

GitHub, który przygotował narzędzie do pracy w tym modelu (o nim za chwilę), opisuje SDD jako odwrócenie dotychczasowego układu sił:

Specifications don’t serve code – code serves specifications.

– Spec-Driven Development, GitHub Spec Kit (otwiera się w nowej karcie)

Czyli: to nie specyfikacja służy kodowi, tylko kod służy specyfikacji.

Do tej pory źródłem prawdy był kod. Dokumentacja powstawała na początku (o ile w ogóle), a potem coraz bardziej rozjeżdżała się z rzeczywistością – aż nikt do niej nie zaglądał, bo „i tak jest nieaktualna”. W SDD jest odwrotnie: najważniejsza jest specyfikacja, a kod to tylko jej „tłumaczenie” na konkretny język programowania. Chcesz coś zmienić? Zmieniasz specyfikację, a z niej powstaje nowy kod.

Ktoś powie – to się nie uda, kod zawsze będzie żył własnym życiem. Pewnie będzie miał trochę racji, jeszcze do tego wrócę. Ale sama idea bardzo mi się podoba, bo dokładnie w tym kierunku zmienia się nasza praca: wartość programisty przesuwa się z pisania kodu na podejmowanie decyzji, zanim ten kod powstanie. O tym samym pisałem we wpisie Programista w czasach AI – SDD zamienia tę myśl w konkretny proces.

Jak to wygląda krok po kroku?

Te 5 kafelków to kolejne etapy pracy w SDD – te same, które widać na okładce. A żeby było bardziej przystępnie, porównam je do budowy domu. Temat znam z własnego podwórka – i jak pisałem przy okazji modernizacji domowej sieci komputerowej, do dziś żałuję, że budując dom, za mało myślałem o elektryce…

1. Konstytucja (zwój z tarczą) – stałe zasady całego projektu: w czym piszemy, jakie mamy konwencje i standardy bezpieczeństwa, czego robić nie wolno. Powstaje raz, na samym początku. W budowie domu to prawo budowlane i warunki zabudowy – nie dyskutujemy z nimi przy każdej ścianie.
2. Specyfikacja (lista ze znakiem zapytania) – co dokładnie ma powstać i po co. Dom ma mieć np. 4 sypialnie, garaż i być parterowy, bo nikt nie chce biegać po schodach. Ale jeszcze bez cegieł, betonu i rodzaju dachówki. Znak zapytania też nie jest przypadkowy – wrócę do niego przy Spec Kit.
3. Plan (schemat blokowy) – dopiero tu wchodzi technologia: z czego budujemy, jaki fundament, jaka instalacja. To projekt architekta.
4. Zadania (lista z polami do odhaczenia) – plan rozbity na małe, uporządkowane kroki. Najpierw fundamenty, potem ściany, na końcu dach. Harmonogram dla ekipy.
5. Implementacja (okno z kodem) – AI pisze kod zadanie po zadaniu – żadnej „całej aplikacji w jednym prompcie”. Ekipa buduje etap po etapie.

Zostaje jeszcze pętla, która wraca od kodu do specyfikacji. To krok, który w narzędziu od GitHuba nazywa się converge – coś w rodzaju odbioru technicznego. Narzędzie porównuje to, co powstało, ze specyfikacją, planem i listą zadań. Jeśli czegoś brakuje albo coś odbiega od ustaleń, dopisuje nowe zadania i pętla kręci się dalej, aż wszystko się zgadza. Trochę jak inspektor nadzoru, który chodzi po budowie z projektem pod pachą i spisuje usterki.

I najważniejsza zasada, którą podkreśla autor filmu: po każdym etapie trzeba przeczytać wynik, zanim przejdzie się dalej. Nie „dalej, dalej, dalej, gotowe”. Bo jeśli specyfikacja jest zła, to plan też będzie zły, a kod – jeszcze gorszy.

Spec Kit – czyli SDD w pudełku

Całą tę teorię można stosować z kartką i długopisem, ale GitHub przygotował do tego gotowe narzędzie: Spec Kit (otwiera się w nowej karcie). Jest darmowe, ma otwarty kod i – co dla mnie ważne – nie przywiązuje do jednego dostawcy AI. Działa m.in. z Claude Code, GitHub Copilotem, Gemini CLI czy Cursorem.

Nie będę tu opisywać instalacji, bo dokumentacja (otwiera się w nowej karcie) robi to lepiej, a narzędzie zmienia się na tyle szybko, że tutoriale starzeją się w oczach. W dużym skrócie: w czacie z AI dostajemy po jednej komendzie na każdy etap z listy powyżej (np. /speckit-specify do specyfikacji), a każda z nich zostawia po sobie zwykły plik tekstowy w repozytorium. Taki plik czyta potem i AI (jako kontekst do kolejnego kroku), i człowiek (jako dokumentację).

Najbardziej spodobał mi się jeden szczegół: szablony Spec Kit zabraniają AI zgadywania. Jeśli w opisie funkcji czegoś brakuje, model nie ma tego dopowiadać po swojemu, tylko oznaczyć w specyfikacji znacznikiem [NEEDS CLARIFICATION] z konkretnym pytaniem. Dokumentacja podaje fajny przykład: prosisz o „system logowania”, a AI, zamiast od razu założyć login i hasło, pyta, jaką metodę logowania masz na myśli. Stąd właśnie znak zapytania na schemacie.

Don’t guess: If the prompt doesn’t specify something, mark it.

– Spec-Driven Development, GitHub Spec Kit (otwiera się w nowej karcie)

Czyli: nie zgaduj – jeśli czegoś nie ma w poleceniu, zaznacz to. Gdyby każdy programista – junior czy senior – trzymał się tej zasady, branża zaoszczędziłaby całe tygodnie na code review…

Spec Kit nie jest zresztą jedyny. W filmie pojawiają się jeszcze 2 inne narzędzia o podobnym modelu pracy: OpenSpec i BMAD Method. Widać, że temat jest gorący.

Rabat za newsletter – czyli diabeł tkwi w szczegółach

Żeby nie było zbyt abstrakcyjnie – weźmy funkcję, którą każdy zna z zakupów w internecie: „Zapisz się do newslettera i odbierz 10% rabatu na pierwsze zamówienie”.

W wersji vibe codingowej prompt wygląda mniej więcej tak: „Dodaj do sklepu zapis do newslettera z rabatem 10% na pierwsze zamówienie”. AI zrobi formularz, wygeneruje kod rabatowy, podepnie go pod koszyk. Działa! Do czasu, aż ktoś zacznie zadawać pytania:

• co, jeśli ktoś zapisze się 2 razy – raz jako Jan@example.com, a raz jako jan@example.com? Dostanie 2 kody?
• czy kod można wykorzystać ponownie?
• co z produktami, które są wyłączone z promocji?
• czy rabat liczymy od kwoty z dostawą, czy bez?
• co się dzieje z kodem, gdy klient anuluje zamówienie?

W każdej z tych kwestii AI jakąś decyzję „podjęło” – tylko nikt jej świadomie nie zatwierdził. I dowiemy się o niej dopiero wtedy, gdy ktoś sprytny odkryje, że rabat da się zgarnąć kilka razy.

W SDD te pytania padają przed pierwszą linijką kodu. Przykładowa specyfikacja – w uproszczeniu i po polsku – mogłaby wyglądać tak:

Historia użytkownika: jako klient sklepu chcę zapisać się do newslettera, żeby dostać 10% rabatu na pierwsze zamówienie.

Scenariusze:

• Gdy klient, który nie jest jeszcze zapisany, poda poprawny adres e-mail i zaznaczy zgodę marketingową, zostaje zapisany i dostaje jednorazowy kod rabatowy.
• Gdy klient, który użył już kodu, spróbuje zrobić to ponownie, sklep odrzuca kod z informacją, że został wykorzystany.
• Gdy w koszyku są produkty za 200 zł, a klient wpisze ważny kod, widzi rabat 20 zł i kwotę 180 zł przed doliczeniem dostawy.

Przypadki brzegowe: wielkość liter w adresie e-mail nie ma znaczenia, anulowane zamówienie nie „oddaje” kodu, rabat nie obejmuje produktów wyłączonych z promocji.

Poza zakresem: program lojalnościowy, łączenie z innymi promocjami, wybór dostawcy mailingu (to decyzja na etap planu).

Zauważcie, że nie ma tu ani słowa o tym, w czym sklep jest napisany ani jakiej używa bazy danych – to pojawi się dopiero w planie. Za to każdy scenariusz da się 1:1 zamienić w test – a to znaczy, że na koniec można obiektywnie sprawdzić, czy AI zrobiło to, co miało zrobić. Zamiast „wydaje mi się, że działa” – lista spełnionych scenariuszy.

I jeszcze jedno: taką specyfikację przeczyta i zrozumie właściciel sklepu, marketingowiec czy tester. Nie trzeba znać się na programowaniu, żeby powiedzieć: „chwila, rabat miał obejmować też dostawę”. A lepiej usłyszeć to na etapie kartki niż gotowego kodu.

Czy ja już nie robię SDD?

Drugi przykład jest bliżej mnie – dosłownie, bo to blog, który właśnie czytacie.

W repozytorium tego bloga leży kilka dokumentów, które Claude Code czyta, zanim cokolwiek zmieni. W pliku CLAUDE.md są stałe zasady projektu – jak pisać kod, czego pilnować pod kątem bezpieczeństwa i dostępności. Dokument z architekturą jest opisany wprost jako „źródło prawdy”. A plan wdrożenia to kolejne fazy z checklistami, w których AI odhacza zakończone kroki.

Nic Wam to nie przypomina? Konstytucja, plan, zadania – brakuje tylko specyfikacji dla każdej funkcji. Robię więc coś bardzo podobnego – ręcznie i bez ładnej nazwy 🙂

Co w takim razie daje narzędzie ponad to, co już mam? Po pierwsze – powtarzalny proces dla każdej pojedynczej funkcji, a nie tylko dla projektu jako całości. Po drugie – wymuszone pytania o niejasności zamiast zgadywania. Po trzecie – converge, czyli automatyczne sprawdzenie, czy kod zgadza się z ustaleniami. Tego ostatniego jestem najbardziej ciekaw, bo dziś inspektorem z projektem pod pachą jestem ja.

Przy okazji: przykładowa konstytucja z dokumentacji Spec Kit jest mocno „backendowa” i do aplikacji frontendowej pasuje średnio. Trzeba ją będzie dopasować do siebie – dobra wiadomość jest taka, że swoją w zasadzie już mam.

Czy to nie przerost formy?

Byłbym nieuczciwy, gdybym na tym skończył. W poprzednim wpisie nabijałem się z inżynierów, którzy chcą „mikroserwisów i Kubernetesa – po co? Nie wiemy!”. SDD łatwo może wylądować w tym samym miejscu. Kilka rzeczy budzi moje wątpliwości – jeszcze zanim w ogóle zacznę testy:

• narzut – do poprawienia literówki na przycisku nie potrzeba konstytucji, specyfikacji i planu. Twórcy Spec Kit zresztą sami to przyznają – stąd skrócona ścieżka dla małych funkcji i osobny proces do naprawiania błędów
• dużo czytania – każdy etap to dokument, który trzeba przejrzeć. Wąskie gardło przesuwa się z pisania kodu na czytanie specyfikacji. Lepiej? Pewnie tak, ale to nadal czas
• specyfikacja kontra rzeczywistość – pomysł, że wystarczy zmienić specyfikację i „wygenerować kod od nowa”, brzmi pięknie. Tylko że AI z tej samej specyfikacji za każdym razem napisze trochę inny kod. Dokument i kod mogą się rozjechać tak samo jak kiedyś
• tempo zmian – narzędzie rozwija się błyskawicznie, nazwy komend i sposób ich instalowania już się zmieniały. Poradnik sprzed pół roku może dziś nie działać

Kiedy więc warto? Jak zwykle odpowiedź brzmi: to zależy. Do jednorazowego skryptu czy szybkiego prototypu – szkoda zachodu, tu vibe coding sprawdza się świetnie. Do funkcji, w której chodzi o pieniądze, dane klientów albo pracę kilku osób przez kilka miesięcy – jak najbardziej. Wróćmy do rakiet z poprzedniego wpisu: fajerwerk na sylwestra nie potrzebuje specyfikacji. Rakieta z ludźmi na pokładzie – zdecydowanie tak.

Czyli vibe coding do kosza?

Nie. SDD nie jest zaprzeczeniem pracy z AI, tylko jej dojrzalszą wersją. W vibe codingu edytujemy prompty, aż „jakoś zadziała”. W SDD decyzje zapadają wcześniej, a AI tylko zamienia je na kod. Narzędzie to samo, klawiatura ta sama – zmienia się to, kto decyduje.

Nie traktujmy AI jak automatu z gotowymi funkcjami, do którego wrzuca się prompt i czeka, co wypadnie. Traktujmy je jak wykonawcę dobrze opisanego planu. Bardzo szybkiego i bardzo pracowitego wykonawcę, który niestety nie dopyta o nic, jeśli mu tego nie każemy.

Co dalej?

Plan jest prosty: na najbliższym nowym projekcie chcę przejść całą ścieżkę Spec Kit z Claude Code – od konstytucji aż po converge – i sprawdzić, ile z tej teorii obroni się w praktyce. Najbardziej ciekawi mnie, czy czas poświęcony na specyfikację zwróci się w mniejszej liczbie poprawek, czy po prostu przeniosę frustrację z czatu do plików Markdown… Jak coś z tego wyjdzie, opiszę to tu na blogu.

A jeśli chcecie zobaczyć, od czego się zaczęło – wspomniany film trwa dosłownie 7 minut:

Odtwórz film: Spec-Driven Development in 7 Minutes

Może ktoś z Was już pracuje w ten sposób – ze Spec Kit, OpenSpec albo po swojemu, z własnym zestawem dokumentów? Dajcie znać w komentarzach, co się sprawdza, a co okazało się przerostem formy. Chętnie skonfrontuję teorię z Waszą praktyką, zanim sam zabiorę się do testów 🙂