Spec driven development z agentami kodującymi

Czym jest spec driven development, a czym nie jest

Spec driven development, czyli programowanie oparte na specyfikacji, to sposób pracy z agentami kodującymi, w którym każda istotna zmiana zaczyna się od krótkiej, spisanej specyfikacji. Opisuje ona problem, zakres i wyłączenia z zakresu, kryteria akceptacji, ograniczenia oraz plan testów. Agent planuje i implementuje na jej podstawie, w review wynik sprawdza się właśnie względem niej, a sama specyfikacja leży w repozytorium obok kodu.

To praktyka dla pojedynczych zmian. W modelu kaskadowym wymagania całego projektu zamrażano, zanim ktokolwiek napisał kod. Tutaj specyfikacja obejmuje jedną zmianę i jest poprawiana, gdy tylko implementacja pokaże, że była błędna.

Nie oznacza to też dokumentu projektowego dla każdej zmiany. Specyfikacja ma rozmiar swojej zmiany: kilka linijek dla zamkniętej poprawki, strona dla funkcji obejmującej kilka serwisów, nic dla literówki.

Birgitta Böckeler z Thoughtworks wyróżnia trzy poziomy: spec-first, gdzie specyfikacja prowadzi jedno zadanie i potem można ją odłożyć, spec-anchored, gdzie zostaje na potrzeby kolejnych zmian w danej funkcji, oraz spec-as-source, gdzie ludzie edytują wyłącznie specyfikację. Zalecamy zacząć od spec-first, a specyfikacje utrzymywać na stałe dla tych części systemu, które często się zmieniają.

Dlaczego to ważne, gdy kod piszą agenci

Agent pracuje na tym, co dostanie. Tam, gdzie polecenie coś pomija, wypełnia lukę wiarygodnym założeniem, a wiarygodne założenia trudno wyłapać w review, bo kod wygląda rozsądnie. Specyfikacja oddaje te decyzje człowiekowi, zanim praca się zacznie: których endpointów dotyczy zmiana, które zachowanie nie może się zmienić, co zobaczy klient, gdy coś pójdzie nie tak.

Dzięki specyfikacji w review da się też sprawdzić, czy zmiana robi to, co miała robić. Bez niej recenzent odtwarza cel zmiany z diffu i z sesji czatu, której nigdy nie widział. Z nią sprawdza, czy każde kryterium akceptacji ma test, a resztę uwagi poświęca temu, czego testy nie pokażą.

To ona sprawia też, że delegowanie pracy ma sens. Zadanie, które da się przekazać na piśmie, z kryteriami ukończenia, które recenzent sprawdzi bez odtwarzania sesji, może trafić do agenta działającego w tle. Wszystko, czego nie da się tak jasno opisać, lepiej zostawić w trybie interaktywnym.

• Agent dostaje zakres, wyłączenia i ograniczenia, które inaczej musiałby zgadywać
• Recenzent dostaje kryteria, względem których sprawdza diff
• Zespół zachowuje zapis tego, dlaczego kod działa tak, a nie inaczej
• Kolejna sesja dziedziczy kontekst, który przetrwał koniec czatu

Jedna zmiana od specyfikacji do zweryfikowanego merge'a

Weźmy zwykłą zmianę: twoje publiczne API ma endpoint do resetu hasła bez żadnego limitu, a skrypty używają go do masowej wysyłki maili resetujących. Rozwiązaniem jest rate limiting, a specyfikacja mniej więcej takiej wielkości w zupełności wystarczy.

# Rate limit for POST /v1/password-reset

## Problem
No limit today. Scripts use the endpoint to send reset emails in bulk.

## Scope
- Limit requests per email address and per client IP
- Return 429 with a Retry-After header when a limit is hit

## Non-goals
- Limits on other endpoints, CAPTCHA, changes to the email itself

## Acceptance criteria
1. 4th request for one email within 15 minutes returns 429
2. 21st request from one IP within 15 minutes returns 429
3. Responses do not reveal whether an account exists
4. Every 429 is logged with a hashed email and the client IP

## Constraints
- Counters in the existing Redis cluster, limits configurable without a deploy

## Test plan
- Integration tests for criteria 1 to 4 against a local Redis
- Load test in staging: added p95 latency below 5 ms

1. 1

   Napisz i uzgodnij specyfikację

   Inżynier szkicuje specyfikację na podstawie ticketu, z agentem albo bez niego, a ktoś, kto zna system, czyta ją, zanim cokolwiek zostanie zaplanowane. Najwięcej uwagi wymagają wyłączenia z zakresu i kryteria akceptacji, bo właśnie tam agent inaczej by zgadywał.

