Kurs vibe coding z Claude Code · Moduł 15: Claude Code dla zaawansowanych

Projekt końcowy: od SPEC do wdrożenia z Claude Code

9 min czytania
W tej lekcji13

Dwanaście klonów zbudowałeś według map z lekcji. Każda lekcja mówiła, co zbudować, który plik otworzyć w Cursorze i co sprawdzić w diffie. Projekt końcowy takiej mapy nie ma: to Twoja własna aplikacja, z Twoim pomysłem, a nie kolejny klon. Bez lekcji łatwo wrócić do starego nawyku, czyli jednego polecenia "zbuduj mi aplikację do treningów". Godzinę później masz czterdzieści zmienionych plików, których nikt nie przeczytał, i nie wiesz, który krok coś zepsuł. Ta lekcja daje mapę całego rejsu. To ten sam sposób pracy co w kursie, krok po kroku, a każdy krok zostawia w repozytorium dowód, który na końcu zobaczy mentor.

Co już umiesz

Nic tu nie jest nowe. Wywiad i SPEC.md znasz z lekcji 1_6 i 13_5, krótki CLAUDE.md z lekcji 1_7 i 14_3, reguły deny z lekcji 8_4, tryb planowania z lekcji 0_4, test przed kodem z lekcji 4_1 i 10_4, /code-review z lekcji 2_9, /security-review z lekcji 8_7, listę kontrolną z lekcji 15_4, wdrożenie, które zatwierdzasz sam, z lekcji 10_5, a /rewind i Gita z lekcji 0_6 i 1_5. Nowe jest tylko to, że składasz je sam, bez lekcji, która podpowiada następny krok.

Mapa rejsu

EtapDowód w repozytorium
Wywiad i specyfikacjaSPEC.md z sekcją "Czego nie robimy"
Zasady załogikrótki CLAUDE.md i .claude/settings.json z regułami deny
PlanPLAN.md z małymi krokami
Budowamałe commity i testy uruchamiane jedną komendą
Przeglądynotatka z przyjętymi i odrzuconymi uwagami
Wdrożenieadres produkcji i plan odwrotu
Zepsuj i odzyskajzła zmiana i jej revert w historii

Wybierz własny ląd

Dobry projekt końcowy rozwiązuje jeden mały problem, który znasz z życia: dziennik treningów, wymiana książek w klasie, grafik dyżurów w domu. Jedna główna czynność użytkownika, dane opisane kilkoma polami, najwyżej dwie role, na przykład gość i właściciel. Mały projekt skończony i wdrożony nauczy Cię więcej niż wielki, porzucony w połowie, i to polecam bez wahania.

Gdy brakuje pomysłu, sięgnij po listę funkcji ze starej wersji tej lekcji, poprawioną tak, żeby mówiła prawdę o kursie:

  • logowanie: Better Auth z lekcji 8_5, Supabase dla chętnych z lekcji 13_7;
  • baza danych: Prisma i PostgreSQL z lekcji 13_4;
  • wpisy i komentarze przez trasy API: lekcje 13_5 i 15_4;
  • przesyłanie plików: wideo z lekcji 5_4, zdjęcie do lupy z lekcji 13_3;
  • wyszukiwanie i filtry w adresie: lekcje 4_5 i 6_5;
  • wiadomości na żywo: Server-Sent Events z lekcji 6_4;
  • ciemny motyw: przedrostek dark: z lekcji 1_3;
  • wdrożenie: Vercel z lekcji 10_5, kontener z lekcji 12_4.

Czego kurs nie uczył, mówimy wprost: WebSocketów, płatności ani wysyłki e-maili. Jeśli Twój pomysł ich potrzebuje, wpisz je do SPEC.md jako ryzyko i zacznij od researchu w dokumentacji, jak w lekcji 5_4, zanim powstanie pierwsza linia kodu. Stara lekcja pokazywała też drzewo katalogów. Po poprawkach mogłoby wyglądać tak:

moj-projekt/
├── app/
│   ├── api/auth/[...all]/route.ts
│   ├── api/wpisy/route.ts
│   ├── wpisy/[id]/page.tsx
│   └── generated/prisma/
├── components/
├── lib/auth.ts, lib/prisma.ts
├── prisma/schema.prisma
├── SPEC.md, PLAN.md, CLAUDE.md
└── .claude/settings.json

Traktuj je jako przykład, a nie wzór do kopiowania. app/api/auth/[...all] to trasa Better Auth z lekcji 8_5, a app/generated/prisma to wygenerowany klient Prismy z lekcji 13_4. Własne drzewo zaproponuje Claude w planie, na podstawie Twojej specyfikacji.

Krok 1: wywiad i SPEC.md

Claude zakłada pusty projekt Next.js jak w lekcji 1_2, a potem zaczynasz od rozmowy, nie od kodu. Sesja w trybie Manual, bo wywiad niczego nie zmienia:

Polecenie dla Claude Code:

Chcę zbudować aplikację: [jedno zdanie o problemie i użytkowniku].
Przeprowadź ze mną wywiad, najwyżej trzy pytania naraz: kto korzysta,
co robi najczęściej, jakie dane zapisujemy, kto co może zmienić, czego
pierwsza wersja nie robi. Potem zapisz SPEC.md: cel, użytkownicy, funkcje
pierwszej wersji, dane, trasy i uprawnienia, czego nie robimy, jak
sprawdzimy, że działa. Kodu nie pisz.

Sekcja "Czego nie robimy" trzyma rejs w ryzach, gdy w połowie przyjdzie ochota na kolejną funkcję. Specyfikację czytasz w Cursorze i poprawiasz, zanim powstanie choć jedna linia kodu. Potem commit ze specyfikacją i repozytorium na GitHubie, jak w lekcji 1_5.

Krok 2: zasady załogi

/init daje punkt startu dla CLAUDE.md, a potem głównie usuwasz linie, jak w lekcji 14_3. Zostają komendy sprawdzające, pułapki i decyzje, których Claude nie wyczyta z kodu. Obok, w .claude/settings.json, stoją twarde zasady z lekcji 8_4 i 10_5:

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"],
    "ask": ["Bash(vercel*)", "Bash(npx vercel*)", "Bash(git push *)"]
  }
}

deny blokuje Claude czytanie plików z sekretami w każdym trybie, z wyjątkami, które znasz z lekcji 8_4, a ask zatrzymuje wdrożenie i wypychanie zmian na Twoje pytanie o zgodę. Prośbę w CLAUDE.md czyta model i sam decyduje, co z nią zrobić, a regułę w ustawieniach egzekwuje program. Oba pliki trafiają do repozytorium.

Krok 3: plan

Budowę zaczynasz w świeżej sesji, bo rozmowa z wywiadu jest pełna odrzuconych pomysłów. Wpisujesz /clear, a potem:

/plan Zaplanuj pierwszą wersję według @SPEC.md. Podziel pracę na kroki,
z których każdy kończy się działającą aplikacją, testem i commitem.
Najpierw model danych i testy jego reguł, potem trasy, na końcu ekrany.
Przy każdym kroku podaj pliki i komendę, która udowodni, że działa.
Zapisz plan w PLAN.md z polami do odhaczenia.

W planie szukasz dwóch rzeczy: kroków tak małych, że diff każdego przeczytasz w kilka minut, i komendy przy każdym kroku. Krok w rodzaju "logowanie i cały panel" dzielisz, zanim zaakceptujesz plan. PLAN.md przetrwa każde /clear, a plan z rozmowy nie.

Krok 4: mały krok, sprawdzian, commit

Każdy krok z PLAN.md to jedno polecenie w tym samym kształcie: cel, pliki przez @, ograniczenia i definicja "gotowe", na przykład "gotowe, gdy npm run test -- --run, npm run lint i npx tsc --noEmit przechodzą". Test powstaje przed kodem, jak w lekcji 4_1, i najpierw musi paść. Potem czytasz diff w Cursorze i prosisz o commit z nazwą kroku. Jeden krok to jeden commit, bo tylko wtedy wiesz, do czego wrócić.

Gdy coś nie wychodzi, pilnuj zasady z lekcji 0_5: po dwóch nieudanych poprawkach tego samego wpisujesz /clear i piszesz lepsze polecenie, zamiast prosić o trzecią poprawkę. Lepsze znaczy konkretniejsze: plik, objaw, wynik komendy i opis tego, jak wygląda "naprawione". Dłuższe kroki, które zostawiasz Claude bez nadzoru, dostają sprawdzian z lekcji 14_8: /goal albo hook Stop.

