Kurs vibe coding z Claude Code · Moduł 2: Projekt Next.js z Claude Code
Najpierw plan: mini PRD dla Kraken's Call
W tej lekcji11
Ahoj! Kraken's Call ma sekcję hero, stronę załogi i dziennik pokładowy na GitHubie. Do końca tej lokacji zamienisz to w landing page, czyli stronę główną, która w kilka sekund mówi gościowi, czym jest gra, i zaprasza go na pokład. Zanim jednak padnie pierwszy rozkaz budowy, narysujesz mapę.
Problem: cztery sekcje i sto domysłów
Polecenie "zrób landing page dla Kraken's Call" brzmi konkretnie, ale zostawia Claude dziesiątki decyzji. Ile sekcji ma mieć strona? Czy karty załogi trafią na stronę główną, czy zostaną pod adresem /crew? Co robi przycisk "Dołącz do załogi"? Czy stopka ma linki? Z lekcji 0_4 wiesz, że Claude wypełnia takie luki po swojemu. Po kwadransie dostajesz stronę z animacjami, formularzem zapisu do newslettera i nową paczką npm, a potem drugi kwadrans wycinasz to, o co nie prosiłeś.
Lekarstwo jest stare jak żegluga: zanim podniesiesz kotwicę, spisz, dokąd płyniesz, czego nie robisz i po czym poznasz port.
Mini PRD, czyli SPEC.md
PRD (Product Requirements Document) to dokument wymagań produktu. W firmach opisuje, co ma powstać, dla kogo i po czym poznać, że jest gotowe. Nasz będzie mini: jeden plik SPEC.md w głównym folderze projektu, z pięcioma częściami:
- cel: jedno zdanie o tym, po co strona istnieje;
- odbiorca: kto na nią wejdzie i z jakiego urządzenia;
- sekcje strony: co stoi na stronie, od góry do dołu;
- czego nie robimy: granice, za które Claude nie wychodzi;
- jak sprawdzimy: komendy i obserwacje, które mówią "gotowe".
Wywiad i SPEC.md poznałeś w lekcji 0_5 przy jednym pliku HTML. Tu ta sama technika planuje prawdziwy projekt, a plik zostanie w repozytorium jako mapa na kolejne lekcje.
Polecenie: wywiad
Otwórz w Cursorze folder krakens-call, uruchom w terminalu claude i przełącz sesję na Manual. Sam wywiad niczego nie zmienia: Claude zapyta o zgodę dopiero wtedy, gdy zechce zapisać plik.
Polecenie dla Claude Code:
Chcę zamienić stronę główną @app/page.tsx w landing page gry Kraken's
Call. Sekcja hero już jest, a karty załogi są w @app/crew/page.tsx.
Przeprowadź ze mną wywiad: zadawaj pytania po kolei, najwyżej trzy
naraz, aż będziesz w stanie napisać specyfikację. Zapisz ją w SPEC.md
w pięciu częściach: cel, odbiorca, sekcje strony, czego nie robimy,
jak sprawdzimy. Nie zmieniaj żadnych innych plików.Polecenie wskazuje pliki przez @, więc Claude od razu wie, co już stoi na pokładzie. Narzuca też kształt specyfikacji i zamyka drogę do zmian w kodzie: na tym etapie powstaje tylko mapa.
Jak wygląda wywiad
Dokumentacja Claude Code opisuje, że w wywiadzie Claude zadaje pytania, często z odpowiedziami do wyboru, o sprawy, których jeszcze nie przemyślałeś, także o to, co zostaje poza zakresem. Pierwsza runda może wyglądać tak:
1. Kto najczęściej wejdzie na stronę?
a) gracze, którzy pierwszy raz słyszą o grze b) obecni gracze
2. Ile kroków ma mieć sekcja "Jak grać"? a) trzy b) pięć
3. Co robi przycisk "Dołącz do załogi"?
a) na razie nic b) prowadzi do formularza zapisuTwoje pytania będą brzmiały inaczej, a ich liczba zależy od tego, ile zostawiłeś niedopowiedziane. Odpowiadaj krótko. Gdy nie wiesz, napisz: "zaproponuj odpowiedź i uzasadnij ją jednym zdaniem". Rada kapitana: najcenniejsze są odpowiedzi "tego nie robimy", bo każda z nich wycina z przyszłego planu godzinę pracy.
Co napisał Claude: SPEC.md
Gdy wywiad się skończy, Claude poprosi o zgodę na zapis. Otwórz SPEC.md w Cursorze. Twój plik będzie miał inne słowa, ale te same części. Na górze stoją cel i odbiorca:
# SPEC: strona główna Kraken's Call
## Cel
Gość w kilka sekund wie, czym jest gra, i klika "Dołącz do załogi".
## Odbiorca
Gracze, którzy pierwszy raz trafiają na stronę, najczęściej z telefonu.Cel to jedno zdanie, które da się sprawdzić, a nie "ładna strona". Odbiorca z telefonem przypomina zasadę z lekcji 1_3: najpierw wąski ekran. Ani cel, ani odbiorca nie mówią jeszcze nic o kodzie.
Dalej sekcje strony, wypisane w kolejności, w jakiej gość zobaczy je od góry do dołu:
## Sekcje strony (od góry)
1. Hero: nazwa gry, jedno zdanie opisu, przycisk "Dołącz do załogi".
2. Załoga: trzy karty piratów, te same co na stronie /crew.
3. Jak grać: trzy kroki, każdy z tytułem i jednym zdaniem.
4. Stopka: nazwa gry, rok i link do repozytorium na GitHubie.Każda sekcja ma treść i liczby: "trzy kroki", a nie "kilka". Zapis "te same co na stronie /crew" mówi Claude, że ma użyć istniejących kart, a nie pisać nowych.
Na końcu stoją dwie części, do których będziesz wracać najczęściej, bo to one pilnują granic budowy i mówią, kiedy rejs się kończy:
## Czego nie robimy
- logowania, bazy danych ani formularzy;
- animacji i nowych paczek npm;
- akcji przycisku: na razie tylko wygląda;
- zmian w next.config.ts, Cache Components zostają wyłączone.
## Jak sprawdzimy
- npm run build, npm run lint i npx tsc --noEmit bez błędów;
- strona czytelna na szerokości telefonu;
- każdy tekst wyraźnie odcina się od tła."Czego nie robimy" to lista, z którą za chwilę porównasz plan. "Jak sprawdzimy" zbiera sprawdziany z lekcji 1_2 i 1_4 oraz dwie rzeczy, których żadna komenda nie oceni: wąski ekran i kontrast. Gdy plik Ci odpowiada, poproś o commit z opisem i przeczytaj komendy, zanim się zgodzisz.
Najpierw "co", potem "jak"
Zauważ, czego w SPEC.md nie ma: nazw plików, komponentów ani kolejności pracy. Specyfikacja odpowiada na pytania "co" i "po co", a plan na pytanie "jak i w jakiej kolejności". Rozdzielasz je celowo. Specyfikację zatwierdzasz jako kapitan, który zna cel rejsu, a plan układa Claude, który czyta kod. Gdy plan się nie uda, wyrzucasz plan, a specyfikacja zostaje. Plan podzielisz na małe kroki, a każdy zakończysz sprawdzianem: jeśli build wywróci się po kroku trzecim, od razu wiesz, gdzie szukać winnego.
Świeża sesja i tryb planowania
Rozmowa z wywiadu jest pełna pomysłów, które po drodze odrzuciłeś. Dobre praktyki Claude Code radzą zaczynać budowę ze specyfikacji w świeżej sesji: z czystym kontekstem i spisaną definicją "gotowe". Wpisz /clear: ta komenda zaczyna nową rozmowę, a starą da się później wznowić. Potem wydaj polecenie z przedrostkiem /plan z lekcji 0_4, który przełącza sesję w tryb planowania:
Polecenie dla Claude Code:
/plan Na podstawie @SPEC.md zaplanuj landing page w małych krokach:
jeden krok to jedna sekcja albo jedna zmiana w plikach. Przy każdym
kroku wypisz pliki, które zmienisz, i zakończ go npm run build. Nie
planuj niczego spoza SPEC.md. Po akceptacji dopisz plan na końcu
SPEC.md jako część "Plan budowy" i na tym skończ.Ostatnie zdanie jest nowe: plan z rozmowy znika po /clear, a plan w pliku przetrwa każdą sesję. Budowa ruszy dopiero w lekcji 1_8, krok po kroku, a dziś powstaje tylko mapa trasy.
Co przygotował Claude: plan
W trybie planowania Claude czyta SPEC.md, pliki obu stron i konfigurację projektu, a potem pokazuje plan i pyta, co dalej. Twój plan może mieć inne słowa, ale podobny kształt:
Plan budowy
1. Typy CrewRole i CrewMember, dane załogi i CrewCard przenieś
z app/crew/page.tsx do nowego pliku components/crew.tsx; strona
/crew importuje je stamtąd i wygląda tak samo. npm run build.
2. app/page.tsx: hero jako pierwsza sekcja, pod nią sekcja "Załoga"
z kartami CrewCard. npm run build.
3. app/page.tsx: sekcja "Jak grać" z trzema krokami. npm run build.
4. app/page.tsx: stopka z nazwą gry, rokiem i linkiem. npm run build.
5. app/layout.tsx: tytuł i opis strony, lang="pl".
npm run build i npm run lint.
Bez nowych paczek i bez zmian w next.config.ts.Pierwszy krok tworzy nowy plik, ale ma dobry powód: karty załogi pokażą teraz dwie strony, a wspólny kod powinien leżeć w jednym miejscu. Każdy krok wymienia pliki i kończy się sprawdzianem. Na dysku nic się jeszcze nie zmieniło.
Poprawka przed akceptacją
Załóżmy, że w Twoim planie pojawił się krok "Zainstaluję bibliotekę animacji, żeby karty płynnie wjeżdżały na ekran". To typowy błąd agenta: plan "na zapas", który dokłada rzeczy, o które nikt nie prosił. Tu łamie wprost zakaz nowych paczek ze SPEC.md. Wybierz No, keep planning i napisz:
Usuń krok z biblioteką animacji: SPEC.md wyklucza nowe paczki.
Resztę planu zostaw bez zmian.Claude pokaże poprawiony plan, a pliki nadal stoją nietknięte. Drobną poprawkę możesz też nanieść sam: Ctrl+G otwiera plan w domyślnym edytorze tekstu. Gdy plan przejdzie przegląd, wybierz Yes, manually approve edits: akceptacja kończy tryb planowania, a każdą edycję zatwierdzasz sam. Claude poprosi o zgodę na dopisanie planu do SPEC.md i na tym się zatrzyma.
Przegląd kapitana
Zanim zaakceptujesz plan, sprawdź cztery rzeczy:
- Pliki: każdy krok wymienia pliki, a każdy nowy plik ma powód.
- Granice: nic spoza
SPEC.md: żadnych nowych paczek, logowania ani zmian wnext.config.ts. - Sprawdzian: każdy krok kończy się
npm run build. - Rozmiar kroku: jeden krok to jedna sekcja. Krok w rodzaju "zbuduj resztę strony" to sygnał, że plan trzeba pociąć.
Po akceptacji otwórz Source Control: zmienił się tylko SPEC.md, a diff pokazuje na końcu pliku nową część "Plan budowy".
Następny krok
Poproś o commit z opisem, na przykład "SPEC.md: plan budowy landing page'a". Mapa leży w dzienniku. W następnej lekcji nauczysz okręt pamiętać zasady projektu, a w lekcji 1_8 ruszysz z budową. W edytorze poniżej czeka gotowy SPEC.md z planem i drugi plik z planem "na zapas": znajdź w nim kroki, które łamią specyfikację, i ten, który jest za duży.
Pamiętaj: mapa narysowana przed rejsem kosztuje kwadrans, a błądzenie bez niej cały dzień.
Kod do tej lekcji: SPEC.md
# SPEC: strona główna Kraken's Call
## Cel
Gość w kilka sekund wie, czym jest gra, i klika "Dołącz do załogi".
## Odbiorca
Gracze, którzy pierwszy raz trafiają na stronę, najczęściej z telefonu.
## Sekcje strony (od góry)
1. Hero: nazwa gry, jedno zdanie opisu, przycisk "Dołącz do załogi".
2. Załoga: trzy karty piratów, te same co na stronie /crew.
3. Jak grać: trzy kroki, każdy z tytułem i jednym zdaniem.
4. Stopka: nazwa gry, rok i link do repozytorium na GitHubie.
## Czego nie robimy
- logowania, bazy danych ani formularzy;
- animacji i nowych paczek npm;
- akcji przycisku: na razie tylko wygląda;
- zmian w next.config.ts, Cache Components zostają wyłączone.
## Jak sprawdzimy
- npm run build, npm run lint i npx tsc --noEmit bez błędów;
- strona czytelna na szerokości telefonu;
- każdy tekst wyraźnie odcina się od tła.
## Plan budowy
1. Typy CrewRole i CrewMember, dane załogi i CrewCard przenieś
z app/crew/page.tsx do nowego pliku components/crew.tsx; strona
/crew importuje je stamtąd i wygląda tak samo. npm run build.
2. app/page.tsx: hero jako pierwsza sekcja, pod nią sekcja "Załoga"
z kartami CrewCard. npm run build.
3. app/page.tsx: sekcja "Jak grać" z trzema krokami. npm run build.
4. app/page.tsx: stopka z nazwą gry, rokiem i linkiem. npm run build.
5. app/layout.tsx: tytuł i opis strony, lang="pl".
npm run build i npm run lint.
Bez nowych paczek i bez zmian w next.config.ts.
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Po co przed budową landing page'a spisujesz z Claude mini PRD w pliku SPEC.md?
2. Który krok planu landing page'a jest zbudowany najlepiej?
3. Plan od Claude zakłada instalację biblioteki animacji, a SPEC.md wyklucza nowe paczki. Co robisz?
Zadania praktyczne w grze
- Układanie w pionie
Ułóż kroki od gotowej specyfikacji do planu budowy zapisanego w pliku: