Spec-driven development (programowanie sterowane specyfikacją) to sposób pracy z AI, w którym najpierw opisujesz w pliku, co ma powstać i jak sprawdzisz, że jest gotowe, a dopiero potem agent pisze kod według tej specyfikacji. Różni się od vibe codingu tym, że pracujesz według zatwierdzonego planu, a nie improwizujesz kolejnymi poleceniami. Najlepiej sprawdza się w projektach, które mają być utrzymywane, a przy małych prototypach bywa zbyt ciężki.
Vibe coding jest szybki: opisujesz, co chcesz, a agent pisze kod. Problem zaczyna się, gdy projekt rośnie, a nikt (łącznie z tobą) nie pamięta, co właściwie miało być zbudowane i według jakich zasad. Spec-driven development (SDD) odwraca kolejność: najpierw ustalasz, co ma powstać, dopiero potem zlecasz napisanie kodu. W artykule o tym, czym jest vibe coding, opisuję jego ryzyka. Tu pokazuję, jak je ograniczyć dobrym planem.
Czym jest spec-driven development?
Spec-driven development to praca z agentem AI według specyfikacji (spec): dokumentu, w którym opisujesz cel, wymagania i kryteria, po których poznasz, że zadanie jest skończone. Specyfikacja jest zwykłym plikiem tekstowym, najczęściej w Markdownie, trzymanym w repozytorium razem z kodem. Agent czyta ją jako źródło prawdy, a ty możesz ją przejrzeć i poprawić zanim powstanie pierwsza linijka kodu.
Typowy przebieg składa się z trzech kroków:
- Wymagania: co ma robić funkcja i dla kogo, wraz z kryteriami akceptacji (acceptance criteria).
- Projekt: jak to zbudować (jakie pliki, dane, zależności).
- Zadania: lista małych kroków, które agent wykonuje po kolei.
Po każdym kroku to ty zatwierdzasz wynik, a nie agent.
Czym różni się spec-driven development od vibe codingu?
| Vibe coding | Spec-driven development | |
|---|---|---|
| Punkt startu | Polecenie w czacie | Plik ze specyfikacją |
| Kto ustala szczegóły | Agent, domyślnie | Ty, przed kodowaniem |
| Sposób sprawdzania | „Działa?” | Czy spełnia kryteria akceptacji |
| Szybkość na starcie | Bardzo wysoka | Wolniejsza (trzeba napisać spec) |
| Utrzymanie po miesiącu | Trudne, brak dokumentacji | Łatwiejsze, spec zostaje w repozytorium |
| Najlepsze zastosowanie | Prototyp, eksperyment | Projekt, który ma żyć dłużej lub powstaje w zespole |
To nie jest wybór „albo-albo”. Wiele osób zaczyna od luźnego prototypu, a gdy pomysł się sprawdzi, przechodzi na specyfikację. Narzędzie Kiro od AWS wprost pozwala przełączać się między trybem swobodnym i trybem ze specyfikacją.
Jak wygląda prosta specyfikacja dla agenta AI?
Załóżmy, że chcesz dodać do aplikacji zapis na newsletter. Zamiast napisać w czacie „dodaj newsletter”, zapisujesz plik specs/newsletter.md:
# Zapis na newsletter
## Cel
Odwiedzający może zapisać swój adres e-mail na listę, a my zapisujemy go w bazie.
## Wymagania
- Formularz ma jedno pole: e-mail.
- Endpoint POST /subscribe przyjmuje JSON {"email": "..."}.
- Ponowny zapis tego samego adresu jest bezpieczny: nie tworzy drugiego wpisu.
## Kryteria akceptacji
- Poprawny e-mail: odpowiedź 201 i nowy wpis w bazie.
- Niepoprawny e-mail (bez @): odpowiedź 422, brak wpisu.
- Duplikat: odpowiedź 200, nadal jeden wpis.
## Poza zakresem (out of scope)
- Wysyłka potwierdzenia e-mail.
- Panel administratora.
## Zadania
1. Dodać model i tabelę subscribers.
2. Dodać endpoint z walidacją.
3. Napisać testy dla trzech kryteriów akceptacji.
Zwróć uwagę na trzy elementy. Kryteria akceptacji są mierzalne, więc łatwo je zamienić w testy. Sekcja poza zakresem mówi agentowi, czego nie ma robić, więc nie dopisze panelu administratora, o który nikt nie prosił. A zadania dzielą pracę na małe, możliwe do sprawdzenia kroki. Potem możesz powiedzieć agentowi: „Zrealizuj zadanie 1 ze specyfikacji specs/newsletter.md i nic poza nim”.
Jakie narzędzia wspierają spec-driven development?
Metodę możesz stosować z dowolnym agentem, nawet bez specjalnego narzędzia: wystarczy plik i dyscyplina. Są jednak narzędzia, które ten przepływ porządkują:
| Narzędzie | Co to jest | Jak wygląda przepływ |
|---|---|---|
| GitHub Spec Kit | Otwarty toolkit na licencji MIT, który dostarcza szablony i komendy dla agenta | constitution (zasady projektu), specify, plan, tasks, implement, converge (uruchamiane jako komendy /speckit-… w agencie) |
| Kiro | Narzędzie AWS (IDE i CLI) zbudowane wokół specyfikacji | Trzy pliki: requirements.md, design.md, tasks.md, z akceptacją każdej fazy |
Spec Kit instalujesz w terminalu (potrzebny jest Python 3.11+ i menedżer uv):
uv tool install specify-cli
specify init my-project --integration copilot
Jeśli terminal jest dla ciebie nowy, zacznij od artykułu o terminalu i wierszu poleceń dla początkujących. W Kiro każdą z trzech faz zatwierdzasz osobno, a wariant „Quick Spec” generuje wszystkie pliki naraz, bez bramek akceptacji, co jest szybsze, ale oddaje kontrolę agentowi. Przegląd samych agentów kodujących znajdziesz w artykule o narzędziach AI dla programistów.
Jak spec-driven development wiąże się z testami i code review?
Dobra specyfikacja działa jak zamówienie na testy. Kryterium „niepoprawny e-mail zwraca 422” zamieniasz w test, zanim agent napisze endpoint, a potem oceniasz kod według jednej miary: czy test przechodzi. Przykłady testowania znajdziesz w artykule o testowaniu kodu z API LLM w pytest. Specyfikacja ułatwia też code review: recenzent porównuje zmianę z tym, co zostało uzgodnione, zamiast zgadywać intencje. Ogranicza to też ryzyko luk i halucynacji, o których piszę w artykułach o bezpieczeństwie kodu generowanego przez AI i halucynacjach AI w kodzie, bo masz jasno opisane wymagania, na których oprzesz przegląd.
Kiedy spec-driven development ma sens, a kiedy jest przesadą?
Warto, gdy:
- projekt ma żyć dłużej niż kilka dni i będziesz do niego wracać,
- pracujesz w zespole i inni muszą zrozumieć, co zbudowałeś,
- funkcja dotyczy danych, płatności lub bezpieczeństwa, gdzie błąd kosztuje,
- agent ma pracować dłużej samodzielnie, a ty chcesz sprawdzić wynik jednym testem.
Nie warto, gdy:
- robisz jednorazowy prototyp lub eksperyment,
- zmiana jest bardzo mała (poprawka literówki, zmiana koloru),
- sam jeszcze nie wiesz, czego chcesz: wtedy najpierw poeksperymentuj, a specyfikację napisz, gdy pomysł się wyklaruje.
Pamiętaj też, że więcej opisu nie zawsze znaczy lepiej. W badaniu zespołu z ETH Zurich dotyczącym plików kontekstowych dla agentów autorzy stwierdzili, że takie pliki nie poprawiają ogólnie skuteczności agenta, za to zwiększają koszt wnioskowania średnio o ponad 20%. Przydają się do niestandardowych zasad projektu, a nie do długich opisów repozytorium. Dlatego pisz specyfikację krótko i konkretnie.
Jak pisać specyfikację, żeby naprawdę pomagała?
Dwie wskazówki, które robią największą różnicę, szczególnie gdy się uczysz.
1. Jeśli nie umiesz napisać kryteriów akceptacji, to jeszcze nie rozumiesz zadania. Próba zapisania ich pokazuje luki w twoim myśleniu: co ma się stać przy pustym polu, przy duplikacie, przy błędzie sieci? Jeśli nie znasz odpowiedzi, zadaj to pytanie mentorowi albo sobie, zanim poprosisz agenta o kod. W ten sposób specyfikacja jest także ćwiczeniem z myślenia o problemie, a nie tylko instrukcją dla AI.
2. Napisz sekcję „poza zakresem” od razu. Agenci chętnie dodają coś ekstra: panel administratora, logowanie, dodatkowe pola. Jedno zdanie w stylu „Poza zakresem: wysyłka e-maili i panel administratora” zatrzymuje te rozszerzenia dużo wcześniej niż przegląd diffa. Wpisanie jej dopiero po tym, jak agent dopisze niechciane funkcje, oznacza cofanie zmian zamiast ich unikania.
Od czego zacząć ze spec-driven development?
- Wybierz małą funkcję (formularz, jeden endpoint).
- Napisz specyfikację w jednym pliku: cel, wymagania, kryteria akceptacji, poza zakresem, zadania.
- Przeczytaj ją jako recenzent: czy każde kryterium da się sprawdzić testem?
- Zleć agentowi jedno zadanie naraz i po każdym przeglądaj diff oraz uruchom testy.
- Gdy rzeczywistość różni się od spec, popraw specyfikację, a nie tylko kod. Specyfikacja ma zostać aktualna.
Podsumowanie: czym jest spec-driven development?
- To praca z AI według pliku ze specyfikacją, a nie według kolejnych poleceń w czacie.
- Różni się od vibe codingu tym, że to ty ustalasz plan i kryteria, zanim powstanie kod.
- Dobra specyfikacja ma cel, wymagania, mierzalne kryteria akceptacji, zakres wyłączony i listę zadań.
- Narzędzia takie jak Spec Kit i Kiro porządkują przepływ, ale metodę możesz stosować z dowolnym agentem.
- Opłaca się przy projektach, które mają żyć dłużej, a przy małych prototypach bywa przesadą.
