Spec-Driven Development Workflow From Requirements to Code

Rozwój napędzany specyfikacjami (Spec-Driven Development) działa skutecznie, gdy specyfikacja jest przepływem pracy, a nie dokumentem, który archiwizuje się po fazie wstępnej. Chodzi o to, by nie tworzyć wielkiego dokumentu z wymaganiami produktu.

Chodzi o przejście przez sekwencję przeglądalnych artefaktów, z których każdy redukuje niejasności, zanim ktokolwiek – człowiek czy agent AI – zmieni kod produkcyjny.

Jeśli nie znasz pojęciowo SDD, zacznij od artykułu Czym jest rozwój napędzany specyfikacjami?, który zawiera definicje, porównania z TDD i BDD oraz argumenty za traktowaniem specyfikacji jako źródła prawdy. Ten artykuł w ramach dokumentacji Architektury Aplikacji stanowi przewodnik operacyjny. Przechodzi przez pięć faz, pokazuje, co powinien zawierać każdy artefakt, wyjaśnia, gdzie wpasowują się agenci AI, oraz dostarcza gotowe szablony, które możesz skopiować do swojego repozytorium już dziś.

SDD to przepływ pracy, nie dokument

Najczęstszym błędem w rozwoju napędzanym specyfikacjami jest traktowanie specyfikacji jako biurokracji. Zespół pisze długi dokument wymagań, przechowuje go na wiki, a następnie koduje w oparciu o pamięć i wątki czatowe. Specyfikacja istnieje, ale nic nie napędza. To teatralna dokumentacja, która jest gorsza niż brak specyfikacji, ponieważ tworzy fałszywe poczucie bezpieczeństwa.

Działający przepływ pracy SDD produkuje łańcuch artefaktów, z których każdy jest przeglądany przed rozpoczęciem kolejnej fazy. Wymagania redukują niejasności produktowe. Projekt redukuje niejasności techniczne. Zadania redukują niejasności wykonawcze. Implementacja produkuje kod względem znanego celu. Walidacja udowadnia, że łańcuch był trwały. Gdy dowolna faza ujawni błąd, naprawiasz artefakt i uruchamiasz proces od tego punktu – a nie wtedy, gdy trzy tysiące linii kodu z odchyleniami już trafiły do gałęzi głównej.

Przepływ pracy jest niezależny od narzędzi. Możesz go realizować z plikami Markdown w Git, z GitHub Spec Kit, z planami w Cursorze lub z prostym edytorem tekstu i dyscyplinowanym recenzentem. Ważna jest sekwencja i punkty kontrolne przeglądów, nie marka narzędzi.

Faza 1 – Specyfikacja wymagań

Faza specyfikacji odpowiada na pytanie, jaki problem rozwiązujesz i jak wygląda stan “zakończone”. Celowo omija ona pytanie, jak to zbudować. W momencie, gdy Twoja specyfikacja wymagań mówi “użyj posortowanych zbiorów Redis”, przestajesz specyfikować i zaczynasz projektować w niewłaściwym dokumencie. Trzymaj implementację z dala od wymagań. Umieść ją w planie.

Statement problemu i użytkownicy

Zacznij od jednego akapitu, który formułuje problem prostym językiem. Wymień użytkowników, których to dotyczy, oraz sytuację, która sprawia, że problem jest bolesny. Dobrze sformułowany problem pozwala recenzentowi, który nie brał udziału w spotkaniu planistycznym, ocenić, czy proponowane rozwiązanie faktycznie adresuje ten ból.

Przykład dla funkcji limitowania zapytań API:

Konsumenci API na warstwie darmowej mogą wysyłać nieograniczoną liczbę zapytań, co powoduje nagłe wzrosty kosztów i efekt “noisy neighbor” (hałaśliwego sąsiada) dla płatnych najemców. Operatorzy platformy potrzebują egzekwowalnego limitu per klucz bez interwencji ręcznej.

Cele, cele wykluczone (non-goals) i kryteria akceptacji

