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:

1. Zrozum — Niech Claude przeanalizuje wymaganie i dotknięty kod
2. Zaplanuj — Uzyskaj ustrukturyzowany plan implementacji przed jakimikolwiek edycjami
3. Zaimplementuj — Buduj przyrostowo, jeden komponent na raz
4. Zweryfikuj — Uruchamiaj testy, sprawdzaj typy i lintuj po każdej zmianie
5. Przejrzyj — Niech Claude przejrzy swoją własną pracę pod kątem problemów
6. 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:

Wskazówka

Prompt do skopiowania na start funkcji:

I need to add a full-text search endpoint to our API. Before writing
any code, I need you to:

1. Read the existing API routes and understand the current patterns
2. Check how the database is set up (schema, ORM, migrations)
3. Look at how existing endpoints handle validation and error responses
4. Identify the files I will need to create or modify

Do not make any changes yet.

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:

Based on your analysis, create an implementation plan for the search
endpoint. I want:

1. The route path and HTTP method
2. Input validation schema
3. Database query approach
4. Response format matching existing endpoints
5. Error handling following current patterns
6. Test cases we need

Number each step. Do not write code until I approve.

Przejrzyj plan. Odrzuć tam, gdzie potrzeba:

Change the database query to use a GIN index instead of LIKE.
Also, add pagination to the response -- our other list endpoints
use cursor-based pagination, not offset.

Krok 3: Implementacja przyrostowa

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

Implement step 1 from the plan: create the Zod validation schema
for the search endpoint in the existing validators file.

Po dokonaniu zmiany przez Claude, zweryfikuj:

Run the type checker to make sure the new schema is valid.

Następnie przejdź do kolejnego kroku:

Now implement step 2: the database query function. Use the existing
query patterns from the users module as a reference.

Wskazówka

Prompt do skopiowania dla przyrostowej implementacji:

Implement the next step from our plan. After making the changes:
1. Show me exactly what files you modified
2. Run the type checker
3. Run the relevant tests
4. Tell me if anything failed

Do not move to the next step until this one passes all checks.

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. To są prompty, które dajesz Claude, a nie polecenia powłoki — Claude uruchamia za Ciebie odpowiednie narzędzia.

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 zaimplementowaniu logiki uruchom odpowiednie 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 kompletny zestaw testów i linter. Pokaż mi podsumowanie wszelkich awarii.

Notatka

Jeśli pozwoliłeś na Bash(npm run test *) w swoich ustawieniach, Claude może uruchamiać testy bez pytania cię. To sprawia, że krok weryfikacji jest niemal natychmiastowy. Zobacz poradnik konfiguracji dla ustawień uprawnień.

Krok 5: Autoreview

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

Wskazówka

Prompt do skopiowania dla autoreview:

Review all the changes you have made in this session. Check for:

1. Missing error handling or edge cases
2. Security issues (SQL injection, unvalidated input, data leaks)
3. Performance concerns (N+1 queries, missing indexes, large payloads)
4. Inconsistencies with existing code patterns
5. Missing or inadequate tests

Be critical. What would a senior engineer flag in 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, po prostu poproś Claude o commit w trakcie sesji:

Commit these changes with a descriptive message that explains what
was added and why. Use conventional commit format.

Claude generuje komunikat commit na podstawie faktycznego diff, nie ogólnego opisu. Nie ma podpolecenia claude commit — commituj, prosząc o to w sesji jak powyżej, uruchamiając git commit samodzielnie albo, dla jednorazowego polecenia z powłoki, w trybie bezgłowym:

claude -p "commit the staged changes with a conventional commit message"

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:

Re-read our CLAUDE.md and the existing search module at
@src/modules/search/. Then continue implementing the response
formatter using the same patterns.

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, aby kontynuować jedną, ostatnią rozmowę, albo claude -r "<session-name>" "<query>", aby wznowić konkretną wcześniejszą sesję po ID lub nazwie (na przykład claude -r "schema-changes" "now add the migration"). 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:

# Instead of this:
Update the search module to add filtering

# Do this:
Add a category filter parameter to @src/api/routes/search.ts
following the pattern used in @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:

Start the dev server, then make a curl request to the new search
endpoint with the query "typescript". Show me the response.

Wskazówka

Prompt do skopiowania dla weryfikacji end-to-end:

Start the dev server if it is not already running. Then test the
new feature by:

1. Making a request with valid input and showing the response
2. Making a request with invalid input and showing the error response
3. Making a request that should return empty results
4. Checking that pagination works correctly

Report any issues you find.

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