Spec-Driven Development: koniec vibe codingu? Jak specyfikacje zmieniają pracę z AI

Problem vibe codingu: kod, który wygląda dobrze, ale rozwiązuje inny problem

Znasz ten scenariusz. Opisujesz agentowi AI funkcję, którą chcesz dodać. Dostajesz kilkaset linii kodu, który się kompiluje, przechodzi lintera i na pierwszy rzut oka wygląda profesjonalnie. Po godzinie okazuje się, że rozwiązuje trochę inny problem niż ten, który miałeś w głowie.

Przy prototypie kosztuje to pół dnia. Przy systemie produkcyjnym, w którym kilka zespołów dowozi równolegle, taki rozjazd zamienia się w tygodnie przepisywania i cichy dług techniczny, który ujawnia się dopiero przy kolejnej zmianie.

Problem nie leży w możliwościach modelu. Leży w tym, jak z niego korzystamy. Traktujemy agentów jak wyszukiwarki, którym wystarczy rzucić hasło — a to dosłowni pair programmerzy: wykonują to, co napisaliśmy, nie to, co mieliśmy na myśli. Spec-Driven Development (SDD) jest próbą zamknięcia tej luki.

Czym jest Spec-Driven Development?

Spec-Driven Development to podejście, w którym zespół najpierw definiuje co i dlaczego buduje — zachowanie systemu, ograniczenia, interfejsy i kryteria akceptacji — a dopiero potem powstaje implementacja. Specyfikacja przestaje być dokumentem pomocniczym i staje się źródłem prawdy, zarówno dla ludzi, jak i dla agentów AI.

Kluczowe jest odwrócenie kolejności. Tradycyjnie źródłem prawdy jest kod, a dokumentacja starzeje się w folderze, którego nikt nie otwiera. W SDD specyfikacja jest żywym artefaktem: zmienia się wymaganie, aktualizujesz spec, a implementacja podąża za nim. To, mówiąc krótko, version control dla twojego myślenia.

Czym SDD nie jest

Warto rozbroić trzy obiekcje od razu. SDD nie jest pisaniem opasłych dokumentów, których nikt nie czyta — dobra specyfikacja funkcji to zwykle dwie strony. Nie jest waterfallem, bo cykl domyka się na poziomie pojedynczej funkcji, nie całego projektu. I nie jest biurokracją, bo każdy artefakt ma konkretnego odbiorcę: człowieka, który robi review, albo agenta, który pisze kod.

Najlepiej widać to na przykładzie, który krąży po branży w różnych wariantach. Zespół buduje system powiadomień. Product manager rozumie „preferencje użytkownika" jako osobne przełączniki dla e-maila, push i SMS-a. Backend implementuje jeden przełącznik on/off. Frontend zakłada, że preferencje przyjdą z systemu operacyjnego. Nikt nie zawinił — zabrakło wspólnego kontekstu. Specyfikacja wyciąga takie założenia na wierzch wtedy, gdy ich uzgodnienie kosztuje kilka zdań, a nie dwa sprinty.

Trzy poziomy SDD — to spektrum, nie jedna metoda

Spora część zamieszania wokół SDD wynika z tego, że pod jedną nazwą kryją się trzy różne poziomy ambicji. Porządkuje je podział opisany przez Birgittę Böckeler na blogu Martina Fowlera:

• Spec-first — dopracowana specyfikacja powstaje przed rozpoczęciem pracy i prowadzi agenta przez konkretne zadanie. Najlżejszy wariant i najłatwiejszy start.
• Spec-anchored — specyfikacja żyje po zakończeniu zadania i służy jako aktualna dokumentacja przy rozwoju oraz utrzymaniu funkcji.
• Spec-as-source — specyfikacja staje się głównym artefaktem, a deweloper edytuje tylko ją. Cały kod generuje AI; narzędzia w rodzaju Tessl oznaczają go ostrzeżeniem „DO NOT EDIT".

Różne narzędzia celują w różne punkty tego spektrum — stąd rozbieżne obietnice. Dla większości zespołów realistyczny start to spec-first albo spec-anchored. Spec-as-source jest na dziś eksperymentem: ciekawym, ale ryzykownym na produkcji.

Dlaczego SDD pojawia się właśnie teraz? Cztery ograniczenia agentów AI