Cele opisują rezultaty, które dostarcysz. Cele wykluczone opisują kuszące, powiązane prace, których celowo nie wykonasz. Razem one ograniczają kreatywność agenta, co jest kluczowe, gdy narzędzia AI w inny sposób “pomagają” rozszerzając zakres.

Kryteria akceptacji powinny być na tyle precyzyjne, by każde z nich mapowało się co najmniej na jeden test. “Endpoint jest bezpieczny” nie jest kryterium akceptacji. “Nieautoryzowane zapytania otrzymują HTTP 401” jest. Jeśli nie możesz napisać konkretnego kryterium, wymaganie jest wciąż zbyt niejasne do zaimplementowania.

Otwarte pytania

Wypisz każdą decyzję, która nie została jeszcze podjęta. Niejasne pytania nie są oznaką porażki. To faza specyfikacji wykonująca swoją pracę. Rozwiąż je przed napisaniem planu projektowego, w przeciwnym razie zapłacisz za tę niejasność kosztami ponownej implementacji.

Minimalny szablon wymagań:

## Problem
[Jeden akapit: kto odczuwa ból, dlaczego i co go wywołuje.]

## Użytkownicy
- [Główna rola użytkownika]
- [Drugorzędna rola użytkownika]

## Cele
1. [Mierzalny rezultat]
2. [Mierzalny rezultat]

## Cele wykluczone
- [Jawne wykluczenie z zakresu]
- [Jawne wykluczenie z zakresu]

## Kryteria akceptacji
- [ ] [Weryfikowalne zachowanie]
- [ ] [Weryfikowalne zachowanie]

## Otwarte pytania
- [ ] [Pytanie blokujące planowanie]

Faza 2 – Planowanie projektu

Faza planowania tłumaczy intencje na decyzje techniczne. Tutaj powinny znaleźć się posortowane zbiory Redis, wraz z granicami modułów, zmianami schematów, kontraktami API, krokami migracji, ograniczeniami bezpieczeństwa oraz strategią testową. Plan jest wyprowadzony ze specyfikacji wymagań oraz istniejących ograniczeń Twojego projektu – wyborów stosu technologicznego, rejestru decyzji i konwencji przechowywanych w plikach takich jak AGENTS.md lub konstytucja projektu.

Architektura i dotknięte moduły

Wymień moduły, usługi lub pakiety, które ulegną zmianie, i streszcz wzorzec integracji. Jeśli funkcja przekracza granicę usługi, udokumentuj kontrakt po obu stronach. Agenty halucynują API, gdy kontrakty są implikowane. Zrobienie ich jawnymi w planie zapobiega wynalezieniu nieistniejących endpointów i błędnym kształtom odpowiedzi.

Model danych, kontrakty API i migracje

Udokumentuj zmiany schematów, nowe tabele lub pola, wymagania dotyczące indeksów oraz zasady zgodności wstecznej. Dla API HTTP napisz metodę, ścieżkę, kształt żądania, kształt odpowiedzi i kody błędów. Dla zdarzeń napisz nazwy tematów, schematy ładunku i semantykę dostawy. Uwzględnij kroki migracji i notatki dotyczące cofania, gdy zmienia się model danych.

Bezpieczeństwo, obserwowalność i strategia testowa

Ograniczenia bezpieczeństwa należą do planu, a nie są dodatkiem w przeglądzie kodu. Zauważ wymagania dotyczące uwierzytelniania, reguły autoryzacji, granice walidacji wejścia oraz dane, które nie powinny pojawiać się w logach. Obserwowalność powinna obejmować metryki, logi lub ślady potrzebne do potwierdzenia, że funkcja działa w środowisku produkcyjnym.

Strategia testowa odwołuje się do kryteriów akceptacji. Określ, które kryteria wymagają testów jednostkowych, które testów integracyjnych, a które weryfikacji ręcznej. Jeśli używasz testów jednostkowych w Go lub testów jednostkowych w Pythonie, wymień pakiety i pliki testowe, które oczekujesz dodać. Plan bez strategii testowej to plan, który trafi do produkcji z lukami, które odkryjesz później.

Faza 3 – Rozbicie zadań implementacyjnych

