Praca w oparciu o specyfikacje: od wymagań do kodu

Pięć faz: od intencji do zweryfikowanego kodu.

Page content

Spec-Driven Development działa, gdy specyfikacja jest procesem, a nie dokumentem, który odkładasz do szuflady po spotkaniu kick-offowym. Chodzi nie o stworzenie obszernego dokumentu wymagań produktowych.

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

Jeśli nie wiesz, czym pojęciowo jest SDD, zacznij od Czym jest Spec-Driven Development?, aby poznać definicje, porównania z TDD i BDD oraz argumenty za traktowaniem specyfikacji jako źródła prawdy. Ten artykuł w klastrze dokumentacji Architektura aplikacji stanowi przewodnik operacyjny. Omawia on pięć faz, pokazuje, co powinien zawierać każdy artefakt, wyjaśnia, gdzie wchodzą do gry agenci AI, i dostarcza ponownie używalnych szablonów, które możesz skopiować do swojego repozytorium już dziś.

Przepływ pracy Spec-Driven Development – wymagania, projekt, zadania, implementacja, walidacja

SDD to proces, a nie dokument

Najczęstszym trybem awarii w podejściu spec-driven development jest traktowanie specyfikacji jako formalności biurowej. Zespół pisze długi dokument wymagań, przechowuje go w wikii, a następnie koduje z pamięci i na podstawie wątków czatu. Specyfikacja istnieje, ale nie napędza niczego. To teatralna dokumentacja, która jest gorsza niż brak specyfikacji, ponieważ tworzy fałszywe poczucie pewności.

Działający proces SDD generuje łańcuch artefaktów, z których każdy jest weryfikowany przed rozpoczęciem następnej fazy. Wymagania redukują niejasności produktowe. Projekt redukuje niejasności techniczne. Zadania redukują niejasności wykonawcze. Implementacja produkuje kod względem znanego celu. Walidacja dowodzi, że łańcuch się utrzymał. Gdy dowolna faza ujawnia błąd, poprawiasz artefakt i uruchamiasz proces ponownie od tego punktu — a nie po tym, jak trzy tysiące linii rozjazdów (drift) wylądują na gałęzi main.

flowchart LR A[Specify] --> B[Plan] B --> C[Tasks] C --> D[Implement] D --> E[Validate] E -->|drift found| A E -->|ship| F[Done]

Proces jest neutralny narzędziowo. Możesz go przeprowadzić za pomocą plików markdown w Gicie, z GitHub Spec Kit, z planami w Cursorze, z wymuszonym pakietem umiejętności takim jak Superpowers, lub z edytorem tekstu i dyscyplinowanym recenzentem. Liczy się sekwencja i bramki weryfikacyjne, a nie marka narzędzia.

Faza 1 – Specyfikacja wymagań

Faza specyfikacji odpowiada na pytanie, jaki problem rozwiązujesz i jak wygląda stan „ukończono”. Celowo unika kwestii „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ń. Przenieś ją do planu.

Sformułowanie problemu i użytkownicy

Zacznij od jednego akapitu, który opisuje problem prostym językiem. Wskaż użytkowników dotkniętych problemem oraz sytuację, która sprawia, że problem jest bolesny. Dobre sformułowanie problemu pozwala recenzentowi, który nie uczestniczył w spotkaniu planistycznym, ocenić, czy proponowane rozwiązanie faktycznie adresuje ból.

Przykład dla funkcji ograniczania przepustowości API (rate-limiting):

Konsumenci API na planie darmowym mogą wysyłać niezliczone żądania, co powoduje skoki kosztów i wpływ „głośnego sąsiada” na najemców płatnych. Operatorzy platformy potrzebują wymagalnego limitu per klucz bez interwencji ręcznej.

Cele, niecele i kryteria akceptacji

Cele opisują wyniki, które dostarczysz. Niecele opisują kuszące prace sąsiednie, których świadomie nie wykonasz. Razem ograniczają kreatywność agenta, co jest niezbędne, gdy narzędzia AI „pomocnie” rozszerzają zakres działania.