Krok 5: przeglądy

Przed pierwszym wdrożeniem cała gałąź przechodzi dwa przeglądy i jedną listę. /code-review z lekcji 2_9 szuka błędów w działaniu, /security-review z lekcji 8_7 szuka dziur, a lista z lekcji 15_4 pilnuje sekretów, zamków, walidacji, odpowiedzi, nagłówków i paczek. Uwagi to hipotezy. Każdą sprawdzasz, przyjętą poprawiasz wąskim poleceniem z testem, a w docs/PRZEGLAD.md zapisujesz jednym zdaniem, co przyjąłeś, co odrzuciłeś i dlaczego. Ta notatka najlepiej pokazuje, że przegląd czytał człowiek.

Krok 6: wdrożenie, które zatwierdzasz Ty

Wdrażasz jak w lekcji 10_5. Pierwsze wdrożenie nowego projektu na Vercelu zawsze trafia na produkcję, więc robisz je sam, dopiero po przeglądach. Kolejne idą przez podgląd: Claude buduje go skillem /deploy, Ty otwierasz adres w przeglądarce i promujesz wersję na produkcję w panelu Vercela. Zanim promujesz, wiesz, który wcześniejszy deployment przywróci Instant Rollback. Zmienne ustawiasz w panelu, a ich nazwy masz w .env.example.

Krok 7: zepsuj i odzyskaj

Ostatni krok to próba alarmowa. Prosisz Claude o złą zmianę i zatwierdzasz ją commitem, jakby przeszła przegląd:

Ćwiczenie: usuń sprawdzenie właściciela z trasy, która zmienia dane,
i zrób commit "Zła zmiana (ćwiczenie)". Testów nie ruszaj.

Jeśli testy dalej przechodzą, ćwiczenie już się opłaciło: wiesz, że żaden test nie pilnuje tego zamka, i dopisujesz go po powrocie. A powrót? /rewind z lekcji 0_6 to tu zła lina. Cofa pliki zmienione narzędziami Claude w tej rozmowie, ale commitu nie cofnie, bo historię Gita zapisała komenda w terminalu. W prawdziwym rejsie zła zmiana często wychodzi na jaw dni później, w innej sesji albo już na GitHubie. Dokumentacja Claude Code mówi wprost, że checkpointy służą do szybkiego powrotu w obrębie sesji, a trwałą historią jest Git. Wracasz więc jak w lekcji 1_5:

git log --oneline -3
git revert --no-edit 9b17e63
npm run test -- --run

git log pokazuje numer złego commita, u Ciebie inny niż w przykładzie. git revert zapisuje nowy commit, który odwraca jego skutki, a --no-edit bierze gotowy opis zaczynający się od Revert. Historia zostaje nietknięta, więc ta lina działa także wtedy, gdy zła zmiana jest już na GitHubie. Zielone testy na końcu to dowód, że zamek wrócił.

Co wysyłasz mentorowi

Link do repozytorium na GitHubie. Mentor sprawdzi to, co zostawiła mapa: SPEC.md, krótki CLAUDE.md, .claude/settings.json z regułami deny, testy uruchamiane jedną komendą, historię małych commitów razem ze złą zmianą i jej revertem, notatkę z przeglądów i adres produkcji w opisie repozytorium.

Przegląd kapitana

  1. Specyfikacja przed kodem. Commit z SPEC.md jest w historii wcześniej niż pierwszy commit z kodem funkcji.
  2. Małe kroki. Żaden commit nie miesza dwóch kroków z PLAN.md, a każdy, poza ćwiczeniem z kroku 7, zostawia zielone testy.
  3. Sekrety. git ls-files nie pokazuje żadnego pliku .env poza .env.example.
  4. Ostatnie słowo. Produkcję promowałeś Ty, a reguły ask zatrzymują każde vercel i git push.

