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

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

Page content

Rozwój oparty na specyfikacji to jeden z tych pomysłów, do których inżynierowie oprogramowania sięgali wcześniej, a następnie odkładali na bok, gdy wysiłek przestawał się opłacać.

Co zmieniło się w 2025 roku, to pojawienie się agentów kodujących opartych na AI, które uczyniły brak jawnie sformułowanego zamiaru kosztownym. Prompty są efemeryczne. Sesje agentów są resetowane. Kod się zmienia, ale rozumowanie za nim stojące znika. Specyfikacja to artefakt, który temu zapobiega.

Czym jest rozwój oparty na specyfikacji – specyfikacja jako źródło prawdy dla kodowania AI

Specyfikacja staje się źródłem prawdy

Przez większość historii rozwoju oprogramowania specyfikacja była albo tymczasowym artefaktem planistycznym, albo czymś, o czym się zapominało. Wymagania żyły w biletach, decyzje projektowe w wątkach czatu, a kod był prawdą obiektywną. Dokumentacja opisywała to, co już istniało, po fakcie.

Rozwój oparty na specyfikacji odwraca ten związek. Specyfikacja staje się głównym artefaktem. Kod jest tym, co jest generowane lub weryfikowane na podstawie specyfikacji, a nie odwrotnie.

To nie jest nowy pomysł. Metody formalne, projektowanie przez kontrakt i BDD (Behavior-Driven Development) zawierają wersje tego podejścia. Nowe jest praktyczne uzasadnienie: agenci kodujący oparci na AI potrzebują jawnego, trwałego kontekstu, aby wygenerować poprawne i spójne wyniki. Prompty są zbyt efemeryczne. Specyfikacja to jedyny artefakt, który może przenosić zamiar między sesjami agentów, członkami zespołu i w czasie.

Czym tak naprawdę jest rozwój oparty na specyfikacji

Rozwój oparty na specyfikacji, zwykle skracany do SDD, to przepływ pracy, w którym wersjonowana specyfikacja kieruje lub generuje implementację. Specyfikacja jest pisana i recenzowana, zanim agent napisze kod. Zawiera ona:

  • Co zbudować – problem użytkownika, cele i cele negatywne (non-goals)
  • Jak wygląda poprawne zachowanie – kryteria akceptacji, przypadki graniczne, 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, ścieżka wstecz do wymagań

Ostatni punkt jest łatwy do zapisania, ale w praktyce łatwo go pominąć. Artykuł Jak utrzymać specyfikacje, testy i kod w synchronizacji w rozwoju AI opisuje, jak w praktyce wygląda ścieżka wstecz do wymagań jako dane: identyfikatory wymagań, identyfikatory decyzji projektowych oraz testy powiązane z pull requestami, które je zaimplementowały.

Specyfikacja nie jest dokumentem jednorazowym. Jest aktualizowana, gdy rzeczywistość różni się od projektu. Gdy agent odkryje podczas implementacji coś, co specyfikacja opisuje błędnie, specyfikacja jest korygowana przed kontynuowaniem pracy. Specyfikacja pozostaje uczciwa, ponieważ traktowana jest 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 na ich podstawie. Praktyczna interpretacja polega na tym, że specyfikacja to recenzowany, trwały zapis zamiaru, który każdy człowiek lub narzędzie AI może przeczytać i zaufać.

Trzy terminy obejmują różne punkty na spektrum wykorzystywania specyfikacji:

Spec-first oznacza napisanie pełnej specyfikacji przed rozpoczęciem jakiejkolwiek implementacji. Jest to najściślejsza interpretacja i ta najbliższa podejściu wodospadowemu, jeśli nie zostanie wykonana ostrożnie.

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

Spec-as-source oznacza generowanie lub walidowanie implementacji na podstawie specyfikacji, entweder przez agentów AI, albo przez narzędzia sprawdzające kod pod kątem ograniczeń specyfikacji. To 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 zintegrowanym kierownictwem w IDE. Pakiety umiejętności, takie jak Superpowers, znajdują się bliżej końca spektrum spec-anchored – egzekwują dyscyplinę recenzji automatycznie, zamiast generować kod bezpośrednio ze specyfikacji.

Dlaczego SDD ma teraz znaczenie

Szczera odpowiedź brzmi: SDD nie jest przekonujący dla pojedynczego developera budującego skrypt jednodniowy. Nakład jest niewspółmierny.

SDD staje się wartościowy, gdy występują trzy warunki: funkcjonalność jest wystarczająco duża, aby obejmować wiele sesji, agent musi podejmować decyzje wpływające na architekturę, a praca zostanie zweryfikowana lub kontynuowana przez kogoś innego.

Wszystkie trzy warunki stają się coraz częstsze w rozwoju wspomagany AI.

LLM-y potrzebują kontekstu, a nie tylko promptów. Model otrzymujący mglisty prompt podejmuje mgliste decyzje. Model otrzymujący recenzowaną specyfikację z jawnymi ograniczeniami, celami negatywnymi i kryteriami akceptacji podejmuje lepsze decyzje i łatwiej go skorygować, gdy odchodzi od kursu. Łączy się to z tym, jak działają retrieval i reprezentacja: przekazanie agentowi wersjonowanej specyfikacji to forma ustrukturyzowanego pobierania zamiaru projektu.

Generowanie kodu jest tanie; decydowanie, co zbudować, nadal jest trudne. Butelką wąską w rozwoju wspomagany AI nie jest już pisanie – to wiedza o tym, co budować i jak ograniczyć agenta. SDD przesuwa wysiłek tam, gdzie ma to znaczenie: jasne sformułowanie zamiaru przed rozpoczęciem generowania.

Prompty są efemeryczne. Agent nie pamięta tego, co powiedziano mu w poprzedniej sesji. Wersjonowana specyfikacja przechowywana w repozytorium pamięta. Każda nowa sesja może odczytać tę samą specyfikację i implementować zgodnie z tym samym zamiarem, bez konieczności ponownego ustanawiania kontekstu od zera.

**Vibe coding jest szybszy przy pracach jednorazowych; SDD vs Vibe Coding opisuje, kiedy dodawać specyfikacje, a kiedy swobodnie korzystać z promptów.

Główne artefakty

SDD produkuje cztery typy artefaktów. Każdy z nich redukuje inny rodzaj niejednoznaczności, zanim agent dotknie kodu:

  • Specyfikacja wymagań – problem, użytkownicy, cele, cele negatywne, kryteria akceptacji
  • Specyfikacja projektu – architektura, model danych, kontrakty API, ograniczenia bezpieczeństwa dla tej funkcjonalności
  • Plan zadań – małe fragmenty implementacji z zależnościami i kryteriami walidacji
  • Rejestr ścieżki wstecz – mapowanie z kryteriów akceptacji na testy, z decyzji projektowych na pliki, z zadań na commity

Jak krok po kroku tworzyć i recenzować je – specyfikuj, planuj, zadania, implementuj, waliduj – opisano w artykule Przepływ pracy rozwoju opartego na specyfikacji od wymagań do kodu. Prosta funkcjonalność może obejmować wszystkie cztery obszary w krótkim pliku markdown. Nawyk jest ważniejszy niż format.

Jak SDD różni się od dokumentacji

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

Dokumentacja opisuje. Mówi, 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 czego nie wolno. Ma ona autorytet 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 swój cel negatywnie.

Wykonywalne specyfikacje kierują generowaniem i walidacją. Najlepsze specyfikacje SDD są wystarczająco bliskie formacie maszynowo odczytywalnym, aby agent mógł je implementować, a zestaw testów mógł je zweryfikować. Kryterium akceptacji zapisane jako „endpoint musi odrzucać żądania bez uwierzytelnienia z odpowiedzią 401” to wykonywalna specyfikacja; „endpoint jest bezpieczny” to dokumentacja.

Rejestry decyzji – ADR-y, PDR-y i DDR-y – są komplementarne do artefaktów SDD, ale służą innemu celowi. Rejestry decyzji przechwytują, dlaczego podjęto wybór i co zostało odrzucone. Specyfikacje SDD przechwytują, co budować i jak to zweryfikować. Oba powinny znajdować się w repozytorium. Razem dają agentom AI pełny obraz: bieżący zamiar i rozumowanie za nim stojące.

Jak SDD różni się od TDD

Rozwój napędzany testami (TDD) i rozwój oparty na specyfikacji (SDD) są często mylone, ponieważ oba produkują jawne artefakty przed istnieniem kodu. Różnica polega na punkcie startowym.

TDD zaczyna się od testów. Piszesz test, który nie przechodzi, opisując zachowanie, którego oczekujesz, a następnie piszesz minimalny kod, aby go zaliczyć. TDD to pętla informacyjna na poziomie jednostkowym. Dostarcza dobre testy, ale nie odpowiada na pytanie, czy budujesz właściwą rzecz.

SDD zaczyna się od zamiaru. Przed istnieniem testów, przed podjęciem decyzji o architekturze, specyfikacja odpowiada: kto ma ten problem, jak wygląda poprawne zachowanie, co jest jawnie poza zakresem. Specyfikacja następnie informuje o tym, jakie testy napisać, dlatego dobry SDD i dobry TDD są komplementarne, a nie konkurencyjne.

Praktyczny sposób myślenia o tym: SDD napędza TDD. Kryteria akceptacji w specyfikacji stają się scenariuszami testowymi. Specyfikacja projektu identyfikuje granice integracji, które wymagają testów kontraktowych. Plan zadań identyfikuje, które zachowania jednostkowe wymagają pokrycia testami, zanim agent je zaimplementuje.

Jak SDD różni się od BDD

Rozwój napędzany zachowaniem (BDD) używa scenariuszy w języku naturalnym – typowo w formacie Gherkin – aby opisać oczekiwane zachowanie z perspektywy użytkownika. Te scenariusze łączą lukę między zamiarem biznesowym a techniczną implementacją.

SDD jest szerszy. Obejmuje opisy zachowań (które mogą używać języka w stylu BDD lub zwykłej prozy), ale także obejmuje decyzje architektoniczne, modele danych, ograniczenia bezpieczeństwa, planowanie zadań i ścieżkę wsteczną. 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 się w niej znajduje.

Różnica ma znaczenie w praktyce: narzędzia BDD koncentrują się na czynieniu scenariuszy wykonywalnymi. Praktyka SDD koncentruje się na czynieniu zamiaru trwałym – między narzędziami, między sesjami i między członkami zespołu.

Jak SDD różni się od metod formalnych

Metody formalne używają notacji matematycznej i automatycznej weryfikacji, aby udowadniać własności systemów oprogramowania. Są ekstremalnie rygorystyczne i ekstremalnie kosztowne dla większości kontekstów produkcyjnego rozwoju.

SDD nie wymaga notacji formalnej. Plik markdown z kryteriami akceptacji i decyzjami architektonicznymi jest specyfikacją. Ogranicza bez bycia matematycznie formalnym. Poziom rygoru skaluje się ze stawkami: specyfikacja dla usługi rozliczeniowej powinna być bardziej precyzyjna i staranniej recenzowana niż specyfikacja dla strony dokumentacji.

Związek jest spektrum:

  • Nieformalna specyfikacja w prozie (minimalny wykonalny SDD)
  • Ustrukturyzowany markdown z kryteriami akceptacji i celami negatywnymi
  • Maszynowo odczytywalna specyfikacja z walidacją schematu
  • Testy kontraktowe wyprowadzone bezpośrednio ze specyfikacji
  • Formalna specyfikacja z automatycznym dowodem