Sekcja Dobre przykład Słaby przykład
Cel Odrzuć żądania przekraczające limit per kluczem z kodem HTTP 429 Zrób API szybszym
Niecel Pulpity do fakturowania per najemca Popraw wszystkie wydajności API
Kryterium akceptacji Żądania nieautoryzowane otrzymują 401 przed uruchomieniem sprawdzianu limitu Endpoint jest bezpieczny

Kryteria akceptacji powinny być wystarczająco precyzyjne, aby każde z nich odpowiadało co najmniej jednemu testowi. „Endpoint jest bezpieczny” nie jest kryterium akceptacji. „Żądania nieautoryzowane otrzymują HTTP 401” — jest. Jeśli nie możesz napisać konkretnego kryterium, wymaganie jest wciąż zbyt niejasne, aby je zaimplementować.

Otwarte pytania

Wypisz każdą decyzję, która nie jest jeszcze ustalona. Niejasne pytania nie są oznaką porażki. To faza specyfikacji wykonująca swoją pracę. Rozwiąż je, zanim napiszesz plan projektowy, w przeciwnym razie zapłacisz za niejasności w postaci przepracowywania implementacji.

Minimalny szablon wymagań:

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

## Użytkownicy
- [Główna rola użytkownika]
- [Wtórna rola użytkownika]

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

## Niecele
- [Jawnie poza zakresem]
- [Jawnie poza zakresem]

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

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

Faza 2 – Planowanie projektu

Faza planowania przekłada intencje na decyzje techniczne. To tu należą posortowane zbiory Redis, wraz z granicami modułów, zmianami schematu, kontraktami API, krokami migracji, ograniczeniami bezpieczeństwa i strategią testów. Plan jest wyprowadzony ze specyfikacji wymagań oraz istniejących ograniczeń Twojego projektu — wyborów stacku, rejestru decyzji i konwencji przechowywanych w plikach takich jak AGENTS.md lub konstytucja projektu.

Architektura i dotknięte moduły

Wskazuj moduły, usługi lub pakiety, które ulegną zmianie, i podsumuj wzorzec integracji. Jeśli funkcja przekracza granicę usługi, udokumentuj kontrakt po obu stronach. Agenci halucynują API, gdy kontrakty są implicite. Ich jawne zapisanie w planie zapobiega wymyślaniu endpointów i błędnym kształtom odpowiedzi.

Model danych, kontrakty API i migracje

Dokumentuj zmiany schematu, nowe tabele lub pola, wymagania dotyczące indeksów i zasady kompatybilności wstecznej. Dla API HTTP zapisz metodę, ścieżkę, kształt żądania, kształt odpowiedzi i kody błędów. Dla zdarzeń (eventów) zapisz nazwy tematów (topic), schematy obciążenia (payload) i semantykę dostarczania. Włącz kroki migracji i notatki o cofnięciu, gdy zmienia się model danych.

Bezpieczeństwo, obserwowalność i strategia testów

Ograniczenia bezpieczeństwa należą do planu, a nie do pospiesznych myśli w przeglądzie kodu. Odnotuj wymagania uwierzytelniania, reguły autoryzacji, granice walidacji wejścia i dane, które nie mogą pojawić się w logach. Obserwowalność powinna obejmować metryki, logi lub ślady (traces) niezbędne do potwierdzenia, że funkcja działa w produkcji.

Strategia testów nawiązuje do kryteriów akceptacji. Zidentyfikuj, które kryteria potrzebują 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, wskaż pakiety i pliki testowe, które planujesz dodać. Plan bez strategii testów to plan, który trafi do produkcji z lukami, które odkryjesz dopiero w środowisku produkcyjnym.

flowchart TB subgraph plan [Zawartość planu projektowego] R[Specyfikacja wymagań] C[Konstytucja projektu / ADRs] R --> D[Decyzje architektoniczne] C --> D D --> M[Model danych i migracje] D --> A[Kontrakty API] D --> S[Ograniczenia bezpieczeństwa] D --> T[Strategia testów] end

Faza 3 – Rozbicie zadań implementacyjnych

Faza zadań dekomponuje plan na fragmenty wystarczająco małe, aby można je było zaimplementować, zweryfikować i zwalidować niezależnie. To sprawia, że rozwój wspomagany agentami jest weryfikowalny. Zamiast jednej ogromnej różnicy (diff), otrzymujesz sekwencję skupionych zmian, z których każda odnosi się do nazwanego wymagania.