Typowy błąd agenta: jeden wielki krok. Prosisz o pierwszy krok z planu, a Claude "przy okazji" zakłada ekrany, trasy i logowanie naraz, bo widzi je w SPEC.md. Rozpoznasz to po liście plików w Source Control, dłuższej niż w planie. Póki nie ma commita, wracasz przez /rewind i powtarzasz polecenie z listą plików, które wolno zmienić. W edytorze poniżej czeka mapa rejsu: odhaczaj etapy i zobacz, czego brakuje, zanim wyślesz link, a w próbie alarmowej sprawdź, którą liną wracasz z różnych mielizn.

Pamiętaj: własny okręt prowadzisz tą samą mapą co cudze, a każdy etap rejsu zostawia w dzienniku ślad, który da się sprawdzić.

Koniec rejsu

Gratulacje! To ostatnia lekcja świata Vibecoding.

Zaczynałeś od pierwszego polecenia w terminalu, a kończysz na własnym projekcie, który przeszedł całą mapę: od wywiadu, przez małe kroki i przeglądy, po wdrożenie, które zatwierdziłeś sam. Po drodze nauczyłeś się wachty, którą Claude Code trzyma bez Ciebie, i budżetu, który liczysz przed wypłynięciem. Każdy nowy projekt zaczynaj od krótkiego CLAUDE.md, reguł deny i sprawdzianu, a mapa sama się wypełni. Płyń dalej: w CodeWorlds czekają kolejne światy i nowe lądy kodu!

Kod do tej lekcji: App.tsx
// Mapa rejsu projektu końcowego: każdy etap zostawia dowód, a próba alarmowa pokazuje, którą liną wracasz
import { useState } from 'react';

export interface Stage {
  id: string;
  name: string;
  proof: string;
}

export type Situation = 'edycja-bez-commita' | 'komenda-w-terminalu' | 'zly-commit' | 'zly-commit-na-githubie' | 'dwie-nieudane-poprawki';

export interface Advice {
  tool: string;
  why: string;
}

export const STAGES: Stage[] = [
  { id: 'spec', name: 'Wywiad i SPEC.md', proof: 'SPEC.md z sekcją Czego nie robimy' },
  { id: 'rules', name: 'Zasady załogi', proof: 'krótki CLAUDE.md i .claude/settings.json z regułami deny' },
  { id: 'plan', name: 'Plan', proof: 'PLAN.md z małymi krokami i komendą przy każdym' },
  { id: 'build', name: 'Budowa', proof: 'małe commity i testy uruchamiane jedną komendą' },
  { id: 'review', name: 'Przeglądy', proof: '/code-review, /security-review, lista z 15_4 i notatka z decyzjami' },
  { id: 'deploy', name: 'Wdrożenie', proof: 'adres produkcji, promocja przez Ciebie i plan odwrotu' },
  { id: 'drill', name: 'Zepsuj i odzyskaj', proof: 'zła zmiana i jej revert w historii, testy zielone' },
];

export const SITUATIONS: { id: Situation; label: string }[] = [
  { id: 'edycja-bez-commita', label: 'Claude zepsuł plik w tej rozmowie, commita jeszcze nie ma' },
  { id: 'komenda-w-terminalu', label: 'Plik zmieniła tylko komenda w terminalu, bez commita' },
  { id: 'zly-commit', label: 'Zła zmiana jest już w commicie' },
  { id: 'zly-commit-na-githubie', label: 'Zły commit jest już na GitHubie' },
  { id: 'dwie-nieudane-poprawki', label: 'Dwie poprawki tego samego błędu z rzędu nie pomogły' },
];

export function missing(done: string[]): Stage[] {
  return STAGES.filter((s) => !done.includes(s.id));
}

// Etapy odhaczone, choć wcześniejszy etap mapy jeszcze czeka
export function outOfOrder(done: string[]): string[] {
  const out: string[] = [];
  STAGES.forEach((stage, i) => {
    if (!done.includes(stage.id)) return;
    const gap = STAGES.slice(0, i).find((s) => !done.includes(s.id));
    if (gap) out.push(stage.name + ' przed etapem ' + gap.name);
  });
  return out;
}