Większość zespołów operuje w środku tego spektrum. Celem nie jest rygor matematyczny – to uczynienie zamiaru wystarczająco jawnym, aby agent AI mógł go zaimplementować, a recenzent człowiek mógł zweryfikować wynik.

Korzyści z rozwoju opartego na specyfikacji

Mniej dryfu zamiaru. Specyfikacja jest referencją. Gdy agent odchodzi od kursu – a będzie – recenzent ma coś, z czym może porównać implementację. Bez specyfikacji dryf jest niewidoczny, dopóki coś się nie zepsuje.

Lepsze wyniki AI. Agenci otrzymujący jawne ograniczenia, cele negatywne i kryteria akceptacji produkują implementacje bliższe zamierzonej i łatwiejsze do skorygowania, gdy się mylą. Jakość kontekstu bezpośrednio determinuje jakość wyniku.

Łatwiejsza recenzja. Pull request powiązany ze specyfikacją jest łatwiejszy do zrecenzowania niż pull request, który wymaga od recenzenta rekonstrukcji zamiaru z kodu. Specyfikacja to checklista recenzji.

Spójność zespołu. Gdy wiele osób lub agentów pracuje nad tą samą funkcjonalnością, specyfikacja jest wspólną umową. Bez niej każdy współtwórca optymalizuje lokalnie, a elementy mogą do siebie nie pasować.

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ły przekaz. Gdy funkcjonalność zmienia właściciela – między inżynierami, między sesjami agentów, między sprintami – specyfikacja jest artefaktem przekazu. Przechwytuje, co zostało zdecydowane, co było poza zakresem i co pozostaje do zweryfikowania.

Koszty rozwoju opartego na specyfikacji

Wysiłek wstępny. Pisanie dobrej specyfikacji przed napisaniem jakiegokolwiek kodu zajmuje czas. Dla małych funkcjonalności ten nakład jest realny i czasem nie warto.

Fałszywe poczucie bezpieczeństwa. Specyfikacja, która istnieje, ale nie jest weryfikowana względem implementacji, daje fałszywe poczucie poprawności. Zestarzałe specyfikacje są czasem gorsze niż brak specyfikacji: wprowadzają w błąd recenzentów i agentów, którzy je czytają.

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

Generowana biurokracja. Agenci AI mogą szybko generować wyczerpujące listy zadań i werbalne specyfikacje. Specyfikacja 200 zadań wygenerowana w trzydzieści sekund to nie użyteczna specyfikacja – to generator biurokracji. Dobry SDD wymaga osądu co do tego, co specyfikować, a co zostawić implicite.

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

Wniosek

Rozwój oparty na specyfikacji nie jest nową metodologią. To stara dyscyplina, która staje się ponownie praktyczna, ponieważ koszt implikitego zamiaru jest teraz widoczny w kodzie generowanym przez AI.

Dyscyplina jest prosta: zapisać, co zamierzasz zbudować, recenzowane i wersjonowane, zanim agent to zbuduje. Utrzymać ten zapis uczciwym, aktualizując go, gdy rzeczywistość się różni. Używać go jako referencji dla recenzji, testów i przekazu.

Specyfikacja nie jest magią. Specyfikacja, która nie jest weryfikowana, staje się najdroższym rodzajem dokumentacji: tą, która pewnie wprowadza w błąd. Dobry SDD to praktyka utrzymywania specyfikacji uczciwymi – wystarczająco małymi, aby je utrzymywać, wystarczająco precyzyjnymi, aby ograniczać, i wystarczająco trwałymi, aby przetrwać każdą pojedynczą sesję agenta.

SDD znajduje się na przecięciu praktyki dokumentacji, architektury testów i projektowania kodu – wszystko to omawiane jest w klastrze Architektura aplikacji w produkcji wraz z rejestrami decyzji, projektowaniem API i wzorcami dostępu do danych.

Przydatne linki

Subskrybuj

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