Czym jest Spec-Driven Development? Specyfikacja jako źródło prawdy

Rozwój napędzany specyfikacjami (Spec-Driven Development) to jedna z tych idei, do których programiści sięgali wcześniej, a następnie odkładali na bok, gdy wysiłki przestawały przynosić wymierne korzyści.

W 2025 roku zmieniły się agenci kodowania oparte na AI, którzy uczynili brak wyraźnego zamysłu kosztownym. Prompty są ulotne. Sesje agentów są resetowane. Kod się zmienia, ale rozumowanie stojące za nim znika. Specyfikacja jest artefaktem, który temu zapobiega.

Specyfikacja staje się źródłem prawdy

Przez większość historii rozwoju oprogramowania specyfikacja była要么是 tymczasowym artefaktem planistycznym,要么是 pomyślnym dodatkiem. Wymagania mieszkały w zgłoszeniach (ticketach), decyzje projektowe w wątkach czatu, a kod stanowił podstawową prawdę. Dokumentacja opisywała to, co już istniało, po fakcie.

Rozwój napędzany specyfikacjami odwraca tę relację. Specyfikacja staje się głównym artefaktem. Kod jest tym, co jest generowane lub weryfikowane względem specyfikacji, a nie odwrotnie.

Nie jest to nowy pomysł. Metody formalne, projektowanie umówowe (design-by-contract) oraz BDD zawierają jego wersje. Nowym elementem jest praktyczny motyw: agenci kodowania oparte na AI potrzebują wyraźnego, trwałego kontekstu, aby produkować poprawne i spójne wyniki. Prompty są zbyt ulotne. Specyfikacja jest jedynym artefaktem, który może przenosić zamysł między sesjami agentów, członkami zespołu i w czasie.

Co tak naprawdę oznacza Rozwój Napędzany Specyfikacjami

Rozwój napędzany specyfikacjami, zwykle skracany do SDD, to przepływ pracy, w którym wersjonowana specyfikacja kieruje lub generuje implementację. Specyfikacja jest pisana i przeglądana przed tym, jak agent napisze kod. Zawiera ona:

• Co zbudować – problem użytkownika, cele i elementy wyłączone z zakresu (non-goals)
• Jak wygląda poprawne zachowanie – kryteria akceptacji, przypadki brzegowe, stany błędów
• Jak to zbudować – decyzje architektoniczne, model danych, kontrakty API, ograniczenia bezpieczeństwa
• Jak to zweryfikować – strategia testów, reguły walidacji, śledzenie powiązań z wymaganiami

Specyfikacja nie jest dokumentem jednorazowym. Jest aktualizowana, gdy rzeczywistość różni się od projektu. Gdy agent odkryje coś podczas implementacji, co specyfikacja przedstawiła błędnie, specyfikacja zostaje skorygowana przed kontynuowaniem pracy. Specyfikacja pozostaje „uczciwa”, ponieważ traktuje się ją jak kod.

Ostatnie prace akademickie formalizują to ujęcie: badacze opisują SDD jako traktowanie specyfikacji jako źródła prawdy, a kodu jako generowanego lub weryfikowanego względem nich. Praktyczne znaczenie polega na tym, że specyfikacja jest przeglądaną, trwałą rejestracją zamysłu, którą może przeczytać i zaufać jej zarówno człowiek, jak i narzędzie AI.

Trzy terminy charakteryzują różne punkty na spektrum wykorzystania specyfikacji:

Spec-first (specyfikacja na początku) oznacza pisanie pełnej specyfikacji przed rozpoczęciem jakiejkolwiek implementacji. Jest to najbardziej rygorystyczna interpretacja, najbliższa wodospadowi, jeśli nie jest realizowana ostrożnie.

Spec-anchored (specyfikacja zakotwiczona) oznacza utrzymywanie specyfikacji w synchronizacji z implementacją przez cały cykl życia funkcji. Specyfikacja jest aktualizowana wraz ze zmianą decyzji. Jest to najbardziej praktyczna wersja dla większości zespołów.