Pisanie specyfikacji przed kodem nie jest nowym pomysłem. Nowe jest to, że ma teraz konkretnego adresata. Analiza EPAM porządkuje cztery ograniczenia agentów, które specyfikacja realnie adresuje.

1. Zakres i długość zadania

Modele językowe utrzymują jakość przy zmianach obejmujących jeden do trzech plików. Przy dziesięciu i więcej spójność zaczyna się sypać: pojawiają się rozjechane nazwy, zduplikowana logika, pominięte miejsca integracji. SDD wymusza dekompozycję — funkcja rozpada się na historie użytkownika, a te na atomowe zadania obejmujące jeden, dwa pliki.

2. Brak kontekstu funkcji

Agent nie zna wymagań biznesowych, przypadków brzegowych ani kryteriów akceptacji. Prompt jest ulotny i ginie wraz z sesją. Warstwa specyfikacji i projektu systemu zostaje w repozytorium — można się do niej odwołać za trzy miesiące, przy kolejnej zmianie w tej samej funkcji.

3. Brak wiedzy o projekcie

Czytanie repozytorium nie jest tym samym co rozumienie go. Agent nie wie, które biblioteki są zaakceptowane, jakie wzorce zostały świadomie porzucone i jakie są wymogi bezpieczeństwa. Co gorsza, stare pliki uczą go złych wzorców. Odpowiedzią jest constitution — spisany dla AI odpowiednik onboardingu seniora w pierwszym dniu pracy: stack z wersjami, konwencje nazewnicze, decyzje architektoniczne, lista dozwolonych i zakazanych zależności, wymogi bezpieczeństwa.

4. Niekontrolowana autonomia

Agent potrafi zwrócić zmianę w piętnastu plikach bez śladu decyzji, które do niej doprowadziły. W środku jest mieszanka dobrego kodu i cichych błędów, a review takiej paczki to loteria. SDD wstawia bramki: najpierw review specyfikacji, potem planu, a zgoda na implementację jest osobnym krokiem.

Jak wygląda workflow SDD w praktyce

Najpopularniejszą implementacją tego wzorca jest GitHub Spec Kit. Workflow ma sześć etapów:

1. Constitution — spisujesz zasady projektu, które obowiązują we wszystkich zadaniach.
2. Specify — opisujesz funkcję: zachowanie, ograniczenia, kryteria akceptacji. Bez decyzji technicznych.
3. Clarify — agent zadaje pytania o luki i sprzeczności; tu wychodzą niewypowiedziane założenia.
4. Plan — powstaje projekt techniczny: moduły, kontrakty, kolejność zmian.
5. Tasks — plan rozpada się na atomowe zadania, każde w zasięgu jednego przebiegu agenta.
6. Implement — agent wykonuje zadania, a ty robisz review przyrostów, nie całości.

Technicznie Spec Kit to narzędzie wiersza poleceń, zestaw szablonów i komendy wywoływane w agencie. Działa z Copilotem, Claude Code, Cursorem i innymi. Artefakty to zwykłe pliki Markdown w repozytorium, więc wersjonujesz je i review'ujesz jak kod.

Praktyczna uwaga z naszych projektów: jakość pierwszego opisu funkcji decyduje o jakości całości. Im więcej napiszesz o wymaganiach i anty-wymaganiach — czyli o tym, czego świadomie nie robimy — tym mniej poprawek później.

Krajobraz narzędzi: natywne kontra doklejone

Cała branża konwerguje do jednego wzorca: intencja, specyfikacja, plan, wykonanie. Różnica jest w tym, jak głęboko narzędzie go wspiera.

Natywnie: GitHub Spec Kit z Copilotem, gdzie komendy są funkcją pierwszej klasy; Kiro od AWS, czyli IDE zaprojektowane od zera pod specyfikacje; oraz Tessl z najambitniejszą wizją spec-as-source.

Doklejone, ale pokrewne: Cursor Plan Mode generuje plan przed wykonaniem — filozoficznie podobnie, technicznie inaczej. Windsurf stawia na agenta Cascade i trwały kontekst bez formalnych specyfikacji. Podobnie tryby planowania w Claude Code, Gemini CLI i Amazon Q Developer. Spec Kit da się z nimi używać przez integracje społeczności, ale bez formalnych bramek weryfikacji. Po stronie open source warto znać lżejsze OpenSpec i BMAD.

