Budowanie pierwszej funkcji z Claude Code

Masz zainstalowany, skonfigurowany Claude Code połączony z twoimi narzędziami. Twój CLAUDE.md opisuje twój projekt. Teraz czas faktycznie coś zbudować. Nie zabawkowy przykład — prawdziwą funkcję, która dotyka wielu plików, potrzebuje testów i musi przejść twój pipeline CI.

Ten poradnik prowadzi przez pełny cykl rozwoju: zrozumienie wymagania, implementację w wielu plikach, uruchamianie testów, debugowanie błędów i przygotowanie czystego PR. Zobaczysz dokładne prompty, które utrzymują Claude skupionego i produktywnego.

Co wyniesiesz z tego poradnika

Powtarzalny workflow dla rozwoju funkcji z Claude Code
Prompty produkujące kod jakości produkcyjnej, nie prototypy
Strategie utrzymywania Claude na właściwej ścieżce podczas zmian w wielu plikach
Wzorce przyrostowej implementacji z weryfikacją na każdym kroku

Pętla rozwoju

Każda funkcja podąża za tym samym podstawowym cyklem:

Zrozum — Niech Claude przeanalizuje wymaganie i dotknięty kod
Zaplanuj — Uzyskaj ustrukturyzowany plan implementacji przed jakimikolwiek edycjami
Zaimplementuj — Buduj przyrostowo, jeden komponent na raz
Zweryfikuj — Uruchamiaj testy, sprawdzaj typy i lintuj po każdej zmianie
Przejrzyj — Niech Claude przejrzy swoją własną pracę pod kątem problemów
Commituj — Twórz czyste, opisowe commity

Przejdźmy przez każdy krok z prawdziwym przykładem: dodawaniem endpointu wyszukiwania do REST API.

Krok 1: Zrozumienie bazy kodu i wymagania

Zacznij każdą funkcję od dania Claude pełnego kontekstu:

Prompt do skopiowania na start funkcji:

Muszę dodać endpoint wyszukiwania pełnotekstowego do naszego API. Zanim
napiszesz jakikolwiek kod, potrzebuję, żebyś:

1. Przeczytał istniejące routy API i zrozumiał obecne wzorce
2. Sprawdził jak skonfigurowana jest baza danych (schemat, ORM, migracje)
3. Spojrzał jak istniejące endpointy obsługują walidację i odpowiedzi błędów
4. Zidentyfikował pliki, które będę musiał utworzyć lub zmodyfikować

Nie rób jeszcze żadnych zmian.

Claude przeczyta twoją bazę kodu, zidentyfikuje odpowiednie wzorce i da ci podsumowanie. Ten krok zapobiega najczęstszemu błędowi: Claude generuje kod, który nie pasuje do twoich istniejących wzorców.

Krok 2: Planowanie przed kodowaniem

Gdy Claude zrozumie bazę kodu, poproś o plan:

Na podstawie twojej analizy stwórz plan implementacji endpointu
wyszukiwania. Chcę:

1. Ścieżkę routu i metodę HTTP
2. Schemat walidacji danych wejściowych
3. Podejście do zapytania bazodanowego
4. Format odpowiedzi pasujący do istniejących endpointów
5. Obsługę błędów zgodną z obecnymi wzorcami
6. Przypadki testowe, które potrzebujemy

Ponumeruj każdy krok. Nie pisz kodu, dopóki nie zatwierdzę.

Przejrzyj plan. Odrzuć tam, gdzie potrzeba:

Zmień zapytanie bazodanowe na użycie indeksu GIN zamiast LIKE.
Również dodaj paginację do odpowiedzi -- nasze inne endpointy
listy używają paginacji opartej na kursorze, nie offset.

Krok 3: Implementacja przyrostowa

Nie proś Claude o implementację wszystkiego naraz. Buduj jeden element na raz:

Zaimplementuj krok 1 z planu: stwórz schemat walidacji Zod
dla endpointu wyszukiwania w istniejącym pliku validatorów.