Spec-as-source (specyfikacja jako źródło) oznacza generowanie lub walidację implementacji ze specyfikacji, czy to przez agenty AI, czy przez narzędzia sprawdzające kod pod kątem ograniczeń specyfikacji. To jest kierunek, w którym zmierzają narzędzia takie jak GitHub Spec Kit i Kiro.

Dlaczego SDD ma znaczenie teraz

Szczera odpowiedź brzmi, że SDD nie jest atrakcyjny dla samotnego programisty tworzącego skrypt jednodniowy. Nakład pracy tego nie uzasadnia.

SDD staje się wartościowy, gdy występują trzy warunki: funkcja jest na tyle duża, że rozciąga się na wiele sesji, agent musi podejmować decyzje wpływające na architekturę, a praca będzie przeglądana lub kontynuowana przez kogoś innego.

Wszystkie trzy warunki są coraz bardziej powszechne w rozwoju wspomagany AI.

Modele LLM potrzebują kontekstu, nie tylko promptów. Model otrzymujący nieprecyzyjny prompt podejmuje nieprecyzyjne decyzje. Model otrzymujący przejrzaną specyfikację z wyraźnymi ograniczeniami, elementami wyłączonymi z zakresu i kryteriami akceptacji podejmuje lepsze decyzje i jest łatwiejszy do skorygowania, gdy odbiega od celu. Łączy się to z tym, jak działają odzyskiwanie i reprezentacja: dostarczenie agentowi wersjonowanej specyfikacji jest formą strukturalnego odzyskiwania zamysłu projektu.

Generowanie kodu jest tani; decyzja o tym, co zbudować, nadal jest trudna. Butelką w rozwoju wspomagany AI nie jest już pisanie – to wiedza o tym, co zbudować i jak ograniczyć agenta. SDD przenosi wysiłek tam, gdzie ma znaczenie: precyzyjne określenie zamysłu przed rozpoczęciem generowania.

Prompty są ulotne. Agent nie pamięta tego, co mu powiedziano w poprzedniej sesji. Wersjonowana specyfikacja przechowywana w repozytorium pamięta. Każda nowa sesja może przeczytać tę samą specyfikację i zaimplementować ją zgodnie z tym samym zamysłem, bez konieczności budowania kontekstu od zera.

Vibe coding działa, dopóki nie przestaje. W przypadku prototypów i pracy do wyrzucenia, ad-hoc promptowanie jest szybsze i odpowiednie. W momencie, gdy funkcja wymaga ograniczeń bezpieczeństwa, decyzji architektonicznych obejmujących wiele plików lub przekazania pracy zespołowi, brak specyfikacji staje się głównym źródłem odchylenia i defektów. Porównanie znajdziesz w SDD vs Vibe Coding, gdzie omówione jest, kiedy stosować każde podejście.

Podstawowe Artefakty

Praktyczny przepływ pracy SDD produkuje cztery główne artefakty. Każdy z nich redukuje konkretny rodzaj niejednoznaczności, zanim dotrze do agenta.

Specyfikacja wymagań. Statement problemu, użytkownicy, których dotyczy, cele, wyraźnie określone elementy wyłączone z zakresu (non-goals) oraz kryteria akceptacji. Elementy wyłączone z zakresu są tak samo ważne jak cele – informują agenta, czego nie budować, i zapobiegają rozszerzaniu zakresu (scope creep). Kryteria akceptacji są na tyle precyzyjne, że każde z nich mapuje się na co najmniej jeden test.

Specyfikacja projektowa. Decyzje architektoniczne istotne dla tej funkcji: dotknięte moduły, zmiany modelu danych, kontrakty API, migracje, ograniczenia bezpieczeństwa, wymagania dotyczące obserwowalności oraz znane tryby awarii. Nie jest to pełny dokument projektowy systemu – to podzbiór decyzji architektonicznych niezbędnych do poprawnej implementacji tej funkcji.

Plan zadań. Sekwencja małych zadań implementacyjnych, każda z wyraźnymi zależnościami, oczekiwanymi zmianami plików i kryteriami walidacji. Zadania są na tyle małe, że można je zaimplementować w jednej sesji agenta i zweryfikować przy użyciu skupionego diffu. Każde zadanie ma punkt kontrolny przeglądania przez człowieka.