Wniosek jest prosty: wzorzec jest przenośny. Na start wystarczą zwykłe pliki Markdown w repozytorium, a wybór narzędzia to kwestia stacku, w którym już pracujesz.

Co SDD robi dobrze

Wydłuża okno bezpiecznej delegacji. Bez struktury sensownie delegujesz agentowi zadania na dziesięć, dwadzieścia minut. Ze specyfikacją i planem to okno rośnie do wielogodzinnych funkcji przy porównywalnej jakości.

Przesuwa pracę w lewo. Więcej myślenia na etapie projektowania, mniej sprzątania po implementacji. To najprostsza znana nam dźwignia na dług techniczny: najtańszy dług to ten, którego nie zaciągnąłeś.

Zmienia rolę dewelopera. Od pisania kodu w stronę projektowania systemów i walidacji. Code review skupia się na architekturze i zgodności ze specyfikacją, nie na literówkach i stylu.

Robi ze specyfikacji artefakt pierwszej klasy. Wersjonowany, testowalny, walidowany w CI/CD. Dokumentacja przestaje się rozjeżdżać z kodem, bo jest wejściem do procesu, nie jego produktem ubocznym.

Jest też korzyść, którą najmocniej widzą klienci software house'u: dobra specyfikacja to przewidywalna wycena. Gdy zakres jest spisany i uzgodniony przed startem, maleje liczba niespodzianek po obu stronach — dlatego etap ideacji i odkrywania traktujemy jako osobną fazę projektu, nie formalność przed podpisaniem umowy.

Gdzie SDD zawodzi — uczciwa lista ograniczeń

Materiały producentów narzędzi są promocyjne, a krytyka na forach jednostronna. Prawda jest mniej wygodna: SDD ma kilka realnych słabości i warto je znać przed wdrożeniem.

Napięcie z Agile

Agile nauczył nas przyjmować zmianę i cenić działające oprogramowanie ponad rozbudowaną dokumentację. SDD każe napisać szczegółowe wymagania przed pierwszą linijką kodu. Kontrargument jest sensowny: nowoczesne SDD zakłada iteracyjne specyfikacje, więc aktualizujesz spec i regenerujesz implementację jako lekki proces zmiany. Ale otwarte pytania zostają — jak pogodzić szczegółowość z tempem iteracji i czy specyfikacja nie stanie się kolejną dokumentacją, która rozjeżdża się z kodem.

Ściany markdownu

Dzisiejsze narzędzia generują mnóstwo rozwlekłych, powtarzalnych dokumentów do review. Paradoksalnie często łatwiej przejrzeć sam kod niż przebrnąć przez kilka ekranów specyfikacji. Wniosek praktyczny: specyfikacja ma być tak lekka, jak to możliwe przy zachowaniu jednoznaczności. Jeśli nikt jej nie czyta, nie jest źródłem prawdy — jest teatrem.

Fałszywe poczucie kontroli

Mimo szczegółowych specyfikacji, szablonów i checklist agenci wciąż potrafią zignorować instrukcję albo błędnie zinterpretować kontekst. Duże okno kontekstowe nie gwarantuje, że model z niego skorzysta. Specyfikacja zmniejsza ryzyko, nie eliminuje go — i to rozróżnienie jest ważne, gdy ktoś planuje budżet na review.

Niedopasowanie do skali problemu

Pełny proces SDD przy drobnym bugfiksie to strzelanie z armaty do wróbla. Nawet przy średnich funkcjach narzut bywa odczuwalny. Branża nie ma dobrej odpowiedzi na pytanie, od jakiej wielkości zadania SDD realnie się opłaca — na razie to kwestia wyczucia zespołu.

Lekcja z historii: Model-Driven Development

Na początku lat dwutysięcznych MDD obiecywało dokładnie to samo: modele wysokopoziomowe, automatyczna generacja kodu, skupienie na intencji zamiast na składni. W aplikacjach biznesowych poległo — złe poziomy abstrakcji, narzut narzędziowy, sztywność. Modele językowe usuwają część tych przeszkód, bo nie trzeba parsowalnych języków dziedzinowych ani własnych generatorów. Ale tracimy też to, co MDD robiło dobrze: walidację i spójność strukturalnych, maszynowo czytelnych specyfikacji. Pytanie, które warto sobie zadać przed wdrożeniem: czy nie bierzemy wad obu światów — sztywności MDD i niedeterminizmu modeli językowych?