Po dokonaniu zmiany przez Claude, zweryfikuj:

Uruchom type checker, aby upewnić się, że nowy schemat jest prawidłowy.

Następnie przejdź do kolejnego kroku:

Teraz zaimplementuj krok 2: funkcję zapytania bazodanowego. Użyj
istniejących wzorców zapytań z modułu users jako odniesienia.

Prompt do skopiowania dla przyrostowej implementacji:

Zaimplementuj następny krok z naszego planu. Po dokonaniu zmian:
1. Pokaż mi dokładnie, które pliki zmodyfikowałeś
2. Uruchom type checker
3. Uruchom odpowiednie testy
4. Powiedz mi, czy coś się nie powiodło

Nie przechodź do następnego kroku, dopóki ten nie przejdzie wszystkich sprawdzeń.

To przyrostowe podejście wychwytuje problemy wcześnie. Jeśli zapytanie bazodanowe Claude ma błąd typu, wychwytasz go przed zbudowaniem handlera routu na jego podstawie.

Krok 4: Weryfikacja na każdym kroku

Uczyń weryfikację nawykiem, nie przemyśleniem:

# Po każdej zmianie poproś Claude o uruchomienie sprawdzeń
Uruchom npm run type-check i npm run lint. Napraw wszelkie błędy przed kontynuowaniem.

# Po implementacji logiki uruchom testy
Uruchom testy dla modułu wyszukiwania. Jeśli jakieś się nie powiodą, przeanalizuj
awarię i napraw ją przed dalszym postępem.

# Po zakończeniu całej implementacji uruchom pełny zestaw
Uruchom pełny zestaw testów i lintera. Pokaż mi podsumowanie
wszelkich awarii.

Krok 5: Autoreview

Zanim commitniesz, niech Claude przejrzy swoje własne zmiany:

Prompt do skopiowania dla autoreview:

Przejrzyj wszystkie zmiany, które dokonałeś w tej sesji. Sprawdź:

1. Brakującą obsługę błędów lub przypadki brzegowe
2. Problemy bezpieczeństwa (SQL injection, niezwalidowane dane wejściowe, wycieki danych)
3. Obawy o wydajność (zapytania N+1, brakujące indeksy, duże payloady)
4. Niespójności z istniejącymi wzorcami kodu
5. Brakujące lub nieodpowiednie testy

Bądź krytyczny. Co wychwyciliby senior developer w code review?

Claude często wychwytuje problemy, które sam wprowadził — brakujące sprawdzenia null, niespójne formaty błędów lub testy, które nie pokrywają przypadków brzegowych. Napraw te przed PR.

Krok 6: Commit i czyszczenie

Gdy jesteś zadowolony z implementacji:

Commitnij te zmiany z opisowym komunikatem wyjaśniającym, co
zostało dodane i dlaczego. Użyj formatu conventional commit.

Lub użyj dedykowanej komendy commit:

claude commit

Claude generuje komunikat commit na podstawie faktycznego diff, nie ogólnego opisu.

Praktyczne wskazówki dla zachowania produktywności

Utrzymuj Claude skupionego

Długie sesje prowadzą do dryfowania. Jeśli Claude zaczyna tracić kontekst o twoich wzorcach:

Przeczytaj ponownie nasz CLAUDE.md i istniejący moduł wyszukiwania w
@src/modules/search/. Następnie kontynuuj implementację formatera
odpowiedzi używając tych samych wzorców.

Dziel duże funkcje na sesje

Dla funkcji zajmujących więcej niż 30-40 minut, podziel je na wiele sesji:

Sesja 1: Schemat i zmiany bazodanowe
Sesja 2: Ruta API i logika biznesowa
Sesja 3: Testy i integracja
Sesja 4: Review, dopracowanie i PR

Użyj claude -c do kontynuowania najnowszej rozmowy lub zacznij na świeżo z claude, jeśli chcesz czysty kontekst.

Używaj /compact gdy kontekst staje się ciężki

