Workflow rozwoju oparty na specyfikacjach: od wymagań do kodu

Pięć faz od intencji po zweryfikowany kod.

Page content

Rozwój oparty na specyfikacjach (Spec-Driven Development, SDD) działa, gdy specyfikacja jest procesem, a nie dokumentem, który archiwizujemy po spotkaniu kick-off. Chodzi nie o to, aby wyprodukować obszerny dokument wymagań produktu.

Chodzi o to, aby przechodzić przez sekwencję weryfikowalnych artefaktów, które kolejno zmniejszają niejednoznaczność, zanim ktokolwiek — człowiek czy agent AI — zmieni kod produkcyjny.

Jeśli nie wiesz, czym SDD jest koncepcyjnie, 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 klastrowym Architektura aplikacji jest przewodnikiem operacyjnym. Omawia pięć faz, pokazuje, co powinien zawierać każdy artefakt, wyjaśnia, gdzie wchodzą agenci AI, i daje wzorce szablonów, które możesz dziś skopiować do swojego repozytorium.

Przepływ pracy rozwoju opartego na specyfikacjach – wymagania, projekt, zadania, implementacja, walidacja

SDD to przepływ pracy, nie dokument

Najczęstszym błędem w rozwoju opartym na specyfikacjach jest traktowanie specyfikacji jak biurokracji. Zespół pisze długi dokument wymagań, przechowuje go na wiki, a następnie koduje z pamięci i na podstawie wątków czatu. Specyfikacja istnieje, ale nie napędza niczego. To jest teatralne dokumentowanie, i 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 weryfikowany, zanim rozpocznie się następna faza. Wymagania zmniejszają niejednoznaczność produktową. Projekt zmniejsza niejednoznaczność techniczną. Zadania zmniejszają niejednoznaczność wykonawczą. Implementacja produkuje kod w oparciu o znany cel. Walidacja dowodzi, że łańcuch się trzymał. Kiedy jakakolwiek faza ujawnia błąd, poprawiamy artefakt i ponawiamy działanie od tego punktu – nie po tym, jak trzy tysiące linii odchylenia lądują w 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]

Przepływ pracy jest niezależny od narzędzi. Możesz go prowadzić za pomocą plików markdown w Git, z GitHub Spec Kit, z lżejszym CLI skupionym na zmianach, takim jak OpenSpec, z planami Cursor, z wymuszonym pakietem umiejętności, takim jak Superpowers, albo z prostym edytorem tekstu i zdyscyplinowanym recenzentem. Ważna jest sekwencja i bramki weryfikacyjne, a nie marka narzędzi.

Faza 1 – Określenie wymagań

Faza określania odpowiada na pytanie, jaki problem rozwiązujesz i jak wygląda „ukończony” produkt. Deliberatnie unika tego, jak go zbudować. W momencie, gdy specyfikacja wymagań mówi „użyj uporządkowanych zbiorów Redis”, przestajesz określać wymagania i zaczynasz projektować w niewłaściwym dokumencie. Nie wprowadzaj implementacji do wymagań. Wstaw ją do planu.

Sformułowanie problemu i użytkownicy

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

Przykład dla funkcji limitowania żądań API:

Użytkownicy API z darmowym planem mogą wysyłać nieograniczoną liczbę żądań, co powoduje skoki kosztów i wpływ „hałaśliwego sąsiada” na najemców z płatnych planów. Operatorzy platformy potrzebują wymagalnego limitu na klucz bez interwencji manualnej.

Cele, cele poza zakresem i kryteria akceptacji

Cele opisują rezultaty, które dostarczymy. Cele poza zakresem opisują kuszące prace sąsiednie, których zdecydowanie nie wykonamy. Razem ograniczają kreatywność agenta, co jest niezbędne, gdy narzędzia AI w innym przypadku „pomocnie” rozszerzają zakres.

Sekcja Dobry przykład Słaby przykład
Cel Odrzucaj żądania przekraczające limit per kluczem z HTTP 429 Zrób API szybszym
Cel poza zakresem Dashboards rozliczeniowe per najemcom Popraw wydajność całego API
Kryterium akceptacji Żądania niezalogowane otrzymują 401, zanim uruchomi się sprawdzanie limitu Endpoint jest bezpieczny

Kryteria akceptacji powinny być wystarczająco precyzyjne, aby każde z nich mogło zostać zmapowane na co najmniej jeden test. „Endpoint jest bezpieczny” nie jest kryterium akceptacji. „Żądania niezalogowane otrzymują HTTP 401” jest. Jeśli nie potrafisz napisać konkretnego kryterium, wymaganie jest nadal zbyt niejasne, aby je zaimplementować.

Otwarte pytania

Wypisz każdą decyzję, która nie została jeszcze podjęta. Niejasne pytania nie są znakiem porażki. To faza określania wykonująca swoją pracę. Rozwiąż je, zanim napiszesz plan projektu, w przeciwnym razie zapłacisz za tę niejednoznaczność w postaci ponownej przebudowy implementacji.

Minimalny szablon wymagań:

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

## Użytkownicy
- [Rola głównego użytkownika]
- [Rola drugorzędnego użytkownika]

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

## Cele poza zakresem
- [Jawnie poza zakresem]
- [Jawnie poza zakresem]

## Kryteria akceptacji
- [ ] [Zweryfikowalne zachowanie]
- [ ] [Zweryfikowalne zachowanie]

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

Faza 2 – Zaplanowanie projektu

Faza planowania przekłada intencję na decyzje techniczne. To jest miejsce, gdzie należy wskazać uporządkowane zbiory Redis, a także granice modułów, zmiany schematu, kontrakty API, kroki migracji, ograniczenia bezpieczeństwa i strategię testowania. Plan jest wyprowadzony ze specyfikacji wymagań oraz istniejących ograniczeń projektu – wyborów stacka, rejestru decyzji i konwencji przechowywanych w plikach, takich jak AGENTS.md lub konstytucja projektu.

Architektura i dotknięte moduły

Wskaż 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ą implikowane. Sprawienie, że są jawne w planie, zapobiega wymyślanym endpointom 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ń zapisz nazwy tematów, schematy obciążenia i semantykę dostarczania. Włącz kroki migracji i notatki o wycofywaniu, gdy zmienia się model danych.

Bezpieczeństwo, obserwowalność i strategia testowania

Ograniczenia bezpieczeństwa należą do planu, a nie do post factum w recenzji kodu. Oznacz wymagania uwierzytelniania, reguły autoryzacji, granice walidacji wejścia i 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 testowania odnosi się do kryteriów akceptacji. Zidentyfikuj, które kryteria wymagają testów jednostkowych, które testów integracyjnych, a które manualnej weryfikacji. Jeśli używasz testów jednostkowych w Go lub testów jednostkowych w Pythonie, wskaż pakiety i pliki testów, które oczekujesz dodać. Plan bez strategii testowania 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 / ADR-y] R --> D[Decyzje architektoniczne] C --> D D --> M[Model danych i migracje] D --> A[Kontrakty API] D --> S[Ograniczenia bezpieczeństwa] D --> T[Strategia testowania] end

Faza 3 – Rozbicie zadań implementacyjnych

Faza zadań dekomponuje plan na fragmenty wystarczająco małe, aby zaimplementować, zweryfikować i zapisać je niezależnie. To sprawia, że rozwój wspierany przez agentów 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 zakończy krokiem weryfikacyjnym. Zadania powinny jawnie deklarować zależności. Zadania migracyjne są wykonywane przed kodem, który czyta nowy schemat. Zmiany w bibliotekach współdzielonych są wykonywane przed konsumentami. Zmiany w middleware uwierzytelniania są wykonywane przed endpointami, które zależą od nowego zachowania.

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

Pliki, walidacja i punkty kontrolne recenzji

Każde zadanie powinno zawierać listę plików, które prawdopodobnie ulegną zmianie, kryteria akceptacji, które spełnia, i sposób weryfikacji ukończenia. Walidacja może być poleceniem testowym, przykładem curla lub manualnym sprawdzianem opisanym krokami do skopiowania. Każde zadanie kończy się na punkcie kontrolnym recenzji ludzkiej. Recenzent potwierdza, że diff odpowiada opisowi zadania, zanim rozpocznie się następne zadanie.

Minimalny wpis zadania:

### Zadanie 3 -- Dodanie middleware limitowania żądań

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

Uważaj na eksplozję wygenerowanych zadań. Agenci AI mogą wygenerować plan pięćdziesięciu zadań w kilka sekund. Większość z tych zadań będzie nadmierna lub zbyt szczegółowa, aby efektywnie je recenzować. Przydatna lista zadań dla funkcji średniej wielkości często ma pięć do piętnastu elementów, a nie pięćdziesiąt.

Faza 4 – Implementacja jednego zadania na raz

Implementacja jest celowo wąska. Wybierz jedno zadanie, daj agentowi tylko kontekst, którego potrzebuje do tego zadania, i zatrzymaj się, gdy walidacja przejdzie. Resetowanie kontekstu między zadaniami to cecha, a nie błąd. Zapobiega one, aby wcześniejsze założenia zanieczyściły późniejszą pracę, i utrzymuje diffy weryfikowalne.

Zastosowanie ograniczeń ze stosu specyfikacji

Agent implementujący powinien czytać specyfikację wymagań, plan projektu, aktualny opis zadania i ograniczenia na poziomie projektu. Ograniczenia to sekcja o najwyższym zwrocie z inwestycji, którą większość zespołów pomija. Mówią agentowi, czego nie robić – nie refactoruj niezwiązanych modułów, nie zmieniaj sygnatur publicznych API poza tą funkcją, nie wprowadzaj nowych zależności bez aktualizacji planu.

