Rozwój oparty na specyfikacji z Claude Code: przewodnik krok po kroku

Czym jest rozwój oparty na specyfikacji?

Rozwój oparty na specyfikacji to workflow oparty na trzech dokumentach w kolejności: dokument opisujący, co zmiana ma robić, plan określający kroki oraz kod pisany według planu, z ludzką recenzją między każdą parą etapów.

Trzy punkty przeglądu, przez które przechodzi funkcja w rozwoju opartym na specyfikacji.

Spec to krótki dokument napisany zwykłym językiem przed jakimkolwiek kodem, który mówi, co zmiana ma robić. Weź funkcję w stylu „pozwól użytkownikom eksportować swoje dane”. Spec doprecyzowuje odpowiedzi, które agent w innym wypadku musiałby zgadywać. Wymienia

• Obsługiwane formaty plików
• Sposób dostarczenia
• Zachowanie podczas niedokończonego eksportu
• Elementy celowo wyłączone z zakresu

Oto prawdziwy wstęp specyfikacji, którą Claude Code napisał dla zmiany workout-shape-verification w mojej aplikacji rozliczającej na Telegramie. Zmiana zastępuje kruchy próg tętna kontrolą kształtu krzywej tętna w czasie:

# Workout Shape-Based Verification — Design Spec
 
**Created:** 2026-05-05
**Status:** Draft
**Supersedes (partially):** [2026-03-17-calisthenics-verification-design.md]
  — replaces the absolute-HR thresholds for the Workout activity type.
  Run / Ride / Walk verification is unchanged.
 
## Problem
 
The current Workout verifier accepts an activity only if absolute heart-rate
levels clear fixed cutoffs: avg ≥ 120, max ≥ 140, range ≥ 30, suffer_score ≥ 3.
Two failures in production:
 
1. **False-negative risk.** As cardiovascular fitness improved
   (resting HR ~80), real calisthenics sessions with disciplined rest now
   average 115–125 bpm. Recent sessions have come within 4 bpm of the 120 floor.
 
<!-- ... continues for hundreds of lines through Solution, Risks,
 	Out of scope, and What is removed / added / changed / unchanged -->

Plan to kolejny dokument. Rozbija powyższą specyfikację na ponumerowane zadania, nad którymi agent może pracować jedno po drugim — każde zadanie wskazuje plik, zmianę, kolejność i test. Tam, gdzie spec odpowiada na pytanie „co”, plan odpowiada „w jakich krokach”.

Kod powstaje na końcu, pisany według planu, krok po kroku.

Trzy dokumenty. Między każdą parą jest ludzka recenzja. Recenzujesz spec, zanim stanie się planem. Recenzujesz plan, zanim stanie się kodem. Recenzujesz kod przed scaleniem.

Czym spec-driven różni się od trybu planu

Być może używałeś wbudowanego trybu planu w Claude Code (wciśnij Shift+Tab dwa razy, by go włączyć) i zastanawiasz się, czym to się różni. Tryb planu tworzy plan w ramach jednej tury czatu. Plan żyje w pamięci — bez utrwalonej specyfikacji i bez kroku recenzji między fazami.

Rozwój oparty na specyfikacji utrwala zarówno spec, jak i plan jako pliki na dysku. Każdy z nich przechodzi ludzką recenzję, zanim zacznie się następna faza, a artefakty przetrwają między sesjami. Tryb planu kompresuje dwie fazy rozwoju oprogramowania do jednej tury czatu. To działa przy małych zadaniach i zawodzi, gdy tylko baza kodu rośnie i zaczyna obsługiwać prawdziwych użytkowników.

Dlaczego vibe-coding dochodzi do ściany

Vibe-coding działa przy prototypach, pojedynczych plikach i jednorazowych skryptach. Im gorzej jest w prawdziwych aplikacjach z użytkownikami i w dużych, istniejących kodbazach. Rozsądna granica to około 4 pliki. Każda zmiana dotykająca tylu plików potrzebuje specyfikacji — podobnie jak każde refaktoryzacje z jasno określonym stanem końcowym czy każde zadanie, w którym „co to ma dokładnie robić?” jest najtrudniejszą częścią.

Przyczyna porażek jest jasna. Mętna prośba typu „dodaj udostępnianie zdjęć do mojej aplikacji” każe modelowi zgadywać tysiące niewypowiedzianych wymagań.

Weźmy jedno z nich: preferencje powiadomień. Product manager zakłada przełączniki per kanał. Backend buduje włącz/wyłącz. Frontend zakłada integrację na poziomie systemu operacyjnego. Cztery rozsądne odczyty trzech słów, cztery różne produkty.