Jeśli odpowiedzi Claude zaczynają się pogarszać lub wydaje się zapominać wcześniejsze decyzje:

/compact

To podsumowuje rozmowę i zwalnia miejsce kontekstowe. Śledź to krótkim przypomnieniem, nad czym pracujesz.

Odnośniki do konkretnych plików

Zamiast niejasnych żądań, wskaż Claude na dokładne pliki:

# Zamiast tego:
Zaktualizuj moduł wyszukiwania, aby dodać filtrowanie

# Zrób to:
Dodaj parametr filtra kategorii do @src/api/routes/search.ts
według wzorca użytego w @src/api/routes/products.ts

Pozwól Claude uruchomić twój serwer deweloperski

Dla aplikacji webowych Claude może uruchomić twój serwer deweloperski i sprawdzić wyniki:

Uruchom serwer deweloperski, następnie wykonaj żądanie curl do nowego
endpointu wyszukiwania z zapytaniem "typescript". Pokaż mi odpowiedź.

Prompt do skopiowania dla weryfikacji end-to-end:

Uruchom serwer deweloperski, jeśli nie jest już uruchomiony. Następnie przetestuj
nową funkcję przez:

1. Wykonanie żądania z prawidłowymi danymi wejściowymi i pokazanie odpowiedzi
2. Wykonanie żądania z nieprawidłowymi danymi wejściowymi i pokazanie odpowiedzi błędu
3. Wykonanie żądania, które powinno zwrócić puste wyniki
4. Sprawdzenie, czy paginacja działa poprawnie

Zgłoś wszelkie znalezione problemy.

Antywzorce

Proszenie o wszystko naraz — “Zbuduj kompletną funkcję wyszukiwania z testami, paginacją, cachowaniem i monitoringiem” wyprodukuje przeciętny kod. Rozłóż to.

Brak weryfikacji między krokami — Jeśli pozwolisz Claude zaimplementować pięć plików przed uruchomieniem type checkera, spędzisz więcej czasu na naprawianiu kaskadowych błędów niż zaoszczędziłeś.

Akceptowanie kodu bez jego zrozumienia — Claude wyjaśni swoje zmiany, jeśli zapytasz. Jeśli nie rozumiesz, dlaczego coś zostało zrobione w określony sposób, zapytaj: “Dlaczego użyłeś kursora zamiast offsetu dla paginacji?”

Ignorowanie CLAUDE.md — Jeśli Claude ciągle generuje kod niezgodny z twoimi wzorcami, twój CLAUDE.md brakuje kluczowych informacji. Zaktualizuj go i powiedz Claude, aby go ponownie przeczytał.

Kiedy to nie działa

Claude modyfikuje złe pliki — Bądź precyzyjny co do ścieżek plików. Używaj wzmianek @ do odnoszenia się do dokładnych plików zamiast opisywania ich nazwą.

Wygenerowany kod się nie kompiluje — Uruchamiaj type checker po każdej zmianie. Jeśli Claude generuje błędy TypeScript, powiedz mu: “Type checker znalazł błędy. Napraw je przed kontynuowaniem.”

Testy przechodzą, ale funkcja nie działa — Testy mogą nie pokrywać faktycznego zachowania. Poproś Claude o przetestowanie funkcji end-to-end z prawdziwym żądaniem, nie tylko testami jednostkowymi.

Claude utyka w pętli — Jeśli Claude ciągle próbuje tego samego podejścia i zawodzi, przerwij nowym kierunkiem: “Stop. To podejście nie działa. Zamiast tego spróbuj [alternatywne podejście].” Czasami /clear i świeży start jest szybszy niż naprawianie zdezorientowanej sesji.

Co dalej

Mając zaimplementowaną funkcję, naucz się zarządzać branchami, tworzyć czyste commity i otwierać PR z integracją git Claude Code.

Kontrola wersji Integracja Git, commity i PR

Naprawianie błędów Obsługa awarii i odzyskiwanie z błędów