Czym jest rozwój oparty na specyfikacji? Specyfikacja jako źródło prawdy

Specyfikacja jako źródło prawdy, a nie dokument dodatkowy.

Page content

Rozwój napędzany specyfikacjami to jedna z tych idei, do których inżynierowie oprogramowania sięgają, a następnie odkładają na bok, gdy wysiłki przestają przynosić wymierne korzyści.

W 2025 roku zmieniło się to, że pojawiły się agenty kodujące oparte na sztucznej inteligencji i sprawiły, że brak jawnej intencji stał się kosztowny. Prompty są efemeryczne. Sesje agentów są resetowane. Kod się zmienia, ale uzasadnienie stojące za nim znika. Specyfikacja jest artefaktem, który zapobiega temu zjawisku.

Czym jest Spec-Driven Development – specyfikacja jako źródło prawdy dla AI kodującej

Specyfikacja staje się źródłem prawdy

Przez większość historii rozwoju oprogramowania specyfikacja była albo tymczasowym artefaktem planistycznym, albo elementem dodawanym ex post. Wymagania mieszkały w zgłoszeniach (ticketach), decyzje projektowe w wątkach czatu, a kod był jedynym źródłem prawdy. Dokumentacja opisywała to, co już istnieje, po fakcie.

Rozwój napędzany specyfikacjami odwraca tę relację. Specyfikacja staje się głównym artefaktem. Kod jest generowany lub weryfikowany względem specyfikacji, a nie na odwrót.

Nie jest to nowy pomysł. Metody formalne, projektowanie oparte na umowie (design-by-contract) oraz BDD (Behavior-Driven Development) zawierały jego wersje. Nowym elementem jest praktyczne uzasadnienie: agenty kodujące oparte na AI potrzebują jawnego, trwałego kontekstu, aby produkować poprawne i spójne wyniki. Prompty są zbyt efemeryczne. Specyfikacja jest jedynym artefaktem, który może przenosić intencję między sesjami agenta, członkami zespołu oraz w czasie.

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