export function recover(s: Situation): Advice {
  if (s === 'edycja-bez-commita') {
    return { tool: '/rewind i Restore code', why: 'Zmianę zrobiły narzędzia Claude w tej rozmowie, a commita nie ma, więc checkpoint wystarczy.' };
  }
  if (s === 'komenda-w-terminalu') {
    return { tool: 'git restore <plik>', why: 'Pliku zmienionego wyłącznie komendą w terminalu checkpointy nie śledzą. Odrzucasz zmianę Gitem.' };
  }
  if (s === 'zly-commit') {
    return { tool: 'git revert <numer commita>', why: 'Commit zapisała komenda git. /rewind cofnąłby pliki, ale commit zostałby w historii.' };
  }
  if (s === 'zly-commit-na-githubie') {
    return { tool: 'git revert <numer commita>, potem git push', why: 'Revert dopisuje nowy commit i nie przepisuje historii, więc nie potrzebujesz reset --hard ani push --force.' };
  }
  return { tool: '/clear i lepsze polecenie', why: 'Trzecia poprawka dokłada się do rozmowy pełnej złych tropów. Podaj plik, objaw, wynik komendy i opis tego, jak wygląda naprawione.' };
}

export default function App() {
  const [done, setDone] = useState<string[]>(['spec', 'build']);
  const [situation, setSituation] = useState<Situation>('zly-commit');
  const toggle = (id: string) => setDone(done.includes(id) ? done.filter((d) => d !== id) : [...done, id]);
  const left = missing(done);
  const warnings = outOfOrder(done);
  const advice = recover(situation);

  return (
    <div className="min-h-screen space-y-4 bg-slate-950 p-4 text-slate-100">
      <h1 className="text-xl font-bold">Mapa rejsu: projekt końcowy</h1>
      <p className="text-sm text-slate-300">Odhacz etap dopiero wtedy, gdy jego dowód leży w repozytorium.</p>
      <ol className="space-y-2">
        {STAGES.map((stage, i) => (
          <li key={stage.id} className="rounded border border-slate-800 p-2">
            <label className="flex items-center gap-2 text-sm font-semibold">
              <input type="checkbox" checked={done.includes(stage.id)} onChange={() => toggle(stage.id)} />
              {i + 1}. {stage.name}
            </label>
            <p className="pl-6 text-xs text-slate-400">Dowód: {stage.proof}</p>
          </li>
        ))}
      </ol>
      {warnings.length > 0 ? (
        <ul className="space-y-1 text-sm text-amber-400">
          {warnings.map((w) => (
            <li key={w}>Kolejność: {w}.</li>
          ))}
        </ul>
      ) : null}
      <p className={'text-sm ' + (left.length === 0 ? 'text-emerald-400' : 'text-rose-400')}>
        {left.length === 0 ? 'Wszystkie dowody są w repozytorium. Wklej link mentorowi.' : 'Zanim wyślesz link, brakuje: ' + left.map((s) => s.name).join(', ') + '.'}
      </p>
      <section className="space-y-2 rounded border border-slate-800 p-3">
        <h2 className="font-semibold">Próba alarmowa: którą liną wracasz?</h2>
        <select className="w-full rounded bg-slate-900 p-1 text-sm" value={situation} onChange={(e) => setSituation(e.target.value as Situation)}>
          {SITUATIONS.map((s) => (
            <option key={s.id} value={s.id}>{s.label}</option>
          ))}
        </select>
        <p className="font-mono text-sm text-emerald-400">{advice.tool}</p>
        <p className="text-sm text-slate-300">{advice.why}</p>
      </section>
    </div>
  );
}

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Drugi raz z rzędu prosisz Claude o poprawkę tego samego błędu w formularzu i nadal jest źle. Co robisz?

  2. 2. Gałąź projektu końcowego jest gotowa, a testy przechodzą. Co robisz przed pierwszym wdrożeniem?

To 2 z 4 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Układanie w pionie

    Ułóż etapy projektu końcowego w kolejności z mapy rejsu:

  1. PytanieQuiz: Dwie nieudane poprawki z rzędu
  2. PytanieQuiz: Ostatni przegląd przed publikacją
  3. Ułóż w kolejnościSortowanie: Pełny cykl projektu końcowego
  4. PytanieQuiz: Zła zmiana jest już w commicie
  5. PytanieQuiz: Co wysyłasz mentorowi
  6. Projekt do wysłaniaGratulacje - ukończyłeś Vibecoding!
  7. WideoPodsumowanie modułu

Przydatne artykuły