Każdy krok recenzji w rozwoju opartym na specyfikacji wyłapuje inny rodzaj błędów, zanim staną się kosztowne. Przegląd specyfikacji łapie rozrastanie zakresu i błędne diagnozy przyczyn. Przegląd planu łapie niedokończone implementacje i sprzeczne wzorce. Przegląd kodu łapie plany, które wyglądają dobrze, ale łamią się przy pierwszym niezdanym teście.

Zwrot z inwestycji jest realny i narasta stopniowo. Faza specu kosztuje godziny pisania, zanim uruchomisz jakikolwiek kod, a pierwsze funkcje wydają się wolniejsze niż vibe-coding. U mnie punkt równowagi przyszedł przy czwartej–piątej funkcji. Wtedy specyfikacje zaczęły wyłapywać błędy projektowe, które w innym wypadku bym wysłał na produkcję i poprawiał tydzień później.

Kolejne trzy sekcje przeprowadzają przez trzy open-source’owe podejścia uruchamiające ten workflow w Claude Code. Ułożone są od najlżejszego do najcięższego pod względem narzucanej struktury.

Superpowers

Superpowers to najlżejsze z trzech rozwiązań. Tego używam na co dzień i temu poświęcimy najwięcej uwagi.

Czym jest Superpowers?

Superpowers to wtyczka do Claude Code autorstwa Jesse’ego Vincenta (obra/superpowers, MIT), z około 194 tys. gwiazdek na GitHubie.

Dostarcza zestaw umiejętnościs. Umiejętność Claude w Claude Code to nazwany plik instrukcji, który agent ładuje na żądanie, by podążać za określonym workflow. Superpowers dostarcza umiejętności, które trzymają Claude Code w pętli spec-driven zamiast pozwalać mu od razu przejść do kodu.

Strona projektu Superpowers na GitHubie.

Jak zainstalować Superpowers

Zainstaluj ją przez oficjalny marketplace wtyczek Claude Code:

/plugin install superpowers@claude-plugins-official

Hak SessionStart automatycznie ładuje umiejętność using-superpowers, więc workflow jest aktywny od momentu, gdy zaczynasz pisać. (Hooki Claude Code to skrypty uruchamiane przez agenta przy konkretnym zdarzeniu w cyklu życia). Nie trzeba niczego podłączać per projekt.

Workflow Superpowers

Później cztery umiejętności obsługują twoją codzienną pracę:

Subagent to osobna instancja Claude Code, którą nadrzędny agent wysyła do skupionej pracy w jej własnym oknie kontekstu. Recenzenci w tabeli powyżej działają jako subagenci, więc czytają kod na zimno, bez ram, które ma agent nadrzędny.

Jak używać Superpowers

Wywołujesz cztery umiejętności opisując po prostu, czego chcesz. Umiejętność brainstorming rozumie „porozmawiajmy o nowej funkcji” i sama rozpoczyna rozmowę o specyfikacji. Pozostałe działają podobnie.

Cztery umiejętności Superpowers w kolejności, z dwoma punktami ludzkiej recenzji między brainstorming a writing-plans.

Poniższy walkthrough używa tej samej funkcji workout-shape-verification z cytowanej wcześniej specyfikacji.

Etap 1: od brainstormu do specyfikacji

Otwieram Claude Code i piszę:

Let's discuss a new feature. The Workout verifier in make-me-work uses absolute heart-rate cutoffs and is now misfiring as my resting HR drops. I want to replace the absolute cutoffs with a check on the shape of the HR curve over the session.

Umiejętność brainstorming przejmuje stery i zadaje około dziesięciu pytań, m.in.:

• Co uznajemy za właściwy „kształt”
• Które strumienie danych łączyć
• Co zrobić z sesjami, które wyglądają dobrze kształtem, ale nie spełniają starego progu
• Czy zmiana powinna dotyczyć także Run i Ride

Tutaj pojawiają się dwa punkty ludzkiej recenzji. Pierwszy to przegląd projektu, w którym potwierdzam, że moje odpowiedzi zgadzają się z tym, czego chcę. Drugi to przegląd specyfikacji. Czytam plik napisany przez Claude’a i zatwierdzam go, zanim zacznie się praca nad planem.

Etap 2: od specyfikacji do planu

Uruchamiam umiejętność writing-plans. Czyta zatwierdzony spec i pisze plik planu z czterema częściami:

• Definicja „Gotowe”
• Mapa plików objętych zmianą
• Ścieżka użytkownika przez demo
• Ponumerowana lista zadań z pod-krokami na checkboxach.

Przeglądam plan, odrzucam zadania, które wydają się w złej kolejności lub zbyt grube, i zatwierdzam.

Etap 3: od planu do kodu

Uruchamiam subagent-driven-development. Od tego momentu pętla działa beze mnie. Dla każdego zadania w planie umiejętność:

1. Pisze niespełniony test
2. Pisze kod, by go zdać
3. Refaktoryzuje
4. Wysyła subagenta code review, który czyta diff na zimno

Jeśli recenzent zgłosi problem, pętla go naprawia, zanim przejdzie dalej. W tym etapie nie ma ludzkiego punktu przeglądu. Istotne recenzje to te dwa wcześniejsze etapy.

Etap 4: przegląd pełnego diffu

Gdy plan jest ukończony, uruchamiam requesting-code-review. Świeży subagent czyta cały diff względem specu i planu i publikuje recenzję. Wprowadzam sugestie przed scaleniem.

Gdy zadanie w planie ujawnia sprzeczność ze specem, pętla zatrzymuje się i pyta. Mogę edytować spec (albo pozwolić, by zrobił to Claude) i wygenerować ponownie dotknięte zadania. Druga opcja to jednorazowa korekta w samym zadaniu. Superpowers nie obchodzi po cichu błędów w specyfikacji.

Prawdziwe specyfikacje i plany na dysku

Oto spec dla funkcji workout-shape-verification, otwarty w edytorze:

Plik specyfikacji zapisany na dysku po tym, jak umiejętność brainstorming go utworzy.

Nagłówek zawiera pola Created, Status i Supersedes, które umiejętność brainstorming wpisuje domyślnie. Potem następuje sekcja Problem. To nie jest kod. Plik ciągnie się dalej poza zrzutem ekranu przez sekcje z proponowanym rozwiązaniem i ograniczeniami co do tego, czego zmiana powinna i nie powinna dotykać.

Pasujący plan otwiera się swoją sekcją User Journey:

Plik planu, który umiejętność writing-plans tworzy z zatwierdzonej specyfikacji.

Ścieżka prowadzi przez demo po pięć kroków, nazywając dokładne polecenia, pliki i argumenty na każdym etapie. Następujące po niej ponumerowane zadania przekładają każdy krok na pod-kroki checkboxów, które umiejętność subagent-driven-development może zrealizować.

Dwa dokumenty łączą się tak:

Spec i plan obok siebie. Spec odpowiada, co i dlaczego się zmienia. Plan odpowiada, w jakich krokach.

Przy większych specach i planach dodaję krok, którego oficjalna pętla nie ma: red teaming. Zanim zatwierdzę, proszę jednego lub kilku subagentów Opus, by przeczytali spec na zimno, szukając luk z różnych stron. To osobisty nawyk, nie funkcja Superpowers. Wystarczająco często wyłapywał złe założenia, że go utrzymuję.

Kiedy Superpowers nie jest dobrym wyborem

Superpowers pasuje do solo pracy nad jednym repozytorium. Najlepiej działa, gdy cała kodbaza mieści się w jednej sesji Claude Code, a ty faktycznie przeczytasz 2-stronicowy spec. Szczegółowe porównanie znajdziesz niżej w Jak wybrać między nimi. Krótko: Superpowers ma trudności z funkcjami obejmującymi wiele repo i z pracą wymagającą wyraźnego podziału ról.

Jeden deweloper opisał publicznie czwarty tryb porażki tej wtyczki: „Nawet najmniejsze zadania trwają wieczność, bo Claude uruchamia subagentów i pisze plany kompletnie na wyrost. Zmiana CSS zajmuje teraz wieki.”

Lekarstwem jest pomijanie Superpowers przy drobnostkach. Umiejętności uruchamiają się tylko po wyzwoleniu brainstormingu. Jednolinijkowa zmiana CSS może przejść przez Claude Code bez włączania pętli spec. Prawdziwy błąd to nadużywanie workflow tam, gdzie spec nie jest potrzebny.

GitHub Spec Kit

Spec Kit wybieraj wtedy, gdy spec musi przetrwać dłużej niż pojedyncza sesja Claude Code. To także dobry wybór, gdy muszą go czytać osoby, które nigdy nie otwierają Claude Code.

Czym jest GitHub spec-kit?

Spec Kit to projekt GitHub (github/spec-kit, MIT), utrzymywany przez samo GitHub, z ponad 100 tys. gwiazdek. Dostarcza CLI i workflow działające tak samo z każdym większym agentem do kodowania AI. Wspierane są Claude Code, Cursor, Aider, Cline i Roo Code. Neutralność względem agenta pozwala specowi żyć poza Claude Code.

Strona projektu Spec Kit na GitHubie.

Jak zainstalować GitHub spec-kit

Nie ma jeszcze oficjalnego pakietu na PyPI, więc zainstaluj CLI z taga Git przy użyciu uv:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Zastąp vX.Y.Z bieżącym tagiem wydania. Pakiet to specify-cli, a rejestrowana komenda to specify.

Workflow GitHub spec-kit

Workflow działa przez dziewięć komend „slash”, które CLI dodaje do listy komend twojego agenta. Sześć jest rdzeniem pętli, trzy są opcjonalne dla przypadków poza rdzeniem.

Separator między grupą komend a czasownikiem to kropka, nie dwukropek: /speckit.specify, nie /speckit:specify.

Dziewięć komend slash Spec Kit: sześć rdzeniowych na pipeline, trzy opcjonalne pod spodem.

Artefakty tworzone przez te komendy to ten sam spec i plan, które widziałeś w sekcji o Superpowers — również zapisywane na dysku i śledzone w Git. Różnica to przenośność: artefakty Spec Kit są zaprojektowane do pracy z dowolnym agentem kodującym AI, nie tylko Claude Code, a workflow jest zbudowany pod przegląd interesariuszy przez pull requesty na GitHubie, zamiast być efektem ubocznym pętli jednego narzędzia.

Kiedy używać GitHub spec-kit

W solo projekcie pewnie go nie potrzebujesz. Sięgnij po niego, gdy:

• Projekt wyrasta ponad jedną osobę
• Twój spec musi być czytany przez osoby, które nie otwierają Claude Code
• Część pracy wykonujesz agentem innym niż Claude Code
• Chcesz formatu speca, który żyje poza jednym narzędziem i nadal czyta się po miesiącach

Metoda BMAD

Tam, gdzie Spec Kit organizuje artefakty, BMAD organizuje ludzi. Dzieli ścieżkę od specu do kodu na cztery fazy, każdą prowadzoną przez nazwanego agenta-roli.

Czym jest BMAD?

BMAD-METHOD (bmad-code-org/BMAD-METHOD, MIT, około 47 tys. gwiazdek) jest w wersji 6. Akronim, zgodnie z dokumentacją projektu, rozwija się do „Breakthrough Method for Agile AI-Driven Development”. Działa na Claude Code i innych agentach, instalując się jako ekosystem modułów. Domyślna instalacja daje moduł core z sześcioma agentami ról, czterema fazami workflow i 34+ nazwanymi workflowami.

Strona projektu BMAD-METHOD na GitHubie.

Jak zainstalować BMAD

Zainstaluj BMAD przez Node:

npx bmad-method install

Sześciu agentów ról to persony promptów, które użytkownik aktywuje po nazwie wewnątrz hosta agenta. W Claude Code oznacza to wpisanie komendy aktywacji instalowanej przez BMAD. Sprawdź README po dokładną składnię — zmienia się między wydaniami.

Przedstawienie agentów-współpracowników BMAD i artefaktów

Po aktywowaniu agent przyjmuje instrukcje, głos i wyjścia danej roli, dopóki nie przełączysz persony. Szóstka to:

• Mary, Analityczka
• Paige, Techniczna Pisarka
• John, Product Manager
• Sally, Projektantka UX
• Winston, Architekt
• Amelia, Deweloperka

W v6 brakuje dwóch ról, których możesz się spodziewać: nie ma agenta Scrum Master i oddzielnego agenta QA. Planowanie sprintu i przygotowanie historii spada na agenta Dewelopera, a generowanie testów QA to workflow uruchamiany przez Dewelopera.

Zestaw artefaktów jest cięższy niż pojedyncza specyfikacja. Dostajesz:

• brief produktowy
• PRD (Product Requirements Document)
• specyfikację UX
• dokument architektury
• epiki rozbite na user stories (co użytkownicy będą mogli zrobić po wdrożeniu)

PRD i dokument architektury razem pełnią tę samą rolę co spec Superpowers. Podział rozkłada je na dwóch agentów ról i bardziej formalny format. Cały zestaw artefaktów obejmuje pełny cykl wytwarzania oprogramowania, a każda funkcja dziedziczy kontekst z wyższej warstwy.

Workflow BMAD

Workflow v6 działa w czterech fazach.

