Spec-Driven Development — metodologia produkcyjnej pracy z AI

TL;DR: Spec-Driven Development (SDD) to przeciwieństwo "vibe codingu". Zamiast mówić AI "zrób mi apkę", najpierw budujemy specyfikację (PRD, roadmapę, taski), recenzujemy je w zespole, a dopiero potem zlecamy implementację. W praktyce to kluczowa metodologia: pozwala utrzymać jakość produkcyjną w projektach budowanych z AI, uniknąć "doom loops" i zapewnić powtarzalność wyników.

TL;DR

Spec-Driven Development (SDD) to przeciwieństwo "vibe codingu". Zamiast mówić AI "zrób mi apkę", najpierw budujemy specyfikacje (PRD, roadmapę, taski), recenzujemy je w zespole, a dopiero potem zlecamy implementacje. W praktyce to kluczowa metodologia -- pozwala utrzymać jakość produkcyjna w projektach budowanych z AI, uniknąć "doom loops" i zapewnić powtarzalność wyników.

Kluczowe koncepcje

Problem z vibe codingiem

"W cloud codzie możemy powiedzieć 'zbuduj mi to i chcę odnieść sukces'. Tylko ze kurczak to się nie uda. Jeszcze dzisiaj patrząc na te możliwości modeli. Trzeba podejść do tej implementacji w sposób, który daje maksymalnie dobre efekty."

Vibe coding to:

• "Zrób mi apkę" -> enter
• "To mi nie działa" -> enter
• "Nadal nie działa" -> enter
• -> Doom loop (agent przepisuje wszystko, wraca do starych pomysłów)

"Rok temu wyrywałem sobie włosy z głowy i potrafiłem spędzić całe noce, całe dnie i nic z tego nie było. Zdarzało mi się pomysły wyrzucić do kosza."

"Sporo jest kontrowersji dookoła tego vibe codingu i ostatnio coraz więcej zespołów ma dość dobre doświadczenia z tak zwanym Speckit."

Spec-Driven Development -- definicja

"Spec Driven Development to takie podejście, gdzie rozdzielamy prace na specyfikacji od docelowej implementacji. Bardzo mocno pracujemy na tak zwanym kontekście tego projektu. Budujemy dokumentacje, specyfikacje, zadania najczęściej w postaci plików Markdown, które tworzymy, oceniamy, przeglądamy nawet zespołowo."

Trzy filary SDD:

• Specyfikuj -- tworzenie PRD, roadmapy, tasków ZANIM zaczniesz kodować
• Recenzuj -- zespołowy review specyfikacji (nie auto-apply!)
• Implementuj -- dopiero teraz AI koduje, ale na podstawie specyfikacji

Plan Mode -- pierwszy krok

Claude Code ma wbudowany tryb planowania:

"Jeżeli zmienimy tryb konwersacji Shift+Tab na plan mode on, to Claude Code zacznie działać inaczej. Nie zrobi apki, tylko najpierw zrobi plan na stworzenie tej apki."

Ale Plan Mode to dopiero początek -- bardziej zaawansowane podejścia to Open Spec i Speckit.

Speckit -- narzędzie od GitHuba

"Speckit to narzędzie od samego GitHuba, które umożliwia ustawienie naszego vibe codingu w specjalnych szynach techniczno-funkcjonalnych."

Jak działa Speckit:

• Konstytucja -- definiujesz co jest ważne: specyfikacje, prosty UX, workflow
• Development workflow -- najpierw specyfikujemy, planujemy, rozpisujemy taski
• Specyfikacja -- mówisz "dodaj możliwość dodawania todusów", Speckit rozpisuje user stories
• Planowanie -- AI wybiera stack, planuje implementacje, zadaje pytania
• Implementacja -- dopiero na końcu

"Te specyfikacje, które robi ten Speckit są bardzo dobre. Gdybym ja jako junior miał dostęp do takich narzędzi 10 lat temu, to naprawdę bym spędził dużo mniej czasu na pisanie 40-stronicowych dokumentów user stories."

Open Spec -- otwartoźródłowa alternatywa

w szczegółowo pokazał Open Spec w połączeniu z Tenex Astro Starter:

Trzy kluczowe komendy:

• /opsx propose -- proponowanie nowej funkcjonalności
• Bada projekt (faza research)
• Buduje specyfikacje biznesowa i techniczna
• Tworzy czteropunktowy plan do zatwierdzenia
• Buduje mini-bazę wiedzy o domenie

• /opsx apply -- implementacja zatwierdzonej specyfikacji
• Realizuje taski z checklisty
• Oznacza ukończone elementy