Faza zadań dekomponuje plan na fragmenty wystarczająco małe, by można je było zaimplementować, przeanalizować i zwalidować niezależnie. To to sprawia, że rozwój z asystą agenta jest przeglądalny. Zamiast jednego ogromnego diffu, otrzymujesz sekwencję ukierunkowanych zmian, z których każda odnosi się do nazwanego wymagania.

Rozmiar zadań i zależności

Dobre zadanie dotyka ograniczonego zestawu plików, kończy się w jednej sesji agenta i kończy się krokiem weryfikacji. Zadania powinny jawno deklarować zależności. Zadania migracyjne wykonują się przed kodem odczytującym nowy schemat. Zmiany w bibliotekach współdzielonych wykonują się przed konsumentami. Zmiany w middleware’u uwierzytelniającym wykonują się przed endpointami zależnymi od nowego zachowania.

Pliki, walidacja i punkty kontrolne przeglądu

Każde zadanie powinno wymienić pliki, które prawdopodobnie ulegną zmianie, kryteria akceptacji, które spełnia, oraz sposób weryfikacji ukończenia. Walidacja może być komendą testową, przykładem curla lub ręczną kontrolą opisaną w krokach do skopiowania. Każde zadanie kończy się punktem kontrolnym przeglądu przez człowieka. Recenzent potwierdza, że diff zgadza się z opisem zadania, zanim rozpocznie się kolejne zadanie.

Minimalny wpis zadania:

### Zadanie 3 -- Dodaj middleware limitowania

**Zależności:** Zadanie 1 (schemat), Zadanie 2 (repozytorium)
**Pliki:** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**Spełnia:** AC-2 (429 przy przekroczeniu limitu), AC-3 (nagłówki limitu w odpowiedzi)
**Walidacja:** `go test ./middleware/...` przechodzi; curl przekraczający limit zwraca 429 z Retry-After
**Punkt kontrolny przeglądu:** Potwierdź, że middleware działa po uwierzytelnieniu, ale przed handlerem

Uważaj na wybuch generowanych zadań. Agenci AI mogą wyprodukować plany pięćdziesięciu zadań w kilka sekund. Większość z tych zadań będzie redundantna lub zbyt granulowana, by można ją efektywnie przeglądać. Przydatna lista zadań dla funkcji średniego rozmiaru często ma od pięciu do piętnastu pozycji, a nie pięćdziesiąt.

Faza 4 – Implementacja po jednym zadaniu

Implementacja jest celowo wąska. Wybierz jedno zadanie, daj agentowi tylko kontekst potrzebny do tego zadania i zatrzymaj się, gdy walidacja przejdzie. Resetowanie kontekstu między zadaniami jest cechą, a nie błędem. Zapobiega to zanieczyszczeniu późniejszej pracy wcześniejszymi założeniami i utrzymuje diffy w stanie przeglądalnym.

Stosuj ograniczenia ze stosu specyfikacji

Implementujący agent powinien przeczytać specyfikację wymagań, plan projektowy, opis bieżącego zadania oraz ograniczenia na poziomie projektu. Ograniczenia to sekcja o najwyższym zwrocie z inwestycji, której większość zespołów pomija. Powiadziają agentowi, czego nie robić – nie refaktoryzuj niezwiązanych modułów, nie zmieniaj sygnatur publicznych API poza tym featurem, nie wprowadzaj nowych zależności bez aktualizacji planu.

Aktualizuj plan, gdy rzeczywistość się różni

Implementacja ujawni niespodzianki. Biblioteka nie obsługuje zakładanego zachowania. Migracja zajmuje dłużej niż oczekiwano. Przypadek brzegowy został pominięty w kryteriach akceptacji. Gdy tak się stanie, zaktualizuj specyfikację przed kontynuowaniem. Napraw wymagania lub plan, przeprowadź szybki przegląd, a następnie wznowij implementację względem skorygowanego artefaktu. Kod, który cicho odbiega od specyfikacji, to sposób, w jaki odchylenie staje się trwałe.

Faza 5 – Walidacja względem specyfikacji

Walidacja to miejsce, w którym SDD zarabia na swoim. Bez niej specyfikacja to ćwiczenie planistyczne. Z nią specyfikacja to kontrakt, z którym możesz porównać wyślij kod.

Automatyczne kontrole

Uruchom pełny zestaw testów, lint i kontrole typów w CI. Podłącz je do swojego potoku, używając wzorców ze skorotowicy GitHub Actions, jeśli potrzebujesz praktycznego punktu startowego. Automatyczne kontrole łapią regresje. Nie łapią jednak błędnych funkcji zbudowanych poprawnie, dlatego przegląd kryteriów akceptacji nadal ma znaczenie.

Kryteria akceptacji i przegląd ręczny

Przejdź przez każde kryterium akceptacji ze specyfikacji wymagań. Oznacz każde jako spełnione, nieudane lub odroczone z uzasadnieniem. Przegląd ręczny łapie problemy UX, luki bezpieczeństwa i błędne zachowanie, które testy przeoczyły, ponieważ testy były napisane tak, by pasowały do błędnej specyfikacji.

Diff specyfikacji do kodu

Ostatni krok walidacji porównuje implementację z planem projektowym. Czy zmienione pliki pasują do plików przewidzianych w planie? Czy decyzje architektoniczne w kodzie pasują do odnotowanych decyzji? Nieoczekiwane pliki w diffie to sygnał – albo plan był niekompletny, albo agent się zgubił. Oboje zasługują na uwagę przed scaleniem.

Gdzie agenci AI wpasowują się w przepływ pracy

Agenci AI to akceleratory w każdej fazie, a nie zastępcy dla przeglądu. Produktywnym wzorcem jest: szkic, przegląd, doszlifowanie, a następnie kontynuacja. Poproś agenta o szkic specyfikacji wymagań z opisu problemu, a następnie edytuj intencję, dopóki cele, cele wykluczone i kryteria akceptacji nie będą poprawne. Poproś agenta o szkic planu projektowego z zatwierdzonych wymagań, a następnie przeglądaj decyzje architektoniczne, zanim jakikolwiek kod istnieje. Poproś agenta o implementację po jednej porcji zadania, zatwierdzając każdy diff przed rozpoczęciem kolejnego zadania.

Agenci są szczególnie przydatni przy produkcji pierwszych szkiców i testów boilerplate. Ludzie są szczególnie przydatni przy łapaniu błędnych celów, niebezpiecznej architektury i subtelnego przekraczania zakresu. Przepływ pracy zawodzi, gdy pomija się którąkolwiek ze stron – gdy agenty implementują bez specyfikacji, lub gdy ludzie piszą specyfikacje, nigdy ich nie walidując przeciwko kodowi.

Ten artykuł o przepływie pracy celowo pozostaje niezależny od narzędzi. Przewodniki wykonawcze specyficzne dla narzędzi – konfiguracja edytora, komendy slash, konfiguracja agenta – należą do klastra Narzędzia Deweloperskie AI. Filary procesu znajdują się tutaj w praktykach dokumentacyjnych, ponieważ artefakty są ważniejsze niż dostawca.

Najczęstsze błędy zabijające rozwój napędzany specyfikacjami

Ogromne specyfikacje przed jakąkolwiek walidacją. Trzydziestostronicowy dokument wymagań napisany przed prototypem lub spiżem to biurokracja wodospadowa, nie SDD. Napisz minimalną specyfikację, która usuwa niejasności dla kolejnej fazy, a następnie wczesnie waliduj założenia. Nie każda funkcja potrzebuje pełnej pętli pięciu faz – Rozwój Napędzany Specyfikacjami vs Kodowanie Wibracyjne wyjaśnia, kiedy lżejsza struktura wystarczy.

Niejasne kryteria akceptacji. Przysłówki jak “szybki”, “czysty” i “przyjazny dla użytkownika” nie są kryteriami akceptacji. Zamień je na mierzalne zachowanie. Jeśli nie możesz tego przetestować, nie możesz tego zaimplementować niezawodnie – zwłaszcza z agentem AI.

Brak celów wykluczonych. Bez celów wykluczonych agenty domyślnie rozszerzają zakres. Dodają warstwy cache, refaktoryzują sąsiadujące moduły i wprowadzają zależności, o które nie prosiłeś. Cele wykluczone to sposób, w jaki mówisz “nie” z wyprzedzeniem.