2. 2

   Niech agent zaplanuje, a ty sprawdź plan

   Agent czyta specyfikację i odpowiedni kod, po czym proponuje plan: w którym miejscu ścieżki obsługi żądania stoi limiter, jak budowane są klucze liczników, co zmienia się w konfiguracji. Człowiek akceptuje plan albo odsyła go do poprawy. Poprawka planu zajmuje minuty, a poprawka gotowego kodu cały cykl review.

3. 3

   Podziel plan na zadania

   Każde zadanie kończy się stanem, w którym build przechodzi, a testy są zielone, żeby pracę dało się w każdej chwili sprawdzić albo przerwać. Tutaj oznacza to limiter z konfiguracją, odpowiedź 429 z logowaniem i test obciążeniowy.

4. 4

   Implementuj z testami wynikającymi z kryteriów

   Agent pisze test dla każdego kryterium akceptacji razem z kodem, najlepiej przed nim. Kryterium, którego nie da się zamienić w test, trzeba przeformułować albo oznaczyć jako kontrolę ręczną z przypisaną osobą.

5. 5

   Zweryfikuj względem kryteriów akceptacji

   Uruchom cały zestaw testów i sprawdź każde kryterium względem testu, który je pokrywa. Jeśli twój framework każe agentowi porównać pracę ze specyfikacją, traktuj to jako pierwsze przejście, bo agent ocenia wtedy własną pracę.

6. 6

   Review i merge

   Pull request zawiera specyfikację albo link do niej. Recenzent sprawdza zakres i wyłączenia względem diffu, potwierdza, że każde kryterium ma przechodzący test, i czyta kod pod kątem tego, czego testy nie pokażą, na przykład jak budowane są klucze liczników. Ochrona gałęzi i wymagane checki obowiązują jak zwykle.

7. 7

   Utrzymuj specyfikację w aktualności

   Po merge'u specyfikacja staje się częścią opisu systemu albo zostaje jako datowany zapis zmiany, zależnie od tego, co ustalono dla repozytorium. Gdy zachowanie zmieni się później, zaktualizuj specyfikację w tym samym pull requeście, bo specyfikacja sprzeczna z kodem wprowadza w błąd każdego agenta, który ją czyta.

Czym różnią się Spec Kit, OpenSpec, BMad, GSD i Kiro

Te narzędzia trzymają artefakty w Markdownie w twoim repozytorium i sterują agentem przez slash commands albo skills. Różnią się procesem, tym, co dzieje się ze specyfikacją po merge'u, i obsługiwanymi agentami. Każde sprawdziliśmy w październiku 2026 roku w jego własnym repozytorium lub dokumentacji. Nowe wersje wychodzą często, więc sprawdź ponownie, zanim przyjmiesz jedno z nich jako standard.

GitHub Spec Kit

Spec Kit to otwartoźródłowy zestaw narzędzi od GitHuba, instalowany jako narzędzie wiersza poleceń w Pythonie. Po jednorazowym spisaniu konstytucji z zasadami projektu każda funkcja przechodzi kroki specify, plan, tasks, implement i converge, przy czym dwa ostatnie powtarza się, aż krok converge zgłosi status Converged. Doprecyzowanie, checklisty i analiza spójności to opcjonalne bramki. Lista integracji obejmuje ponad 40 agentów, w tym Claude Code, Codex CLI, Cursor, GitHub Copilot i Gemini CLI.

OpenSpec

OpenSpec, pakiet npm od Fission AI, określa się jako elastyczny, iteracyjny i przeznaczony zarówno dla istniejącego kodu, jak i dla nowych projektów. Obecne zachowanie systemu opisuje katalog openspec/specs, a każda zmiana dostaje folder w openspec/changes z propozycją, specyfikacjami delta, projektem i zadaniami. Specyfikacje delta zapisują tylko, które wymagania dochodzą, zmieniają się lub znikają, a archiwizacja zakończonej zmiany scala je z głównymi specyfikacjami. Domyślna pętla to propose, apply i archive, a obsługiwanych narzędzi jest ponad 30.

BMad Method

BMad Method jest darmowa, na licencji MIT i dystrybuowana jako skills dla agentów, obecnie w wersji 6, a wersja 7 jest w przygotowaniu. Jej skills planistyczne tworzą, zależnie od potrzeb, product brief, PRD, projekt UX, architekturę albo specyfikację, a skill do ticketów układa większą pracę w stories. Implementacja przechodzi przez jeden skill budujący, jedna sesja na jednostkę pracy. Wymaga narzędzia obsługującego skills, a instaluje się ją przez Skills CLI albo marketplace'y pluginów w Claude Code i Codex.

GSD Core

GSD Core kontynuuje projekt publikowany wcześniej jako Get Shit Done i jest utrzymywany przez Open GSD na licencji MIT. Każda faza kamienia milowego przechodzi kroki discuss, plan, execute, verify i ship, przy czym ciężką pracę wykonują subagenci startujący ze świeżym kontekstem, a decyzje trafiają do plików takich jak CONTEXT.md i STATE.md. Są osobne punkty wejścia dla nowych projektów i istniejących baz kodu, lżejsze polecenia dla małych zadań oraz instalator dla Claude Code, OpenCode, Codex, GitHub Copilot, Cursor i innych.

Specyfikacje w Kiro

Kiro ma specyfikacje wbudowane w swoje IDE, CLI i wersję webową. Specyfikacja funkcji składa się z wymagań, projektu i listy zadań, przy czym punktem wyjścia mogą być wymagania albo projekt, a specyfikacja poprawki błędu startuje od opisu obecnego, oczekiwanego i niezmienionego zachowania. Wymagania zapisuje się w notacji EARS (Easy Approach to Requirements Syntax), podając warunek wyzwalający i reakcję, którą system ma dać, dzięki czemu da się je przetestować. Zadania uruchamia się pojedynczo albo falami uporządkowanymi według zależności, a Quick Spec tworzy wszystkie trzy dokumenty w jednym przebiegu, bez bramek akceptacji.

pstack dla Cursora

pstack, plugin do Cursora autorstwa Lauren Tan z repozytorium cursor/plugins, podchodzi do planowania sceptycznie i jego README mówi to wprost: nie zawiera skills do planowania, opiera się na trybie planowania w Cursorze, a autorka uważa, że najlepszą specyfikacją jest kod. Playbook planu wielofazowego, przeznaczony do pracy rozłożonej na kilka pull requestów, wymienia dla każdego z nich pliki, kroki budowy, oczekiwany efekt oraz weryfikację jednostkową, na żywo i wydajnościową. Skrypt sprawdza plan, a wykonanie czeka na zgodę operatora.

Workflowy pstack w Cursorzepstack w naszym konsultingu Cursora

Który framework pasuje do twojego zespołu

Tę decyzję podejmujemy z liderami zespołów inżynierskich na podstawie repozytoriów, używanych agentów i istniejącego procesu. Zwykle rozstrzygają ją te pytania.

• Istniejący kod czy nowy produkt: specyfikacje delta w OpenSpec i onboarding w GSD Core pasują do istniejących baz kodu, a dokumenty planistyczne BMad Method do nowego produktu, który najpierw potrzebuje PRD i architektury.
• Używani agenci: Spec Kit, OpenSpec i GSD Core obsługują wielu agentów, BMad Method każde narzędzie obsługujące skills, natomiast specyfikacje Kiro działają w Kiro, a pstack w Cursorze.
• Narzut procesu: Spec Kit ma pięć kroków na funkcję plus opcjonalne bramki, domyślna pętla OpenSpec trzy, a pozostałe mają lżejsze ścieżki dla małych zmian.
• Wiele repozytoriów: OpenSpec potrafi trzymać specyfikacje w osobnym repozytorium planistycznym, wspólnym dla kilku repozytoriów z kodem, choć ta funkcja jest jeszcze w becie.
• Przepływ danych: OpenSpec zbiera anonimowe statystyki użycia, dopóki ich nie wyłączysz, a specyfikacje trafiają do modelu twojego agenta tak samo jak kod.

Jeśli żaden nie pasuje, szablon specyfikacji w repozytorium i reguła review zaprowadzą cię daleko. Framework zaczyna się opłacać, gdy nawyk już jest, a ty chcesz mieć te same polecenia i kontrole w każdym repozytorium.

Gdzie spec driven development zawodzi

Ta praktyka zawodzi na kilka przewidywalnych sposobów. Na każdy jest prosta odpowiedź.

Za długie specyfikacje

Generowane specyfikacje szybko rosną, a długie specyfikacje recenzenci czytają po łebkach. W analizie Kiro i Spec Kit dla martinfowler.com z października 2025 roku Birgitta Böckeler opisuje drobny błąd, z którego krok wymagań w Kiro zrobił cztery user stories z szesnastoma kryteriami akceptacji, i pisze, że przy Spec Kit wolałaby recenzować kod niż cały ten Markdown. Narzędzia od tego czasu się zmieniły, ale wniosek pozostaje: specyfikacja powinna zawierać tylko to, co recenzent faktycznie sprawdzi.

Specyfikacje rozjeżdżające się z kodem

Specyfikacja, której nie zaktualizowano po zmianie zachowania, z pełnym przekonaniem opisuje coś, czego już nie ma, a następny agent bierze ją za fakt. Zmieniaj specyfikację w tym samym pull requeście co kod i włącz to do swojej definicji ukończenia.

Kryteria akceptacji bez testów

Kryterium w rodzaju „wystarczająco szybko” nie da się sprawdzić, więc każde potrzebuje obserwowalnego wyniku oraz testu albo nazwanej kontroli ręcznej. Böckeler widziała też, jak agent w Spec Kit potraktował notatki o istniejących klasach jak nową specyfikację i wygenerował te klasy ponownie, tworząc duplikaty. Specyfikacje ograniczają zgadywanie, ale nie gwarantują, że agent się do nich zastosuje, więc weryfikacja pochodzi z testów i review wykonanego przez człowieka.

Narzut procesu przy małych zmianach

Pełna sekwencja dla jednolinijkowej poprawki kosztuje więcej, niż daje, i frameworki to przyznają. BMad Method kieruje małe, jasne zmiany prosto do kroku build, Kiro oferuje Quick Spec bez bramek akceptacji, GSD Core ma lżejsze polecenia dla małych zadań, a playbook planowania w pstack każe pominąć plan, gdy rozwiązanie jest oczywiste. Ustal, które rodzaje zmian wymagają specyfikacji, a resztę puszczaj normalnym procesem.

Jak wprowadzić spec driven development w zespole

Wprowadzamy tę praktykę po jednym rodzaju zmian. Działa w ramach procesu, który twój zespół już ma.

1. 1

   Wybierz jeden rodzaj zmian

   Wybierz zmiany częste, dobrze odgraniczone i testowalne, na przykład nowe endpointy API albo reguły walidacji. Wszystko inne na razie idzie dotychczasowym procesem.

2. 2

   Dodaj szablon specyfikacji do repozytorium

   Ogranicz go do sześciu nagłówków z przykładu i wskaż go w instrukcjach dla agenta, w AGENTS.md lub odpowiedniku w twoim narzędziu. Szablony frameworka mogą go później zastąpić.

3. 3

   Recenzuj specyfikacje przed kodem

   Drugi inżynier czyta specyfikację, zanim agent zacznie planować, w pull requeście albo w tickecie. Przy zmianach we wspólnym kodzie recenzuj też plan.

4. 4

   Powiąż kryteria z kontrolami

   Wprowadź regułę review, że każde kryterium akceptacji ma przypisany test albo nazwaną kontrolę ręczną. Tam, gdzie to tanie, niech CI sprawdza, czy zmiany tego rodzaju zawierają specyfikację.

5. 5

   Mierz na własnej pracy

   Po kilku tygodniach porównaj zmiany zrobione ze specyfikacją z podobnymi zmianami bez niej: liczbę rund review, poprawki po merge'u, czas od ticketu do merge'a. Przejdź do kolejnego rodzaju zmian tylko wtedy, gdy porównanie za tym przemawia.

Jak pomaga Cloudsail

Prowadzimy warsztaty spec driven development dla zespołów inżynierskich w ich własnych repozytoriach, na zmianach z ich backlogu. Inżynierowie piszą specyfikacje dla prawdziwej pracy, recenzują plany agenta i sprawdzają wyniki względem kryteriów akceptacji. Warsztaty odbywają się zdalnie albo na miejscu w Niemczech i w Polsce, po angielsku, niemiecku lub polsku. Nie prowadzimy otwartych kursów i nie wystawiamy certyfikatów.

Wokół warsztatów konfigurujemy to, od czego ta praktyka zależy: szablon specyfikacji i instrukcje dla agentów w twoich repozytoriach, polecenia builda i testów, które agent potrafi uruchomić, reguły review oraz, jeśli chcesz, framework skonfigurowany dla twoich agentów. Potem mierzymy efekt na twoich własnych zmianach, zanim praktyka obejmie kolejne zespoły.

Harness engineeringWdrażanie agentów kodującychSzkolenia Claude Code