• /opsx archive -- archiwizacja ukończonej delty
• Przenosi do archiwum
• Aktualizuje bazę wiedzy projektu

"W Spec Driven Development bardzo mocno kładziemy nacisk na to, żeby nie tylko generować kod, ale pracować na specyfikacji, żeby ta specyfikacja była oceniana przez zespoły."

Roadmapa -- brakujący element

zauważyć, że sam PRD i Open Spec to za mało -- potrzebna jest roadmapa:

"Jeżeli w Open Spec wrzucicie po prostu PRD, to pierwszym elementem specyfikacji może być wszystko. Bardzo trudno to przewidzieć."

Rozwiązanie: skill /roadmapit który tworzy roadmapę z konkretnymi zasadami:

• Każda faza = maks. 5 dni roboczych
• Każda faza = inkrementbiznesowy (nie "dzisiaj baza, jutro API")
• Full-stackowe podejście -- użytkownik widzi wartość po każdej fazie

"Pierwsza faza -- użytkownik już może przeglądać listingi w mieście. Nie jest tak, że użytkownik wie, że jest baza danych w tym projekcie, bo jego to nie interesuje."

PRD -- Product Requirements Document

Metoda budowania PRD :

• Metaprompting -- 3 subagentów tworzy 3 różne prompty do PRD
• Synteza -- Claude wyciąga najlepsze elementy z każdego
• Skill -- najlepszy prompt zostaje zapisany jako skill /prd
• Metoda sokratejska -- skill prowadzi wywiad (pyta, nie generuje od razu)
• Testowanie -- dwa Claude Code w osobnych terminalach testują PRD automatycznie

Metoda z Cowork :

"Chciałbym, żebyś napisał PRD platformy treningów online. Generalnie platforma ma dotyczyć treningów online, gdzie ludzie mogą trenować w domu z trenerem personalnym. Zależy mi na tym, żeby platforma miała prosty stak technologiczny."

Porównanie wyników: Claude Sonet vs Gemini -- Sonet generował znacznie bardziej szczegółowe PRD z user stories, strukturami danych i rekomendacjami technicznymi.

Pełny flow od problemu do produkcji

Demo z pokazało pełny sprint produktowy:

• Analiza danych -- CSV z retencją użytkowników -> Claude Code analizuje, znajduje "ścianę śmierci" po 14 dniach
• Research konkurencji -- skill /research -> analiza Duolingo, Strava, Peloton -> raport z priorytetami (MoSCoW)
• Rekomendacja -- "Mechanizm strików z wizualizacją postępu"
• Design -- MCP Pencil -> nowy ekran UI na podstawie design systemu
• Implementacja -- prompt "dodaj do mojej aplikacji design z Pencil" -> kod
• Wynik -- działający feature gotowy do AB testu

"To co wam pokazaliśmy to taki pełny produktowy sprint od rozpoznania problemu z użytkownikami przez research po prototypowanie, design i tworzenie końcowego produktu."

Legacy projekty -- jak stosować SDD

"Skala projektu nie jest aż tak kluczowa jak jego stan. AI ma taka zaletę i wadę, że dość mocno podąża za paternami, które widzi w naszym projekcie."

Rekomendacja:

• Refaktoryzacja -- najpierw napraw moduł, z którym pracujesz
• Dokumentacja per moduł -- nie jeden PRD na cały projekt, ale dedykowany per moduł
• Linkowanie -- poszczególne dokumenty linkują do architektury wyższego poziomu
• Zoom out -- na legacy robisz wycinek tego co pokazują na greenfield

"Przy dużym projekcie nie jesteśmy w stanie stworzyć jednego dokumentu, który opisze dla AI cała aplikację. Musimy to robić w sposób dedykowany per moduł."

Tenex Astro Starter -- szablon projektowy

Z -- repozytorium template na GitHubie od 10x Devs:

"Szablon, który my z kilkunastu miesięcy rozwijamy i ono służy temu, żeby rozwijać na jego podstawie produkty webowe, ale też żeby praca z AI w ramach tego repozytorium była łatwa, przyjemna, bardziej efektywna."

Zawiera:

• Skonfigurowany Open Spec
• CLAUDE.md
• Skrypty inicjalizacyjne
• Astro framework gotowy do pracy

Testy -- część SDD

"Kiedy robimy to w sposób naiwny pod tytułem 'napisz mi testy', to zwykle te testy nie są najwyższej jakości. Ale jeżeli przygotujemy sobie testing guide i jakiegoś dobrego prompta, to naprawdę jakościowe testy możemy dowozić."