Rejestr śledzenia (Traceability record). Mapowanie z kryteriów akceptacji do testów, z decyzji projektowych do dotkniętych plików oraz z zadań do commitów. To jest to, co odróżnia SDD od dokumentacji, która szybko traci aktualność: śledzenie czyni możliwą weryfikację, że specyfikacja została faktycznie zaimplementowana, a nie tylko napisana.

Te artefakty nie muszą być skomplikowane. Prosta funkcja może wygenerować pojedynczy, dwustronicowy dokument w formacie markdown, obejmujący wszystkie cztery obszary. Format ma mniejsze znaczenie niż nawyk zapisywania zamysłu przed rozpoczęciem implementacji.

Jak SDD różni się od dokumentacji

Najczęstszym nieporozumieniem jest traktowanie artefaktów SDD jako dokumentacji. Nie są to dokumentacja w konwencjonalnym sensie.

Dokumentacja opisuje. Mówi Ci, co system robi, jak go używać i co zawiera. Jest pisana po fakcie i aktualizowana, gdy system się zmienia.

Specyfikacje ograniczają. Specyfikacja mówi agentowi, co mu wolno budować, a czego nie wolno robić. Jest autorytatywna przed rozpoczęciem implementacji. Jest weryfikowana po zakończeniu implementacji. Specyfikacja, która opisuje, co zostało faktycznie zbudowane – zamiast ograniczać to, co powinno zostać zbudowane – już nie spełnia swojego celu.

Specyfikacje wykonywalne kierują generowaniem i walidacją. Najlepsze specyfikacje SDD są na tyle bliskie maszynowo-optymalnym, że agent może je zaimplementować, a zestaw testów zweryfikować. Kryteria akceptacji napisane jako „endpoint musi odrzucać nieautoryzowane żądania odpowiedzią 401” to specyfikacja wykonalna; „endpoint jest bezpieczny” to dokumentacja.

Rejestry Decyzji – ADR-y, PDR-y i DDR-y – są uzupełniające do artefaktów SDD, ale służą innemu celowi. Rejestry decyzji przechwytują, dlaczego dokonano wyboru i co odrzucono. Specyfikacje SDD przechwytują, co zbudować i jak to zweryfikować. Oba należą do repozytorium. Razem dają agentom AI pełny obraz: bieżący zamysł i rozumowanie stojące za nim.

Jak SDD różni się od TDD

Rozwój Napędzany Testami (TDD) i Rozwój Napędzany Specyfikacjami są często mylone, ponieważ oba produkują wyraźne artefakty przed istnieniem kodu. Różnica polega na punkcie wyjścia.

TDD zaczyna się od testów. Piszesz test, który ma się nie powieść (failing test), opisujący zachowanie, którego chcesz, a następnie piszesz minimalny kod, aby go zaliczyć. TDD to pętla zwrotna na poziomie jednostkowym. Produkuje dobre testy, ale nie odpowiada na pytanie, czy budujesz właściwą rzecz.

SDD zaczyna się od zamysłu. Przed istnieniem testów, przed podjęciem decyzji o architekturze, specyfikacja odpowiada: kto ma ten problem, jak wygląda poprawne zachowanie, co jest wyraźnie poza zakresem. Specyfikacja następnie informuje, jakie testy napisać, dlatego dobry SDD i dobry TDD są uzupełniające, a nie rywalizujące.

Praktyczny sposób myślenia o tym: SDD napędza TDD. Kryteria akceptacji w specyfikacji stają się scenariuszami testowymi. Specyfikacja projektowa identyfikuje granice integracji, które wymagają testów kontraktowych. Plan zadań identyfikuje, które zachowania jednostkowe wymagają pokrycia testowego przed ich implementacją przez agenta.

Jak SDD różni się od BDD

Rozwój Napędzany Zachowaniem (BDD) wykorzystuje scenariusze w języku naturalnym – typowo w formacie Gherkin – do opisywania oczekiwanego zachowania z perspektywy użytkownika. Te scenariusze mostkują lukę między zamysłem biznesowym a implementacją techniczną.

