Jak zbudować apkę z Claude Code, build-along 2026

Spis treści

• Co zbudujemy i czego potrzebujesz
• Krok 1, setup projektu Next.js
• Krok 2, claude i /init (CLAUDE.md)
• Krok 3, opisz apkę po polsku
• Krok 4, Plan Mode zanim Claude zacznie
• Krok 5, generacja i iteracja
• Krok 6, test i weryfikacja
• Krok 7, deploy na Vercel
• Modele i koszty tego projektu
• 5 antywzorców budowy apki
• Co dalej, rozbudowa projektu
• FAQ

Aktualizacja: maj 2026. To build-along, czyli budujemy razem, krok po kroku. Zaczynasz od pustego katalogu, kończysz z działającą aplikacją Next.js postawioną na produkcji, a cały kod pisze Claude Code, ty prowadzisz wizję i weryfikujesz efekty. Pokazuję dokładne komendy (zweryfikowane na oficjalnej dokumentacji Claude Code, maj 2026), gdzie wcisnąć Shift+Tab, jak działa /init i Plan Mode oraz jak nie przepalić budżetu w pierwszej godzinie. Jeśli to twój pierwszy raz z terminalem, najpierw przejdź przez Claude Code jak zacząć, a potem wróć tutaj.

Co zbudujemy i czego potrzebujesz

Zbudujemy prostą, ale realną apkę: kalkulator wyceny dla freelancera z formularzem, który wysyła wynik na maila. To projekt, który faktycznie da się postawić w jeden wieczór, a jednocześnie dotyka wszystkich etapów, które powtarzają się w każdej większej aplikacji: routing, formularz, stan, walidacja, integracja zewnętrzna, deploy.

Czego potrzebujesz przed startem:

• Node.js 18+ i terminal (macOS, Linux albo Windows przez WSL2)
• Claude Code zainstalowany i zalogowany, instrukcja w Claude Code jak zacząć
• Konto GitHub i Vercel (oba mają darmowy plan) do deployu
• Opcjonalnie klucz API Resend, jeśli chcesz realnie wysyłać maile

Nie potrzebujesz znajomości TypeScript ani Reacta. Prowadzisz Claude po polsku, on dostarcza składnię. To dokładnie podejście, które opisuję w vibe coding po polsku i w Claude Code dla nietechnicznych.

Krok 1, setup projektu Next.js

Zaczynamy od gotowego szkieletu. create-next-app stawia projekt Next.js z TypeScriptem, Tailwindem, App Routerem i bundlerem Turbopack jednym poleceniem. Dlaczego Next.js, a nie coś innego? Bo Claude zna ten stack najlepiej, a pipeline od projektu do produkcji jest najkrótszy. W terminalu:

npx create-next-app@latest moja-apka --typescript --tailwind --app --turbopack
cd moja-apka
git init

Flaga @latest bierze aktualną wersję (w maju 2026 to Next.js 16). git init w pierwszej minucie to nie kosmetyka, to twoja siatka bezpieczeństwa. Gdy Claude w którymś prompcie coś popsuje, wracasz do ostatniego działającego commita jednym poleceniem zamiast prosić AI o cofnięcie zmian.

Krok 2, claude i /init (CLAUDE.md)

Wchodzimy do sesji. W katalogu projektu wpisz:

claude

Pierwszy ruch w nowym repo to wygenerowanie pamięci projektu. W sesji wpisz slash command:

/init

/init skanuje strukturę projektu, rozpoznaje stack i zależności, wykrywa konwencje i generuje plik CLAUDE.md w root. To dokument, który Claude czyta na początku każdej sesji, więc nie musisz tłumaczyć kontekstu od zera za każdym razem. Od marca 2026 /init dodatkowo zadaje kilka pytań o twój workflow. Odpowiadaj konkretnie.

Po wygenerowaniu dopisz do CLAUDE.md zasady, których chcesz pilnować. Krótko, max strona A4. Przykład minimalny:

# Projekt: kalkulator wyceny freelancera

## Stack
- Next.js 16 (App Router), TypeScript, Tailwind CSS
- Brak dodatkowych zależności bez mojej zgody

## Zasady
- Komponenty są server components, chyba że używają useState/useEffect (wtedy 'use client' na górze)
- Każda działająca zmiana = osobny commit (atomic)
- Pisz po polsku w komentarzach i commitach
- Zero 'any' w TypeScript, dobieraj dokładny typ

Plik CLAUDE.md to pojedyncza inwestycja 15 minut, która oszczędza godziny powtarzania kontekstu. Więcej o pamięci projektu w Claude Code tutorial po polsku.

Krok 3, opisz apkę po polsku

Teraz najważniejsza umiejętność w całym build-along: opisz, co apka ma robić, językiem efektu, nie implementacji. Nie mów "użyj useState", mów "po zmianie suwaka cena ma się aktualizować na żywo". Wklej do sesji opis w 3-6 zdaniach:

> Zbuduj jednostronicowy kalkulator wyceny dla freelancera-grafika.
> Klient wybiera: typ projektu (logo, branding, social media pack),
> liczbę rund poprawek (suwak 1-5) i termin (3, 7, 14 dni).
> Cena w PLN aktualizuje się na żywo. Krótszy termin = wyższa cena.
> Na dole formularz "Wyślij wycenę na e-mail" (na razie tylko walidacja, bez wysyłki).
> Wygląd: ciemne tło, akcent zielony, mobile-friendly.

Im konkretniejszy opis, tym mniej rund poprawek. Ale nie przesadzaj z jednym mega-promptem na wszystko. Tu opisujesz całość wizji, a wykonanie zaraz rozbijemy na etapy przez Plan Mode.

Krok 4, Plan Mode zanim Claude zacznie

To nawyk, który odróżnia chaotyczny vibe coding od pracy, która się skaluje. Zanim Claude tknie pliki, niech rozpisze plan. Masz dwie drogi.

W trakcie sesji: wciśnij Shift+Tab. Skrót cyklicznie przełącza tryby uprawnień: default, acceptEdits, auto, plan. Zatrzymaj się na plan.

Albo od startu sesji:

claude --permission-mode plan

Flaga --permission-mode przyjmuje wartości default, acceptEdits, plan, auto, dontAsk i bypassPermissions. W Plan Mode Claude analizuje pliki i przedstawia plan kroków, ale nie edytuje niczego, dopóki planu nie zaakceptujesz. Dla naszego kalkulatora Claude rozpisze coś w stylu: stworzyć komponent kalkulatora, dodać stan suwaków, logikę cenową, formularz z walidacją, ostylować Tailwindem. Czytasz plan, korygujesz słownie ("rozbij cenę na osobny plik z logiką"), akceptujesz.

Krok 5, generacja i iteracja

Zaakceptuj plan. Claude generuje kod: tworzy komponenty, edytuje pliki, dopina Tailwind. Pierwsza wersja nie będzie idealna i to jest OK, to punkt startu, nie meta. Teraz iterujesz, a złota zasada brzmi: jedno zadanie na prompt.

> Cena nie aktualizuje się od razu po przesunięciu suwaka poprawek, popraw.
> Dodaj walidację: e-mail musi zawierać @, inaczej pokaż błąd pod polem.
> Zmień akcent na ciemniejszą zieleń, RGB około 16, 185, 129.

Każdy prompt to jedna rzecz, którą po wykonaniu od razu sprawdzasz i commitujesz. Jeśli wrzucisz "popraw cenę, dodaj walidację, zmień kolor i dodaj animację" w jednym prompcie, Claude zrobi 3 z 4, a ty nawet nie zauważysz, czego brakuje. Atomowe prompty = łatwa weryfikacja po każdym kroku.

Gdy skończysz sesję i wrócisz później, nie zaczynaj od zera. Wczytaj poprzednią rozmowę:

claude -c

-c (--continue) wczytuje najnowszą rozmowę w tym katalogu. Jeśli masz kilka równoległych wątków, użyj claude -r (--resume), który pokaże picker sesji do wyboru. Warto nazywać sesje przez claude -n "kalkulator", żeby łatwo je później znaleźć.

Krok 6, test i weryfikacja

Największa pułapka budowy apki z AI: Claude mówi "gotowe, działa", a apka jest popsuta albo funkcja nie istnieje. Nie ufaj słowom, ufaj dowodom. Najpierw odpal serwer deweloperski:

npm run dev

Otwórz http://localhost:3000 i przejdź przez weryfikację w czterech warstwach, od najtańszej do najmocniejszej:

1. Smoke test ręczny. Klikaj kalkulator jak klient: różne typy projektu, suwak poprawek, terminy. Sprawdź na telefonie (w Chrome Cmd+Opt+I i tryb urządzenia).
2. Konsola deweloperska. W Chrome Cmd+Opt+J. Czerwony error albo żółty warning? Skopiuj treść i daj Claude: "konsola pokazuje: ...", on naprawi.
3. Testy automatyczne. Poproś o dowód: "napisz test Vitest do funkcji liczącej cenę, uruchom go i pokaż output". Test to jedyny obiektywny dowód, że logika działa.
4. Self-review. Po większej zmianie: "przeczytaj swój ostatni commit i wskaż 3 edge case'y, których nie obsłużyłeś". Claude często sam wskaże własne braki.

Reguła jest prosta: każda zmiana musi być widoczna w działaniu albo w teście. To samo robi senior developer, tylko ty robisz to świadomie, bo nie czytasz każdej linijki kodu.

Krok 7, deploy na Vercel

Apka działa lokalnie, czas na produkcję. Najpierw sprawdź, czy projekt buduje się czysto (to wyłapuje błędy, których npm run dev nie pokaże):

npm run build

Jeśli build przechodzi, deployujesz. Dwie drogi. Przez GitHub: wypchnij repo na GitHub, wejdź na vercel.com, połącz repozytorium, Vercel sam wykryje Next.js i postawi apkę. Z terminala:

npx vercel --prod

Po chwili dostajesz publiczny URL. Plan hobby Vercel jest darmowy i w zupełności wystarcza na taki projekt. Domenę custom (np. kalkulator.twojadomena.pl) podepniesz w panelu Vercel w kilka kliknięć, sama domena to koszt 50-80 zł/rok.

Chcesz realnie wysyłać maile z formularza? Poproś Claude: "podłącz Resend API key z .env.local i wysyłaj wycenę mailem przy submit formularza". Pamiętaj, żeby klucz trzymać w .env.local (poza gitem), nie w kodzie. To jeden z antywzorców, do których zaraz wracam.

Modele i koszty tego projektu

Cały ten kalkulator zbudujesz na modelu Sonnet 4.6, to domyślny i właściwy wybór do 80% pracy w kodzie. Model ustawisz w sesji lub flagą:

claude --model sonnet

Alias sonnet bierze najnowszą wersję, alias opus najmocniejszy model. Strategia kosztowa przy budowie apki:

• Sonnet 4.6, default, do generacji i iteracji (cały ten projekt)
• Opus, tylko gdy Sonnet utknie na trudnym bugu albo złożonej architekturze (jest istotnie droższy)
• Haiku 4.5, do prostych, masowych tasków (format, klasyfikacja), rzadko potrzebny przy jednej apce

Realny koszt pierwszego prostego projektu to zwykle kilka-kilkanaście złotych na Anthropic API. Jeśli pracujesz na subskrypcji Claude Pro lub Max, nie liczysz tokenów wcale. Hosting Vercel hobby i Supabase free tier są darmowe na start.

5 antywzorców budowy apki z Claude Code

1. Akceptujesz wszystko bez sprawdzenia. 200 linii, "accept all", jedziesz dalej. Po 50 promptach apka działa, ale nikt nie wie, kiedy się zepsuje. Lekarstwo: smoke test plus pytanie "co właśnie zmieniłeś, 3 zdania" po każdym większym diff.
2. Brak commitów. Projekt rośnie, AI psuje coś podstawowego, nie ma jak wrócić. Lekarstwo: git init w pierwszej minucie, commit po każdej działającej zmianie.
3. Klucze API w kodzie. Resend, Supabase, Stripe, wszystko wklejone wprost do plików i wypchnięte na publiczny GitHub. Lekarstwo: sekrety tylko w .env.local, który jest w .gitignore.
4. Pomijanie Plan Mode. "Po prostu zrób", Claude dociąga 6 bibliotek i robi po swojemu. Lekarstwo: Shift+Tab na plan przy każdym wieloetapowym zadaniu, akceptuj plan świadomie.
5. Zero limitu kosztów. Kilka długich sesji bez kontroli i niespodzianka na fakturze. Lekarstwo: ustaw spending limit w Anthropic Console, default trzymaj na Sonnecie, Opusa odpalaj tylko gdy trzeba.

Co dalej, rozbudowa projektu

Masz działającą, zdeployowaną apkę. To fundament pod większe projekty, które budujesz tym samym rytmem: setup, /init, opis, Plan Mode, generacja, test, deploy. Naturalne następne kroki:

• Baza danych, podłącz Supabase, żeby zapisywać wyceny i leady
• Auth, dodaj logowanie (Supabase Auth lub Clerk), gdy robisz panel użytkownika
• Płatności, integracja Stripe, gdy budujesz mikro-SaaS
• Worktrees, izoluj eksperymenty przez claude -w nazwa, żeby nie psuć głównej gałęzi

Jeśli chcesz uporządkowaną ścieżkę zamiast zbierania wiedzy po artykułach, sprawdź te przewodniki: Claude Code jak zacząć, Claude Code Plan Mode po polsku i vibe coding po polsku.

Najczęściej zadawane pytania

Powiązane artykuły

Claude Code•9 min

Claude Code cena 2026, ile kosztuje i czy jest darmowy

Claude Code cena w PLN i USD, plany Pro i Max, API pay-as-you-go, darmowe kredyty i alternatywy. Najtańsza legalna ścieżka. Stan maj 2026.

Czytaj

Claude Code•9 min

Claude Max plan po polsku, ceny i limity 2026

Plan Claude Max po polsku: ceny Max 5x i 20x, ile zapytań daje, Claude Pro vs Max, Max vs API. Limity sesji i tygodniowe. Stan maj 2026, dla kogo warto.

Czytaj

Claude Code•15 min

Claude Code Skills po polsku, tutorial Agent Skills 2026

Pierwszy polski tutorial Agent Skills w Claude Code. SKILL.md, frontmatter, progressive disclosure, jak tworzyć skille krok po kroku, vs subagents i MCP.

Czytaj