Brak planu testów w fazie projektowej. Testy napisane dopiero po implementacji mają skłonność do potwierdzania tego, co zbudowano, a nie tego, co było zamierzone. Plan powinien nazwać, które kryteria akceptacji mapują się na które typy testów, zanim pierwszy plik produkcyjny ulegnie zmianie.

Pomijanie przeglądu na granicach faz. Specyfikacja przeglądana przed planem. Plan przeglądany przed zadaniami. Zadania przeglądane przed implementacją. Każda brama jest tania. Naprawianie odchylenia po dużym scaleniu jest drogie.

Pozwalanie na wybuch generowanych zadań. Traktuj listę zadań wygenerowaną przez AI z pięćdziesięciu pozycji jako pierwszy szkic, a nie harmonogram. Scal redundantne pozycje, podziel nadmiarowe i usuń zadania, które nie mapują się na wymaganie.

SDD działa, gdy każda faza redukuje niejasności. Zawodzi, gdy tworzy biurokrację.

Szablony do ponownego użycia

Skopiuj je do swojego repozytorium i dostosuj. Przechowuj specyfikacje obok gałęzi funkcji, przeglądaj je w pull requestach i trzymaj pod kontrolą wersji, aby agenci i ludzie czytali to samo źródło.

Szablon wymagań

# Funkcja -- [nazwa]

## Problem
## Użytkownicy
## Cele
## Cele wykluczone
## Kryteria akceptacji
## Otwarte pytania

Szablon projektu

# Projekt -- [nazwa funkcji]

## Streszczenie
## Dotknięte moduły
## Zmiany modelu danych
## Kontrakty API
## Migracje
## Bezpieczeństwo
## Obserwowalność
## Strategia testowa
## Ryzyka i środki łagodzące

Szablon listy zadań

# Zadania -- [nazwa funkcji]

## Zadanie 1 -- [tytuł]
Zależności:
Pliki:
Spełnia:
Walidacja:
Punkt kontrolny przeglądu:

## Zadanie 2 -- [tytuł]
...

Lista kontrolna walidacji

# Walidacja -- [nazwa funkcji]

## Automatyczne
- [ ] Wszystkie testy przechodzą
- [ ] Lint czyste
- [ ] Kontrola typów czyste

## Kryteria akceptacji
- [ ] AC-1 --
- [ ] AC-2 --

## Specyfikacja do kodu
- [ ] Zmienione pliki pasują do planu
- [ ] Brak nieudokumentowanych zmian architektonicznych
- [ ] Specyfikacja zaktualizowana, jeśli implementacja się różniła

Podsumowanie

Rozwój napędzany specyfikacjami nie polega na pisaniu więcej dokumentów. Polega na przechodzeniu przez specyfikację, planowanie, zadania, implementację i walidację z bramą przeglądu na każdym kroku. Każda faza powinna pozostawić kolejnego wykonawcę – człowieka lub agenta – z mniejszą liczbą zgadywań niż poprzednia faza.

Zacznij małym krokiem. Uruchom pełny przepływ na jednej funkcji średniego rozmiaru. Trzymaj artefakty w Markdown w repozytorium. Aktualizuj specyfikację, gdy rzeczywistość odbiega. Waliduj przed scaleniem. Gdy łańcuch działa, otrzymujesz mniej odchylenia, mniejsze, przeglądalne diffy i trwały rejestr intencji, który przetrwa resety sesji i przekazania między zespołami.

Gdy łańcuch staje się biurokracją, skróć zakres – nie przegląd. Dwustronicowa specyfikacja, która została zwalidowana, wygrywa nad trzydziestostronicową specyfikację, której nikt nie czytał.

Przydatne linki

• Dokumentacja GitHub Spec Kit – open-source’owy zestaw narzędzi implementujący podobną pętlę: specyfikuj-planuj-zadania-implementuj
• Martin Fowler o narzędziach do Rozwoju Napędzanego Specyfikacjami – analiza Kiro, Spec Kit i Tessl