Rozmycie terminu

Słowo „spec" bywa już używane jako synonim „szczegółowego promptu". Bez precyzyjnych definicji SDD grozi los kolejnego buzzwordu, który znaczy wszystko i nic. Dlatego w tym artykule definicje i spektrum trzech poziomów są na początku, a nie na końcu.

Realistyczne oczekiwania

Trzy rzeczy, o których producenci narzędzi mówią najciszej. Napisanie sensownej konstytucji projektu to praca doświadczonego inżyniera i wiele iteracji — junior nie zrobi tego w jeden dzień. Sześćdziesiąt do osiemdziesięciu procent wygenerowanego kodu użytecznego po review to już sukces; resztę trzeba doszlifować, zwykle w przypadkach brzegowych i integracjach. A same narzędzia są młode: Spec Kit to wciąż wczesne wersje, więc formaty i workflow będą się zmieniać.

Wartość SDD leży w strukturze i wymuszonej jasności, nie w magii. Dwie osoby z tym samym procesem osiągną skrajnie różne wyniki, a różnicą będzie inżynierska ocena sytuacji.

Dla kogo SDD ma sens, a dla kogo jeszcze nie

Ma sens w zespołach pracujących już z agentami, w projektach enterprise i brownfield z wymogami compliance, w organizacjach z wieloma serwisami i API oraz w zespołach platformowych, które budują wspólne kontrakty dla innych.

Nie ma sensu — jeszcze — w projektach jednoosobowych i szybkich prototypach; tam vibe coding wystarcza i jest szybszy. Nie ma też sensu w zespołach bez ustalonych konwencji: nie da się spisać konstytucji projektu, w którym nie ma zgody, jak nazywa się pliki. Najpierw standardy, potem SDD.

Czyja to w ogóle praca?

Tutoriale SDD każą definiować cele produktowe i historie użytkownika, co otwiera niewygodne pytanie: czy to zadanie dewelopera, czy product managera? W praktyce to styk obu rol i dlatego SDD bywa trudne organizacyjnie, a nie technicznie. Dla software house'u jest to akurat szansa — właśnie na styku produktu i inżynierii powstaje większość wartości.

Jak podchodzimy do tego w Midapt

Nie wdrażamy SDD jako metodyki z certyfikatem. Bierzemy z niego trzy rzeczy, które sprawdzają się w projektach klienckich. Specyfikację i plan piszemy przed implementacją w projektach MVP, bo tam najszybciej zwraca się uniknięcie przepisywania. Konstytucję traktujemy jako kodyfikację standardów zespołu: powstaje raz, a służy każdemu zadaniu i każdemu agentowi. Review prowadzimy dwustopniowo — najpierw zgodność ze specyfikacją, potem szczegóły implementacji.

[Do uzupełnienia przez zespół: jeden konkretny przykład z projektu, choćby anonimowy, z liczbą w rodzaju „X% mniej poprawek po review".]

Podsumowanie: pragmatyzm ponad dogmat

SDD nie jest ani srebrną kulą, ani modą bez treści. Jest zestawem nawyków, które dobrze się starzeją. Pięć zasad, z którymi warto do niego podejść:

1. Myślenie spec-first stosuj do pracy złożonej i krytycznej produkcyjnie, nie do wszystkiego.
2. Utrzymuj specyfikacje tak lekkie, jak to możliwe przy zachowaniu jasności.
3. Zostań iteracyjny — małe, review'owalne zmiany zamiast wielkiego projektu z góry.
4. Traktuj specyfikacje jak narzędzie, nie religię.
5. Ucz się z historii Model-Driven Development, zamiast ją powtarzać.

Rewolucja AI w wytwarzaniu oprogramowania jest prawdziwa. Ale rewolucja nie oznacza porzucenia wszystkiego, czego nauczyła nas inżynieria oprogramowania — oznacza stosowanie tych lekcji z nowymi narzędziami.

Zastanawiasz się, jak bezpiecznie wprowadzić agentów AI do swojego procesu wytwarzania oprogramowania? Porozmawiajmy o twoim przypadku.