Skalowalność zadań i zależności

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

flowchart TD T1[Zadanie 1 -- migracja schematu] --> T2[Zadanie 2 -- warstwa repozytorium] T2 --> T3[Zadanie 3 -- handler HTTP] T2 --> T4[Zadanie 4 -- instrumentacja metryk] T3 --> T5[Zadanie 5 -- testy integracyjne] T4 --> T5

Pliki, weryfikacja i punkty kontrolne recenzji

Każde zadanie powinno listować pliki, które prawdopodobnie ulegną zmianie, kryteria akceptacji, które spełnia, oraz sposób walidacji ukończenia. Walidacją może być komenda testowa, przykład z curl lub kontrola ręczna opisana w krokach do skopiowania i wklejenia. Każde zadanie kończy się punktem kontrolnym recenzji przez człowieka. Recenzent potwierdza, że diff zgadza się z opisem zadania, zanim zacznie się następne zadanie.

Minimalny wpis zadania:

### Zadanie 3 -- Dodanie middleware rate-limit

**Zależy od:** Zadanie 1 (schemat), Zadanie 2 (repozytorium)
**Pliki:** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**Spełnia:** AK-2 (429 po przekroczeniu limitu), AK-3 (nagłówki limitu w odpowiedzi)
**Walidacja:** `go test ./middleware/...` przechodzi; curl po przekroczeniu limitu zwraca 429 z Retry-After
**Punkt kontrolny recenzji:** Potwierdź, że middleware działa po uwierzytelnianiu, przed handlerem

Uważaj na eksplozję wygenerowanych zadań. Agenci AI mogą wygenerować plany z pięćdziesięciu zadań w kilka sekund. Większość z tych zadań będzie redundantna lub zbyt drobna, aby dało się je efektywnie zweryfikować. Przydatna lista zadań dla średniej funkcji często ma od pięciu do piętnastu elementów, a nie pięćdziesiąt.

Faza 4 – Implementuj jedno zadanie naraz

Implementacja jest celowo wąska. Wybierz jedno zadanie, daj agentowi tylko kontekst niezbędny do tego zadania i zatrzymaj się, gdy walidacja przejdzie. Reset kontekstu między zadaniami to funkcja, a nie błąd. Zapobiega on zanieczyszczaniu późniejszej pracy wcześniejszymi założeniami i utrzymuje diffy weryfikowalnymi.

Zastosuj ograniczenia ze stosu specyfikacji

Agent implementujący powinien przeczytać specyfikację wymagań, plan projektowy, bieżący opis zadania i ograniczenia na poziomie projektu. Ograniczenia to sekcja o najwyższej stopie zwrotu (ROI), której większość zespołów pomija. Mówią one agentowi, czego nie robić — nie refaktoryzuj niezwiązanych modułów, nie zmieniaj sygnatur publicznych API poza tą funkcją, 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 trwa dłużej niż oczekiwano. Przypadek brzegowy został pominięty w kryteriach akceptacji. Gdy tak się stanie, zaktualizuj specyfikację przed kontynuowaniem. Popraw wymagania lub plan, uzyskaj szybką weryfikację, a następnie wznowić implementację względem skorygowanego artefaktu. Kod, który cicho odchodzi od specyfikacji, to sposób, w jaki drift staje się permanentny.

sequenceDiagram participant H as Człowiek recenzent participant A as Agent AI participant S as Artefakty specyfikacji H->>S: Zatwierdź zadanie N A->>S: Przeczytaj zadanie + plan + ograniczenia A->>A: Zaimplementuj zadanie N A->>A: Uruchom walidację zadania A->>H: Prześlij diff do recenzji H->>H: Zweryfikuj diff względem zadania alt drift lub niespodzianka H->>S: Zaktualizuj specyfikację/plan H->>A: Uruchom ponownie ze skorygowanym kontekstem else zatwierdzone H->>S: Oznacz zadanie N jako ukończone H->>A: Przejdź do zadania N+1 end

Faza 5 – Walidacja względem specyfikacji

Walidacja to moment, w którym SDD zwraca swoją inwestycję. Bez niej specyfikacja jest tylko ćwiczeniem planistycznym. Z nią specyfikacja jest kontraktem, którego można się trzymać, porównując z dostarczanym kodem.

Automatyczne sprawdziany

Uruchom pełny zestaw testów, lint i sprawdziany typów na CI. Połącz je z Twoim pipeline’em, używając wzorców z Skróconego przewodnika po GitHub Actions, jeśli potrzebujesz praktycznego punktu startowego. Automatyczne sprawdziany łapią regresje. Nie łapią jednak błędnych funkcji zbudowanych poprawnie, dlatego recenzja kryteriów akceptacji wciąż ma znaczenie.

Kryteria akceptacji i recenzja ręczna

Przejdź przez każde kryterium akceptacji ze specyfikacji wymagań. Oznacz każde jako spełnione, nieudane lub odroczone z uzasadnieniem. Recenzja ręczna łapie problemy z UX, luki w bezpieczeństwie i błędne zachowanie, które testy przeoczyły, ponieważ były napisane zgodnie z wadliwą specyfikacją.

Diff specyfikacji do kodu

Ostatni krok walidacji porównuje implementację z planem projektowym. Czy zmienione pliki zgadzały się z plikami przewidzianymi w planie? Czy decyzje architektoniczne w kodzie zgadzały się z udokumentowanymi decyzjami? Nieoczekiwane pliki w diffe to sygnał — albo plan był niekompletny, albo agent zboczył z kursu. Oba przypadki zasługują na uwagę przed scaleniem. Utrzymywanie specyfikacji, testów i kodu w synchronizacji w rozwoju z AI przekształca tę jednorazową recenzję diffa w powtarzalną tabelę śledzenia i zestaw sprawdzianów CI, dzięki czemu drift jest łapany przy każdym PR, a nie tylko wtedy, gdy ktoś pamięta, by się przyjrzeć.

Warstwa walidacji Łapie
Testy jednostkowe i integracyjne Regresje i błędną logikę w obrębie zakresu
Lint i sprawdziany typów Problemy stylowe i błędy typów
Przejście przez kryteria akceptacji Błędne zachowanie zbudowane zgodnie ze specyfikacją
Diff specyfikacji do kodu Dryft architektoniczny i rozszerzanie zakresu

Gdzie w procesie wchodzą agenci AI

Agenci AI są akceleratorami w każdej fazie, a nie zamiennikami recenzji. Produktywnym wzorcem jest: szkic, recenzja, dopracowanie, a następnie przejście dalej. Poproś agenta o szkic specyfikacji wymagań z opisu problemu, a następnie edytuj intencję, aż cele, niecele i kryteria akceptacji będą właściwe. Poproś agenta o szkic planu projektowego z zatwierdzonych wymagań, a następnie zweryfikuj decyzje architektoniczne, zanim powstanie jakikolwiek kod. Poproś agenta o implementację jednego fragmentu zadania naraz, zatwierdzając każdy diff przed rozpoczęciem następnego zadania.

flowchart LR subgraph human [Człowiek posiada] H1[Intencja i priorytety] H2[Zatwierdzenie architektury] H3[Recenzja diffa w punktach kontrolnych] H4[Ostateczna akceptacja] end subgraph agent [Agent przyspiesza] A1[Szkic wymagań] A2[Szkic planu projektowego] A3[Wygenerowanie listy zadań] A4[Implementacja fragmentów zadań] A5[Szkic testów] end H1 --> A1 --> H1 A1 --> A2 --> H2 H2 --> A3 --> A4 --> H3 H3 --> A4 A4 --> A5 --> H4

Agenci są szczególnie przydatni przy tworzeniu pierwszych szkiców i szablonowych testów. Ludzie są szczególnie przydatni przy łapaniu błędnych celów, niebezpiecznej architektury i subtelnego rozszerzania zakresu. Proces zawodzi, gdy pominięta jest któraś ze stron — gdy agenci implementują bez specyfikacji, lub gdy ludzie piszą specyfikacje, nigdy ich nie walidując względem kodu.

Ten artykuł o procesie celowo pozostaje neutralny narzędziowo. Przewodniki wykonawcze specyficzne dla narzędzi — konfiguracja edytora, komendy slash, konfiguracja agenta — należą do klastra Narzędzia dla deweloperów AI. Filar procesu znajduje się tutaj w praktykach dokumentacyjnych, ponieważ artefakty ważą więcej niż dostawca.

