Spec-driven development — jak przestać vibe codować z Claude Code i zacząć dowozić

„Vibe coding” — termin ukuty przez Andreja Karpathy’ego na opisanie podejścia, w którym po prostu mówisz AI co chcesz i akceptujesz wynik bez głębszego zastanawiania się nad detalami. Brzmi jak marzenie. I przez pierwsze kilka dni z Claude Code — często jest.

Problem pojawia się przy projekcie, który ma więcej niż tydzień historii.

Dlaczego vibe coding przestaje działać

Przy małych projektach od zera vibe coding jest całkiem efektywny. Claude generuje kod, Ty akceptujesz, coś działa. Ale z każdą sesją rośnie dług decyzyjny: Claude podjął setki małych wyborów architektonicznych, których nie kontrolowałeś. Po miesiącu masz projekt, który technicznie działa, ale którego logiki sam nie rozumiesz w pełni — i przy każdej zmianie coś się psuje w nieoczekiwanym miejscu.

Sam Karpathy przyznał to publicznie — era czystego vibe codingu się kończy. Nie dlatego, że AI jest słabe, ale dlatego że projekty dorastają i wymagają struktury.

Czym jest spec-driven development

Spec-driven development to podejście, w którym zanim Claude napisze linię kodu, powstaje specyfikacja — dokument opisujący co ma być zbudowane, jak ma działać, jakie są ograniczenia i kryteria sukcesu.

Nie chodzi o 50-stronicową dokumentację techniczną. Chodzi o to, żeby decyzje architektoniczne były Twoje, nie Claude’a.

Typowa spec to: cel funkcji (co rozwiązuje), interfejs (jak się wywołuje, co zwraca), ograniczenia (czego nie robi, z czym się integruje), kryteria weryfikacji (jak wiem, że działa). Często mieści się na jednej stronie.

Frameworki, które wypracowała społeczność

Kilka podejść zyskało popularność w 2025–2026:

BMAD (Build, Measure, Analyze, Design) — cykl, w którym każda nowa funkcja przechodzi przez cztery etapy zanim Claude zacznie kodować. Szczególnie popularny przy projektach SaaS.

GitHub Spec Kit — zestaw szablonów issue i PR opisujących standard specyfikacji dla projektów używających GitHub jako centrum dokumentacji. Claude Code może bezpośrednio czytać issue i działać zgodnie z opisaną tam specyfikacją.

Podejście „spec first, code second” — najprostsze: zanim zaczniesz sesję, napisz w CLAUDE.md lub w osobnym pliku specs/feature-name.md co ma powstać. Potem zlecasz Claude’owi implementację zgodnie ze specyfikacją.

Jak to wygląda w praktyce

Przed: „Dodaj do aplikacji system notyfikacji push" — Claude decyduje o wszystkim.

Po: tworzysz plik specs/push-notifications.md:

Cel: powiadamiaj użytkownika gdy ktoś odpowie na jego komentarz.
Trigger: nowy rekord w tabeli comments z parent_id != null.
Kanał: Web Push API (bez zewnętrznych serwisów).
Obsługiwane przeglądarki: Chrome 90+, Firefox 88+, Safari 16.4+.
Nie obsługujemy: iOS przed 16.4, powiadomień e-mail (osobny ticket).
Sukces: użytkownik z aktywnym subskrybowaniem dostaje powiadomienie < 5s od zdarzenia.

Teraz dajesz Claude’owi to do przeczytania i mówisz: „Zaimplementuj zgodnie ze specyfikacją w @specs/push-notifications.md". Claude pracuje w określonych ramach, nie zgaduje intencji.

Kiedy specyfikacja jest przerostem formy

Nie każde zadanie wymaga dokumentu. Bugfix, mała poprawka, dodanie pola do formularza — to można zlecić bezpośrednio. Spec-driven development opłaca się przy funkcjach, które:

• dotykają więcej niż trzech plików,
• mają wpływ na API lub schemat bazy,
• będą rozwijane w więcej niż jednej sesji,
• są robione przez więcej niż jedną osobę (lub agenta).

Reszta — swobodnie. Chodzi o to, żeby mieć kontrolę tam, gdzie brak kontroli kosztuje.

Przejście od vibe codingu

Nie trzeba przebudowywać całego workflow naraz. Wystarczy jedno: przy następnym zadaniu, zanim napiszesz prompt do Claude’a, poświęć pięć minut na zapisanie co chcesz osiągnąć i jakie masz ograniczenia. To wystarczy, żeby zobaczyć różnicę.