Rozwój napędzany specyfikacjami, zwykle skracany do SDD (Spec-Driven Development), to przepływ pracy, w którym wersjonowana specyfikacja kieruje implementacją lub ją generuje. Specyfikacja jest pisana i recenzowana przed tym, jak agent napisze kod. Ona zawiera:

  • Co zbudować – problem użytkownika, cele oraz rzeczy, które nie są celem (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

Ten ostatni punkt jest łatwy do zapisania, ale łatwy do pominęcia w praktyce. Utrzymywanie spójności specyfikacji, testów i kodu w rozwoju z AI omawia, jak wygląda śledzenie powiązań z wymaganiami w danych: identyfikatory wymagań, identyfikatory decyzji projektowych oraz testy połączone z pull requestami, które je zaimplementowały.

Specyfikacja nie jest dokumentem jednorazowym. Jest aktualizowana, gdy rzeczywistość różni się od projektu. Gdy agent podczas implementacji odkryje coś, co specyfikacja opisuje błędnie, specyfikacja jest poprawiana przed kontynuowaniem pracy. Specyfikacja pozostaje wiarygodna, ponieważ jest traktowana jak kod.

Ostatnie prace akademickie formalizują to ujęcie: badacze opisują SDD jako traktowanie specyfikacji jako źródła prawdy, a kodu jako czegoś generowanego lub weryfikowanego względem nich. Praktyczne znaczenie polega na tym, że specyfikacja jest recenzowanym, trwałym zapisem intencji, który może odczytać i zaufać każda osoba lub narzędzie AI.

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

Spec-first oznacza napisanie pełnej specyfikacji przed rozpoczęciem jakiejkolwiek implementacji. Jest to najścisze interpretacja i ta najbliższa modelowi kaskadowemu (waterfall), jeśli nie zostanie wykonana ostrożnie.

Spec-anchored oznacza utrzymanie specyfikacji w synchronizacji z implementacją przez cały cykl życia funkcji. Specyfikacja jest aktualizowana w miarę zmiany decyzji. Jest to najbardziej praktyczna wersja dla większości zespołów.

Spec-as-source oznacza generowanie lub walidację implementacji z specyfikacji, zarówno przez agentów AI, jak i przez narzędzia sprawdzające kod względem ograniczeń specyfikacji. To jest kierunek, w którym zmierzają narzędzia takie jak GitHub Spec Kit i Kiro, każde z innym kompromisem między przenośnością a zintegrowaną przewodnictwem w IDE.

Dlaczego SDD ma znaczenie teraz

Szczera odpowiedź brzmi, że SDD nie jest atrakcyjna dla samodzielnego dewelopera budującego skrypt jednodniowy. Nakład pracy tego nie warto.

SDD staje się wartościowa, gdy obecne są trzy warunki: funkcja jest na tyle duża, że obejmuje wiele sesji, agent musi podejmować decyzje wpływające na architekturę, a praca będzie recenzowana lub kontynuowana przez kogoś innego.

Wszystkie trzy warunki stają się coraz powszechniejsze w rozwoju wspieranym przez AI.

LLM-y potrzebują kontekstu, nie tylko promptów. Model otrzymujący niejasny prompt podejmuje niejasne decyzje. Model otrzymujący recenzowaną specyfikację z jawnymi ograniczeniami, rzeczami wykluczonymi z zakresu (non-goals) i kryteriami akceptacji podejmuje lepsze decyzje i łatwiej jest skorygować jego kurs, gdy odbiega on od celu. Łączy się to z tym, jak działają odzyskiwanie i reprezentacja: dostarczenie agentowi wersjonowanej specyfikacji jest formą strukturalnego odzyskiwania intencji projektu.

Generowanie kodu jest tanie; decydowanie, co zbudować, nadal jest trudne. Butelką w rozwoju wspieranym przez AI nie jest już pisanie klawiaturą – to wiedza, co zbudować i jak ograniczyć agenta. SDD przenosi wysiłek tam, gdzie ma znaczenie: jasne określanie intencji przed rozpoczęciem generowania.

Prompty są efemeryczne. Agent nie pamięta tego, co mu powiedziano w ostatniej sesji. Wersjonowana specyfikacja przechowywana w repozytorium pamięta. Każda nowa sesja może odczytać tę samą specyfikację i zaimplementować ją względem tej samej intencji, bez konieczności przywracania kontekstu od zera.

**Vibe coding jest szybszy przy pracy jednorazowej; SDD vs Vibe Coding omawia, kiedy dodać specyfikacje, a kiedy swobodnie korzystać z promptów.

Główne Artefakty

SDD produkuje cztery typy artefaktów. Każdy redukuje inną formę niejasności, zanim agent dotknie kodu:

  • Specyfikacja wymagań – problem, użytkownicy, cele, rzeczy wykluczone z zakresu, kryteria akceptacji
  • Specyfikacja projektowa – architektura, model danych, kontrakty API, ograniczenia bezpieczeństwa dla tej funkcji
  • Plan zadań – małe części implementacji z zależnościami i kryteriami walidacji
  • Rejestr śledzenia – mapowanie kryteriów akceptacji do testów, decyzji projektowych do plików, zadań do commitów

Jak je produkować i recenzować krok po kroku – specyfikować, planować, zadania, implementować, walidować – jest omówione w Przepływie pracy Spec-Driven Development od wymagań do kodu. Prosta funkcja może objąć wszystkie cztery obszary w krótkim pliku markdown. Nawyk ma większe znaczenie niż format.

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 zbudować, a co nie. Jest autorytatywna przed rozpoczęciem implementacji. Jest weryfikowana po zakończeniu implementacji. Specyfikacja, która opisuje to, co faktycznie zostało zbudowane – zamiast ograniczać to, co powinno być zbudowane – już spełniła swoją rolę negatywnie (zawiodła).

Specyfikacje wykonywalne kierują generowaniem i walidacją. Najlepsze specyfikacje SDD są wystarczająco bliskie maszynowo odczytelnym, aby agent mógł implementować na ich podstawie, a zestaw testów mógł je weryfikować. Kryteria akceptacji napisane jako „endpoint musi odrzucać nieuwierzytelnione żądania odpowiedzią 401” to specyfikacja wykonywalna; „endpoint jest bezpieczny” to dokumentacja.

Rejestry Decyzji(https://www.glukhov.org/pl/app-architecture/documentation/decision-records-ai-driven-development/ “Rejestry Decyzji dla Oprogramowania Napędzanego przez AI”) – ADR-y, PDR-y i DDR-y – są uzupełniające dla artefaktów SDD, ale służą innemu celowi. Rejestry decyzji przechwytują, dlaczego podjęto wybór i co odrzucono. Specyfikacje SDD przechwytują, co zbudować i jak to zweryfikować. Oboje należą do repozytorium. Razem dają agentom AI pełny obraz: bieżącą intencję i uzasadnienie za nią.

Jak SDD różni się od TDD

Rozwój Napędzany Testami (Test-Driven Development) i Rozwój Napędzany Specyfikacjami są często mylone, ponieważ oba produkują jawnie artefakty przed istnieniem kodu. Różnica polega na punkcie wyjścia.

TDD zaczyna się od testów. Piszesz test, który się nie powiedzie (failing test), opisujący pożądane zachowanie, a następnie piszesz minimalny kod, aby go przejść. 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 intencji. Przed istnieniem testów, przed podjęciem decyzji architektonicznych, specyfikacja odpowiada: kto ma ten problem, jak wygląda poprawne zachowanie, co jest wyraźnie poza zakresem. Specyfikacja informuje następnie, 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 potrzebują testów kontraktowych. Plan zadań identyfikuje, które zachowania jednostkowe potrzebują pokrycia testowego, zanim agent je zaimplementuje.

Jak SDD różni się od BDD

Rozwój Napędzany Zachowaniem (Behavior-Driven Development) używa scenariuszy w języku naturalnym – typowo w formacie Gherkin – do opisu oczekiwanego zachowania z perspektywy użytkownika. Te scenariusze mostkują lukę między intencją biznesową a implementacją techniczną.

SDD jest szersza. Zawiera opisy zachowań (które mogą używać języka stylu BDD lub zwykłego prozy), ale obejmuje również decyzje architektoniczne, modele danych, ograniczenia bezpieczeństwa, planowanie zadań i śledzenie powiązań. BDD może być użytecznym 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 w jej skład.

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

Jak SDD różni się od Metod Formalnych

Metody formalne używają notacji matematycznej i automatycznej weryfikacji do dowodzenia własności systemów oprogramowania. Są niezwykle rygorystyczne i niezwykle kosztowne w większości kontekstów produkcyjnych.

SDD nie wymaga notacji formalnej. Plik markdown z kryteriami akceptacji i decyzjami architektonicznymi jest specyfikacją. Ogranicza, nie będąc matematycznie formalnym. Poziom rygoru skaluje się z ryzykiem: specyfikacja dla usługi rozliczeniowej powinna być bardziej precyzyjna i ostrożniej recenzowana niż specyfikacja dla strony dokumentacji.

Relacja jest spektrum:

  • Nieformalna specyfikacja prozą (minimum viable SDD)
  • Strukturalny markdown z kryteriami akceptacji i rzeczami wykluczonymi z zakresu
  • Specyfikacja maszynowo odczytelnowa z walidacją schematu
  • Testy kontraktowe wyprowadzone bezpośrednio ze specyfikacji
  • Specyfikacja formalna z automatycznym dowodem

Większość zespołów operuje w środku tego spektrum. Celem nie jest rygor matematyczny – jest to uczynienie intencji wystarczająco jawną, aby agent AI mógł implementować na jej podstawie, a recenzent ludzki mógł zweryfikować wynik.

Korzyści z Rozwoju Napędzanego Specyfikacjami

Mniejszy odstęp intencji (intent drift). Specyfikacja jest odniesieniem. Gdy agent odbiega – a odbędzie – recenzent ma coś, z czym porównać implementację. Bez specyfikacji odstęp jest niewidoczny, dopóki coś się nie zepsuje.

Lepsze wyniki AI. Agenty otrzymujące jawnie ograniczenia, rzeczy wykluczone z zakresu i kryteria akceptacji produkują implementacje bliższe temu, co zamierzono, i łatwiejsze do skorygowania, gdy mylą się. Jakość kontekstu bezpośrednio determinuje jakość wyników.

Łatwiejsza recenzja. Pull request powiązany ze specyfikacją jest łatwiejszy do recenzji niż pull request, który wymaga od recenzenta odtworzenia intencji z kodu. Specyfikacja jest listą kontrolną do recenzji.

Wyrównanie zespołu. Gdy wiele osób lub agentów pracuje nad tą samą funkcją, specyfikacja jest wspólnym kontraktem. Bez niej każdy kontrybutor optymalizuje lokalnie, a części mogą nie pasować do siebie.

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 objęte co najmniej jednym testem?

Trwała przejmość. Gdy funkcja zmienia ręce – między inżynierami, między sesjami agenta, między sprintami – specyfikacja jest artefaktem przejmości. Przechwytuje, co zostało zdecydowane, co było poza zakresem i co pozostało 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.

Fałszywe poczucie pewności. Specyfikacja, która istnieje, ale nie jest weryfikowana względem implementacji, daje fałszywe poczucie poprawności. Przestarzałe specyfikacje są czasem gorsze niż brak specyfikacji: wprowadzają w błąd recenzentów i agenty, które je odczytują.

Przestarzałe 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 oddziela SDD od dokumentacji, która kumuluje się i gnije.

Generowana biurokracja. Agenty AI mogą szybko generować wyczerpujące listy zadań i zwięzłe specyfikacje. Specyfikacja z 200 zadaniami wygenerowana w trzydzieści sekund nie jest użyteczną specyfikacją – jest to generator biurokracji. Dobry SDD wymaga osądu co do tego, co specyfikować, a co zostawić implikacyjnie.

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ą. Jest 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ć, recenzowane i wersjonowane, zanim agent to zbuduje. Trzymaj ten rekord wiarygodnym, aktualizując go, gdy rzeczywistość się różni. Używaj go jako odniesienia do recenzji, testowania i przejmości.

Specyfikacja nie jest cudem. Specyfikacja, która nie jest weryfikowana, staje się najdrodzą formą dokumentacji: taką, która wprowadza w błąd z pewnością siebie. Dobry SDD to praktyka utrzymywania specyfikacji wiarygodnymi – wystarczająco małymi, aby je utrzymać, wystarczająco precyzyjnymi, aby ograniczać, i wystarczająco trwałymi, aby przetrwać każdą pojedynczą sesję agenta.

SDD znajduje się na skrzyżowaniu praktyk 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

Subskrybuj

Otrzymuj nowe wpisy o systemach, infrastrukturze i inżynierii AI.