"AI wykorzystywany świadomie nie tylko poważnie pomaga nam szybciej dowozić kod, ale też szybciej pozwala nam dowozić jakość, której często po prostu brakowało."

Jak to wdrożyć

• Wdrożyć Open Spec lub Speckit jako standard pracy z Claude Code w każdym projekcie
• Stworzyć firmowy skill /bee-prd do tworzenia PRD (z metodą sokratejską)
• Stworzyć skill /bee-roadmap do roadmap z limitami 5-dniowych faz
• Zabronić "zrób mi apkę" jako sposób pracy -- każdy projekt zaczyna od specyfikacji
• Wdrożyć review specyfikacji przed implementacją (nie auto-apply!)
• Przygotować testing guide jako plik kontekstowy -- nie "napisz testy", ale "napisz testy według testing guide"
• Użyć Tenex Astro Starter jako bazowy template dla nowych projektów lub stworzyć własny "zespół Starter"
• Dla legacy projektów: dokumentacja per moduł + refaktoryzacja przed nowa funkcjonalnością
• Przeszkolić PM-ow z tworzenia PRD w Claude Code (metoda sokratejska)

Narzędzia i komendy

Open Spec -- komendy

# Inicjalizacja Open Spec w projekcie
/opsx init

# Propozycja nowej funkcjonalności (na podstawie roadmapy)
/opsx propose
# Prompt: "First phase of this roadmap" + wskazanie roadmap.md

# Implementacja zatwierdzonej specyfikacji
/opsx apply

# Archiwizacja ukończonej funkcjonalności
/opsx archive

Speckit -- konfiguracja

# Instalacja Speckit
npx create-speckit@latest

# Pliki generowane przez Speckit:
# - constitution.md (konstytucja projektu)
# - specs/ (folder specyfikacji)
# - tasks/ (rozbite taski)

Plan Mode w Claude Code

# Przełączenie na tryb planowania
Shift+Tab -> Plan Mode ON

# W Plan Mode Claude:
# - NIE pisze kodu
# - Tworzy plan implementacji
# - Czeka na twoja akceptację/krytykę
# - Dopiero po zatwierdzeniu przechodzi do kodu

Struktura SDD w projekcie

projekt/
├── CLAUDE.md # Konstytucja projektu
├── ai/
│ ├── prd/
│ │ └── prd-final.md # PRD (wynik metapromptingu)
│ ├── roadmap.md # Roadmapa (fazy po 5 dni)
│ ├── competitive-research.md # Research konkurencji
│ └── specs/ # Specyfikacje Open Spec
│ ├── 001-listing/
│ │ ├── proposal.md # Co budujemy
│ │ ├── design.md # Jak technicznie
│ │ ├── tasks.md # Checklista tasków
│ │ └── knowledge.md # Baza wiedzy domeny
│ └── archive/
│ └── ...
├── .claude/
│ └── skills/
│ ├── prd.md # Skill do tworzenia PRD
│ ├── roadmapit.md # Skill do roadmap
│ └── research.md # Skill do researchu
└── src/
 └── ...

Przykładowy workflow SDD

KROK 1: PRD
> /prd
> [Claude zadaje pytania o produkt]
> [Generuje PRD do ai/prd/prd-final.md]

KROK 2: Roadmapa
> /roadmapit
> [Czyta PRD, tworzy 5-dniowa roadmapę]
> [Zapisuje do ai/roadmap.md]

KROK 3: Specyfikacja (powtórz dla każdej fazy)
> /clear
> /opsx propose
> "First phase of roadmap in ai/roadmap.md"
> [Review specyfikacji z zespołem]

KROK 4: Implementacja
> /clear
> /opsx apply
> [Claude implementuje na podstawie specyfikacji]

KROK 5: Archiwizacja
> /opsx archive
> [Przejście do kolejnej fazy]

Inne narzędzia SDD wymienione w filmach

Poważne ostrzeżenia

• Nigdy auto-apply bez review -- specyfikacja musi być przeglądana przez człowieka
• Nie pomijaj roadmapy -- bez niej Open Spec może zacząć od czegoś losowego
• Clear między fazami -- każde zadanie w czystym kontekście
• SDD nie znaczy wolniej -- początkowo tak, ale unikasz doom loops i przepisywania od zera
• Testy też potrzebują specyfikacji -- testing guide zamiast "napisz testy"

"To jest lekarstwo na vibe coding. Zrób mi apkę -- ale co ważne, działa."

Powiązane tematy

• 01-podstawy -- Instalacja i komendy Claude Code
• 02-context-engineering -- Pliki kontekstowe (CLAUDE.md, skille, PRD)
• 03-mcp-serwery -- MCP jako element workflow (Pencil, Figma)