Częste błędy, które zabijają Spec-Driven Development

Ogromne specyfikacje przed jakąkolwiek walidacją. Trzydziestostronkowy dokument wymagań napisany przed prototypem lub spike’em to biurokratyczna woda wodospadowa (waterfall), a nie SDD. Napisz minimalną specyfikację, która usuwa niejasności dla następnej fazy, a następnie wczesne waliduj założenia. Nie każda funkcja potrzebuje pełnej pętli pięciu faz — Spec-Driven Development vs Vibe Coding wyjaśnia, kiedy lżejsza struktura wystarcza.

Niejasne kryteria akceptacji. Przyimki takie jak „szybki”, „czysty” i „przyjazny użytkownikowi” nie są kryteriami akceptacji. Zamień je na mierzalne zachowanie. Jeśli nie możesz tego przetestować, nie możesz tego wiarygodnie zaimplementować — zwłaszcza z agentem AI.

Brak nieceli. Bez nieceli agenci rozszerzają zakres domyślnie. Dodają warstwy cache, refaktoryzują sąsiednie moduły i wprowadzają zależności, o które nie prosiłeś. Niecele to sposób, by powiedzieć „nie” z wyprzedzeniem.

Brak planu testów w fazie projektowania. Testy pisane dopiero po implementacji mają tendencję do potwierdzania tego, co zostało zbudowane, a nie tego, co było zamierzone. Plan powinien wskazać, które kryteria akceptacji odpowiadają jakim typom testów, zanim zmieni się pierwszy plik produkcyjny.

Pomijanie recenzji na granicach faz. Specyfikacja zweryfikowana przed planem. Plan zweryfikowany przed zadaniami. Zadania zweryfikowane przed implementacją. Każda bramka jest tania. Poprawianie driftu po dużym scaleniu jest kosztowne.

Pozwolenie na eksplozję wygenerowanych zadań. Traktuj listę pięćdziesięciu zadań wygenerowanych przez AI jako pierwszy szkic, a nie harmonogram. Scal redundantne elementy, podziel zbyt duże i usuń zadania, które nie odpowiadają żadnemu wymaganiu.

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

Ponownie używalne szablony

Skopiuj je do swojego repozytorium i dostosuj. Przechowuj specyfikacje obok gałęzi funkcji, recenzuj 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
## Niecele
## Kryteria akceptacji
## Otwarte pytania

Szablon projektu

# Projekt -- [nazwa funkcji]

## Podsumowanie
## Dotknięte moduły
## Zmiany modelu danych
## Kontrakty API
## Migracje
## Bezpieczeństwo
## Obserwowalność
## Strategia testów
## Ryzyka i mitygacje

Szablon listy zadań

# Zadania -- [nazwa funkcji]

## Zadanie 1 -- [tytuł]
Zależy od:
Pliki:
Spełnia:
Walidacja:
Punkt kontrolny recenzji:

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

Checklista walidacji

# Walidacja -- [nazwa funkcji]

## Automatyczne
- [ ] Wszystkie testy przechodzą
- [ ] Lint czysty
- [ ] Sprawdź typów czysty

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

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

Wnioski

Spec-Driven Development nie polega na pisaniu większej liczby dokumentów. Polega na przejściu przez fazy: specyfikacja, plan, zadania, implementacja i walidacja, z bramką weryfikacyjną na każdym kroku. Każda faza powinna zostawić następnego wykonawcę — człowieka lub agenta — z mniejszą ilością zgadywania niż faza poprzednia.

Zacznij od małego. Uruchom pełny proces na jednej średniej funkcji. Przechowuj artefakty w markdown w repozytorium. Aktualizuj specyfikację, gdy rzeczywistość się rozjeżdża. Waliduj przed scaleniem. Gdy łańcuch działa, otrzymujesz mniej driftu, mniejsze weryfikowalne diffy i trwały zapis intencji, który przetrwa resety sesji i przekazania zespołom.

Gdy łańcuch staje się papierologią, skróć zakres — a nie recenzję. Dwustronicowa specyfikacja, która została zwalidowana, bije trzydziestostronkową specyfikację, której nikt nie przeczytał.

Przydatne linki

Subskrybuj

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