Cztery fazy BMAD i agent roli obsługujący każdą z nich. Ścieżka Quick Flow omija pierwsze trzy fazy przy małych zadaniach.

Faza 1, analiza, jest opcjonalna. Mary (Analityczka) i Paige (Tech Writer) prowadzą research i tworzą brief produktowy. Pomiń fazę, jeśli już wiesz, co budujesz.

Faza 2, planowanie, jest wymagana. John (PM) pisze PRD. Sally (UX) dodaje spec UX, gdy funkcja ma interfejs.

Faza 3, projektowanie rozwiązania, to faza Winstona. Architekt najpierw szkicuje architekturę, potem John rozbija wymagania na epiki i historie. Umieszczenie historii po architekturze to decyzja v6, która dopasowuje ich rozmiar do realnych granic implementacji. Winston uruchamia następnie kontrolę gotowości do implementacji z werdyktem PASS, CONCERNS lub FAIL.

Faza 4, implementacja, to miejsce pracy Amelii (Deweloperki) historia po historii: utwórz historię, zbuduj ją, zrób code review. Gdy cały epik jest gotowy, uruchamia workflow generowania testów QA dla całego epiku. To faza, w której Claude Code faktycznie koduje, działając jako Amelia.

Dla małych, dobrze określonych zadań BMAD dostarcza ścieżkę „Quick Flow”, która aktywuje Amelię bezpośrednio i pomija trzy pierwsze fazy. Komenda aktywacji jest w README BMAD (dokładna składnia zmienia się między wydaniami). Quick Flow nie tworzy PRD ani dokumentu architektury — tylko krótką historię i kod, który ją spełnia. To odpowiedź na zarzut „to przesada przy zmianie przycisku”.

Gdy spec okazuje się błędny w trakcie implementacji, BMAD wraca do werdyktu Winstona z Fazy 3. FAIL odsyła z powrotem do Fazy 2, by przepisać PRD. CONCERNS pozwala iść dalej z odnotowanymi ryzykami dołączonymi do historii. Ten podział pozwala iść naprzód przy drobnych niespójnościach i twardo zatrzymać się przy dużych.

Kiedy złożoność się opłaca

BMAD opłaca się w długotrwałych projektach z prawdziwymi użytkownikami. Pasuje też do zespołów wieloosobowych, ułatwiając przekazywanie pracy. Podział na fazy i role musi oszczędzać więcej czasu, niż kosztuje.

To zły wybór dla jednoosobowego projektu pobocznego. W solo pracy czterofazowy, sześcioagentowy podział to głównie narzut. Nie ma drugiej osoby w zespole, by separacja ról miała znaczenie.

Jak wybrać między frameworkami

O wyborze decydują trzy reguły.

• Użyj Spec Kit, jeśli spec musi być czytany przez osoby, które nie otwierają Claude Code, albo ma żyć w Git jako artefakt długoterminowy.
• Jeśli kilka osób pracuje w wyraźnie różnych rolach albo w pętli jest prawdziwy interesariusz w stylu PM — użyj BMAD.
• W przeciwnym razie użyj Superpowers.

Trzy pytania o twój projekt, cztery możliwe wybory frameworku.

Istnieje czwarta opcja z drzewa decyzyjnego: połącz Spec Kit z Superpowers. Użyj Spec Kit w fazie specu, aby artefakty żyły w Git do przeglądu międzyzespołowego. Następnie wskaż umiejętności subagent-driven-development z Superpowers plik planu Spec Kit jedną linijką konfiguracji. Dostajesz trwały spec ze Spec Kit obok zwartej pętli implementacji z Superpowers.

Wnioski

Rozwój oparty na specyfikacji to trzy dokumenty w kolejności. Spec mówi, co zbudować, plan mówi, w jakich krokach, a kod podąża za planem. Między każdą parą jest ludzka recenzja.

Przejdź przez powyższe drzewo decyzyjne, by wybrać framework, co dla większości czytelników skończy się na Superpowers. Zainstaluj go i wybierz jedną funkcję, którą w innym wypadku zrobiłbyś „na vibe”, coś dotykającego 3–5 plików. Przeprowadź ją end-to-end przez brainstorming, spec, plan i wykonanie. Jedno prawdziwe przejście nauczy workflowu lepiej niż jakikolwiek opis.

Jeśli chcesz najpierw odświeżyć podstawy Claude Code, DataCamp ma praktyczny tutorial Claude Code, przewodnik dobrych praktyk obejmujący tryb planu, CLAUDE.md i TDD oraz dogłębny materiał o samym trybie planu.