Aktualizacja planu, gdy rzeczywistość różni się

Implementacja ujawni niespodzianki. Biblioteka nie wspiera zakładanego zachowania. Migracja trwa dłużej niż oczekiwano. Przypadek graniczny był pominięty w kryteriach akceptacji. Gdy to się dzieje, zaktualizuj specyfikację, zanim przejdziesz dalej. Popraw wymagania lub plan, uzyskaj szybką recenzję, a następnie wznow implementację w oparciu o poprawiony artefakt. Kod, który cicho odchodzi od specyfikacji, to sposób, w jaki dryf staje się trwały.

sequenceDiagram participant H as Ludzki 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: Złóż diff do recenzji H->>H: Recenzuj diff w oparciu o zadanie alt dryf lub niespodzianka H->>S: Zaktualizuj specyfikację/plan H->>A: Ponów z poprawionym kontekstem else zatwierdzone H->>S: Oznacz zadanie N jako ukończone H->>A: Przejdź do zadania N+1 end

Faza 5 – Walidacja w oparciu o specyfikację

Walidacja to miejsce, gdzie SDD zwraca swoją wartość. Bez niej specyfikacja to ćwiczenie planistyczne. Z nią specyfikacja to umowa, z którą można się zestawić z dostarczonym kodem.

Sprawdzanie automatyczne

Uruchom pełny zestaw testów, lint i sprawdzanie typów na CI. Podłącz je do swojej potoku, używając wzorców ze ściągawki GitHub Actions, jeśli potrzebujesz praktycznego punktu wyjścia. Sprawdzenia automatyczne wykrywają regresje. Nie wykrywają błędnych funkcji zbudowanych poprawnie, dlatego recenzja kryteriów akceptacji nadal ma znaczenie.

Kryteria akceptacji i recenzja manualna

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

Diff specyfikacji i kodu

Ostatni krok walidacji porównuje implementację z planem projektowym. Czy zmienione pliki odpowiadały plikom przewidywanym w planie? Czy decyzje architektoniczne w kodzie odpowiadały zarejestrowanym decyzjom? Nieoczekiwane pliki w diffie to sygnał – albo plan był niekompletny, albo agent odbiegł. Oba zasługują na uwagę przed scaleniem. Utrzymywanie specyfikacji, testów i kodu w synchronizacji w rozwoju AI zamienia tę jednorazową recenzję diffa w powtarzalną tabelę śledzenia i zestaw sprawdzeń CI, dzięki czemu dryf jest wykrywany przy każdym PR, a nie tylko wtedy, gdy ktoś przypomni sobie, żeby to sprawdzić.

Warstwa walidacji Wykrywa
Testy jednostkowe i integracyjne Regresje i błędną logikę w zakresie
Lint i sprawdzanie typów Problemy stylistyczne i błędy typów
Przegląd kryteriów akceptacji Błędne zachowanie zbudowane zgodnie ze specyfikacją
Diff specyfikacji i kodu Dryf architektoniczny i rozrost zakresu

Gdzie agenci AI pasują do przepływu pracy

Agenci AI są przyspieszaczami na każdej fazie, a nie substytutami recenzji. Produktywnym wzorcem jest szkic, recenzja, doszlifowanie, a następnie przejście. Poproś agenta o szkicowanie specyfikacji wymagań z opisu problemu, a następnie edytuj intencję, aż cele, cele poza zakresem i kryteria akceptacji będą poprawne. Poproś agenta o szkicowanie planu projektu z zatwierdzonych wymagań, a następnie przeglądaj decyzje architektoniczne, zanim jakikolwiek kod zaistnieje. 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 włada] H1[Intencja i priorytety] H2[Zatwierdzenie architektury] H3[Recenzja diff na punktach kontrolnych] H4[Ostateczna akceptacja] end subgraph agent [Agent przyspiesza] A1[Szkicowanie wymagań] A2[Szkicowanie planu projektu] A3[Generowanie listy zadań] A4[Implementacja fragmentów zadań] A5[Szkicowanie testów] end H1 --> A1 --> H1 A1 --> A2 --> H2 H2 --> A3 --> A4 --> H3 H3 --> A4 A4 --> A5 --> H4

Agenci są szczególnie przydatni w tworzeniu pierwszych szkiców i szablonowych testów. Ludzie są szczególnie przydatni w wykrywaniu błędnych celów, niebezpiecznej architektury i subtelnego rozrostu zakresu. Przepływ pracy zawodzi, gdy pominięta zostanie któraś ze stron – gdy agenci implementują bez specyfikacji, lub gdy ludzie piszą specyfikacje, nie zwalidowując ich nigdy w oparciu o kod.

Ten artykuł o przepływie pracy celowo jest niezależny od narzędzi. Przewodniki po uruchamianiu zależne od narzędzi – konfiguracja edytora, komendy ukośne, konfiguracja agentów – należą do klastrowego Narzędzia AI dla deweloperów. Pilarz procesu żyje tu w ramach praktyk dokumentowania, ponieważ artefakty są ważniejsze niż producent.

Częste błędy zabijające rozwój oparty na specyfikacjach

Ogromne specyfikacje przed jakąkolwiek walidacją. Trzydziestostronicowy dokument wymagań napisany przed prototypem lub spike’em to biurokracja wodospadowa, a nie SDD. Napisz minimalną specyfikację, która usuwa niejednoznaczność dla następnej fazy, a następnie wczesną walidację założeń. Nie każda funkcja potrzebuje pełnego pięciofazowego pętli – Spec-Driven Development vs Vibe Coding wyjaśnia, kiedy lżejsza struktura wystarczy.

Niejasne kryteria akceptacji. Przymiotniki takie jak „szybki”, „czysty” i „przyjazny użytkownikowi” nie są kryteriami akceptacji. Zastąp je mierzalnym zachowaniem. Jeśli nie możesz tego przetestować, nie możesz go niezawodnie zaimplementować – szczególnie z agentem AI.

Brak celów poza zakresem. Bez celów poza zakresem agenci domyślnie rozszerzają zakres. Dodają warstwy cache, refaktorują sąsiednie moduły i wprowadzają zależności, o które nie prosiłeś. Cele poza zakresem to sposób, w jaki mówisz „nie” z wyprzedzeniem.

Brak planu testów na etapie projektu. Testy pisane dopiero po implementacji mają tendencję do potwierdzania tego, co zostało zbudowane, a nie tego, co było zamierzone. Plan powinien nazwać, które kryteria akceptacji mapują się na które typy testów, zanim zmieni się pierwszy plik produkcyjny.

Pomijanie recenzji na granicach faz. Specyfikacja recenzowana przed planem. Plan recenzowany przed zadaniami. Zadania recenzowane przed implementacją. Każda bramka jest tania. Poprawa dryfu po dużym scaleniu jest droga.

Pozwalanie na eksplozję wygenerowanych zadań. Traktuj listę pięćdziesięciu zadań wygenerowaną przez AI jako pierwszy szkic, a nie harmonogram. Scal redundancje, podziel nadmiernie duże pozycje i usuń zadania, które nie mapują się na wymaganie.

Usuwanie odrzuconych badań zamiast zapisywania dlaczego. Gdy recenzja fazy 2 dochodzi do wniosku, że kierunek nie jest wart zbudowania, refleks to usunięcie specyfikacji i przejście dalej. To wymazuje rozumowanie, i ten sam pomysł powstaje następnego kwartału, badany od zera przez tego, kto – człowiek czy agent – przypadkiem na niego wpadnie. Zapisanie odrzucenia z tą samą rygorystycznością co decyzja zaakceptowana jest tanie w porównaniu; Odrzucone propozycje OpenSpec: konwencja pamięci decyzyjnej omawia jeden konkretny sposób, aby to zrobić, w tym instrukcję, która sprawia, że agent przeszukuje wcześniejsze decyzje przed ponownym proponowaniem.

SDD działa, gdy każda faza zmniejsza niejednoznaczność. Zawodzi, gdy tworzy biurokrację.

Wzorzec szablonów

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

Szablon wymagań

# Funkcja -- [nazwa]

## Problem
## Użytkownicy
## Cele
## Cele poza zakresem
## Kryteria akceptacji
## Otwarte pytania

Szablon projektu

# Projekt -- [nazwa funkcji]

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

Szablon listy zadań

# Zadania -- [nazwa funkcji]

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

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

Kontrolka walidacji

# Walidacja -- [nazwa funkcji]

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

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

## Specyfikacja i kod
- [ ] Zmienione pliki odpowiadają planowi
- [ ] Brak niedokumentowanych zmian architektonicznych
- [ ] Specyfikacja zaktualizowana, jeśli implementacja się różniła

Wniosek

Rozwój oparty na specyfikacjach nie polega na pisaniu więcej dokumentów. Polega na przechodzeniu przez fazy: określ, planuj, zadania, implementuj i waliduj, 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łych. Prowadź pełny przepływ pracy dla jednej funkcji średniej wielkości. Przechowuj artefakty w markdown w repozytorium. Aktualizuj specyfikację, gdy rzeczywistość się różni. Waliduj przed scaleniem. Gdy łańcuch działa, otrzymasz mniej dryfu, mniejsze weryfikowalne diffy i trwały zapis intencji, który przetrwa resety sesji i przejęcia zespołowe.

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

Przydatne linki

Subskrybuj

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