SDD jest szerszy. Obejmuje opisy zachowań (które mogą używać języka w stylu BDD lub zwykłego prozy), ale również obejmuje decyzje architektoniczne, modele danych, ograniczenia bezpieczeństwa, planowanie zadań i śledzenie. BDD może być przydatnym formatem do pisania kryteriów akceptacji wewnątrz specyfikacji wymagań SDD. Specyfikacja jest kontenerem; scenariusze BDD to jeden ze sposobów pisania tego, co wchodzi do środka.

Różnica ta ma znaczenie w praktyce: narzędzia BDD skupiają się na czynieniu scenariuszy wykonywalnymi. Praktyka SDD skupia się na czynieniu zamysłu trwałym – przez narzędzia, przez sesje i przez członków zespołu.

Jak SDD różni się od Metod Formalnych

Metody formalne wykorzystują notację matematyczną i automatyczną weryfikację do dowodzenia własności systemów oprogramowania. Są niezwykle rygorystyczne i niezwykle kosztowne w większości kontekstów produkcyjnego rozwoju.

SDD nie wymaga notacji formalnej. Plik markdown z kryteriami akceptacji i decyzjami architektonicznymi jest specyfikacją. Ogranicza on bez bycia matematycznie formalnym. Poziom rygoru skaluje się z zakładami: specyfikacja dla usługi rozliczeń powinna być bardziej precyzyjna i bardziej starannie przeglądana niż specyfikacja dla strony dokumentacji.

Relacja jest spektrum:

• Nieformalna specyfikacja prozą (minimalny wykonalny SDD)
• Strukturalny markdown z kryteriami akceptacji i elementami wyłączonymi z zakresu
• Maszynowo-optymalna specyfikacja z walidacją schematu
• Testy kontraktowe wyprowadzone bezpośrednio ze specyfikacji
• Specyfikacja formalna z automatycznym dowodem

Większość zespołów działa w środku tego spektrum. Celem nie jest rygor matematyczny – to czynienie zamysłu na tyle wyraźnym, że agent AI może go zaimplementować, a recenzent człowiek zweryfikować wynik.

Korzyści z Rozwoju Napędzanego Specyfikacjami

Mniejsze odchylenie zamysłu. Specyfikacja jest odniesieniem. Gdy agent odbiega – a odbędzie – recenzent ma coś, z czym może porównać implementację. Bez specyfikacji odchylenie jest niewidoczne, dopóki coś się nie zepsuje.

Lepsze wyniki AI. Agenci otrzymujący wyraźne ograniczenia, elementy wyłączone z zakresu i kryteria akceptacji produkują implementacje bliższe temu, co zamierzono, i łatwiejsze do skorygowania, gdy pominą. Jakość kontekstu bezpośrednio determinuje jakość wyników.

Łatwiejszy przegląd. Pull request powiązany ze specyfikacją jest łatwiejszy do przeglądania niż pull request, który wymaga od recenzenta odtworzenia zamysłu z kodu. Specyfikacja jest listą kontrolną przeglądu.

Zrównoważenie zespołu. Gdy wiele osób lub agentów pracuje nad tą samą funkcją, specyfikacja jest wspólnym kontraktem. Bez niej każdy współtwórca optymalizuje lokalnie, a części mogą się nie zgadzać.

Lepsze planowanie testów. Kryteria akceptacji w specyfikacji mapują się bezpośrednio na przypadki testowe. Pokrycie testowe staje się pytaniem o pokrycie specyfikacji: czy każde kryterium akceptacji jest pokryte przez co najmniej jeden test?

Trwała transmisja. Gdy funkcja zmienia ręce – między inżynierami, między sesjami agentów, między sprintami – specyfikacja jest artefaktem transmisji. Przechwytuje, co zostało postanowione, co było poza zakresem i co pozostaje do zweryfikowania.

Koszty Rozwoju Napędzanego Specyfikacjami

Wysiłek wstępny. Pisanie dobrej specyfikacji przed napisaniem jakiegokolwiek kodu zajmuje czas. Dla małych funkcji ten nakład jest realny i czasami nie warto go ponosić.

Fałszywe poczucie pewności. Specyfikacja, która istnieje, ale nie jest weryfikowana względem implementacji, daje fałszywe poczucie poprawności. Nieaktualne specyfikacje są czasem gorsze niż brak specyfikacji: mylą recenzentów i agentów, którzy je czytają.

Nieaktualne specyfikacje. Specyfikacje odbiegają, gdy zespół traktuje je jako artefakty planistyczne, a nie żywe dokumenty. Aktualizacja specyfikacji, gdy implementacja różni się od projektu, nie jest opcjonalna – to jest to, co odróżnia SDD od dokumentacji, która gromadzi się i gnije.

Generowana biurokracja. Agenci AI mogą szybko generować wyczerpujące listy zadań i rozwlekłe specyfikacje. Specyfikacja 200 zadań wygenerowana w trzydzieści sekund nie jest przydatną specyfikacją – to generator biurokracji. Dobry SDD wymaga osądu co do tego, co specyfikować, a co zostawić implikowane.

Zależność od narzędzi. Niektóre narzędzia SDD są zdeterminowane co do formatu, struktury plików i przepływu pracy. Specyfikacja napisana w własnościowym formacie jest trudniejsza do przeniesienia między narzędziami niż plik markdown z jasnymi nagłówkami i kryteriami akceptacji.

Podsumowanie

Rozwój Napędzany Specyfikacjami nie jest nową metodologią. To stara dyscyplina, która staje się ponownie praktyczna, ponieważ koszt niejawnej intencji jest teraz widoczny w kodzie generowanym przez AI.

Dyscyplina jest prosta: zapisz, co zamierzasz zbudować, przeglądane i wersjonowane, przed tym, jak agent to zbuduje. Utrzymuj tę rejestrację uczciwą, aktualizując ją, gdy rzeczywistość się różni. Używaj jej jako odniesienia do przeglądu, testowania i transmisji.

Specyfikacja nie jest magiczna. Specyfikacja, która nie jest weryfikowana, staje się najdrodzą postacią dokumentacji: taką, która myli z pewnością siebie. Dobry SDD to praktyka utrzymywania specyfikacji uczciwych – na tyle małych, by można je utrzymać, na tyle precyzyjnych, by ograniczać, i na tyle trwałych, by przetrwać każdą pojedynczą sesję agenta.

SDD znajduje się na skrzyżowaniu praktyki dokumentacji, architektury testów i projektowania kodu – wszystko to omówione w klastrze Architektura Aplikacji w Produkcji obok rejestrów decyzji, projektowania API i wzorców dostępu do danych.

Przydatne Linki

• Rejestry Decyzji dla Rozwoju Oprogramowania Napędzanego AI – ADR-y, PDR-y i DDR-y, które uzupełniają specyfikacje SDD, przechwytując, dlaczego podejmowano decyzje
• Rozwój Napędzany Specyfikacjami vs Vibe Coding: Wodospad? – kiedy dodawać specyfikacje, a kiedy swobodnie promptować
• Czym jest Vibe Coding – Znaczenie, Narzędzia, Korzyści i Ryzyka – filar klastra vibe coding
• Architektura Aplikacji w Produkcji – dom dla klastra architektury, dokumentacji, testowania i wzorców integracji
• Testowanie Jednostkowe w Go: Struktura i Najlepsze Praktyki – przekształcanie kryteriów akceptacji SDD w testy wykonywalne
• Testowanie Jednostkowe w Pythonie: Kompletny Przewodnik – praktyki pisania testów mapujące się na kryteria akceptacji SDD
• Wzorce Projektowe Pythona dla Czystej Architektury – praktyki struktury kodu, które SDD pomaga zachować
• Odzyskiwanie vs Reprezentacja w Zarządzaniu Wiedzą – jak wyraźne specyfikacje odnoszą się do kontekstu AI i odzyskiwania
• Dokumentacja GitHub Spec Kit – przenośny, open-source’owy zestaw narzędzi SDD
• Martin Fowler o Narzędziach Rozwoju Napędzanego Specyfikacjami – ostrożna analiza Kiro, Spec Kit i Tessl