Zbuduj pierwszą funkcję z Claude Code

Pierwsza funkcja zbudowana z Claude Code przechodzi przez sześć kroków: zdefiniowanie „gotowe” jako kryteriów akceptacji, zatwierdzenie planu w trybie planowania (plan), utrwalenie zachowania testami, które jeszcze nie przechodzą, implementację w małych krokach sprawdzanych bramkami jakości, przegląd diffu w świeżym kontekście i commit z dowodami. Poprawność potwierdzają testy i bramki, a nie czytanie każdej linii.

Ta strona jest dla programistów, którzy mają już zainstalowany Claude Code i napisany CLAUDE.md, a przed sobą prawdziwy ticket. Funkcja dotyka pięciu plików, wymaga testów i musi przejść CI. Pierwsza próba zwykle kończy się na jeden z dwóch sposobów: prosisz o wszystko naraz i dostajesz diff na 600 linii, którego nie da się ocenić, albo zatwierdzasz ręcznie każdą edycję i robisz tę pracę dwa razy. Pętla opisana poniżej omija oba scenariusze.

Co wyniesiesz z budowy pierwszej funkcji w Claude Code

• Sześciokrokową pętlę do każdej funkcji obejmującej wiele plików, z mechanizmem Claude Code, który napędza każdy krok.
• Siedem promptów do skopiowania, od „zrozum ticket” po „commit z dowodami”.
• Konfigurację uprawnień, dzięki której Claude uruchamia twoje sprawdzenia bez pytania za każdym razem.
• Sposób na zaufanie do wyniku przez sprawdzenie testów i wyników bramek zamiast czytania każdej linii.
• Tabelę objawów i sposobów naprawy dla typowych problemów przy pierwszej funkcji.

Z jakich sześciu kroków składa się budowa funkcji w Claude Code?

Przykładem jest endpoint wyszukiwania pełnotekstowego w REST API w TypeScripcie z bazą PostgreSQL. Podstaw własny ticket; kroki się nie zmieniają.

Krok	Co robisz	Mechanizm Claude Code	Dowód, że zadziałało
1. Zrozumienie	Uzgadniasz kryteria akceptacji	Tryb planowania, odwołania @ do plików	Zatwierdzona, ponumerowana lista kryteriów
2. Plan	Zatwierdzasz plan krok po kroku	Tryb planowania, /effort	Zatwierdzony plan, zapisany w repozytorium zaraz po zatwierdzeniu
3. Utrwalenie zachowania w testach	Zatwierdzasz nieprzechodzące testy	Zwykłe edycje, runner testów	Testy, które nie przechodzą z właściwego powodu
4. Implementacja	Jeden fragment naraz	Reguły allow, hooki	Typy, lint i testy zielone po każdym fragmencie
5. Przegląd	Przegląd w świeżym kontekście	/code-review, subagenty	Lista uwag, każda naprawiona lub odrzucona
6. Commit	Commit z dowodami	Commit w sesji	Opis commita i krótkie podsumowanie dowodów

Zanim zaczniesz, sprawdź warunek wstępny: zainicjuj projekt i napisz CLAUDE.md. Jeśli CLAUDE.md nie podaje poleceń do testów, lintera i sprawdzania typów, dopisz je teraz. Claude uruchamia to, co ten plik mu każe.

Krok 1: Jak sprawić, żeby Claude zrozumiał ticket, zanim cokolwiek zmieni?

Uruchom sesję w trybie planowania. Claude może wtedy czytać i przeszukiwać kod, ale nie edytuje niczego, dopóki nie zatwierdzisz planu:

claude --permission-mode plan -n search-endpoint

Flaga -n nadaje sesji nazwę, dzięki czemu jutro łatwo ją odnajdziesz. W trwającej sesji do tego samego trybu przełącza /plan albo Shift+Tab. Jeśli rzeczywisty schemat istnieje tylko w działającej bazie danych, a nie w plikach migracji, najpierw podłącz serwer bazy danych w trybie tylko do odczytu, tak jak pokazuje konfiguracja MCP w Claude Code.

Prompt do skopiowania: zrozum ticket i zdefiniuj „gotowe”

I need a full-text search endpoint for products. Do not change any files yet.

1. Read the existing routes in @src/api/routes/ and describe the patterns they share:
   validation, error format, pagination, and how they call the database layer.
2. Read the database schema and migrations and tell me how products are stored.
3. List every file you expect to create or modify, and why.
4. Propose acceptance criteria as a numbered list of observable behaviours
   (inputs, outputs, status codes, edge cases such as empty query, no results,
   and a query longer than 200 characters). Each criterion must be testable.

Ask me about anything the ticket leaves ambiguous instead of guessing.

Poprawiaj kryteria, dopóki nie mówią dokładnie tego, co masz na myśli. To kontrakt dla wszystkiego, co nastąpi dalej: testy go zakodują, a przegląd sprawdzi diff względem niego. Więcej o zamianie ticketu na testowalne kryteria znajdziesz w artykule o wykonywalnych kryteriach akceptacji.

Krok 2: Jak dostać plan, który naprawdę da się zatwierdzić?

Poproś o plan, w którym każdy krok wskazuje spełniane kryteria i sprawdzenie, które to potwierdza. Plan bez sprawdzeń to lista zadań; plan ze sprawdzeniami da się później zweryfikować bez ponownego czytania kodu.

Prompt do skopiowania: plan powiązany z kryteriami akceptacji

Write an implementation plan for the search endpoint and present it for my
approval. For each numbered step give:

- the files it touches
- which acceptance criteria it satisfies
- the command that proves the step is done (type check, a named test, a curl call)

Order the steps so each one can be verified on its own. Put the tests first.
Follow the existing cursor-based pagination and the error format used by the
other list endpoints. Do not start implementing until I approve the plan.

Zgłaszaj zastrzeżenia do planu, póki zmiana jest tania:

Use a PostgreSQL GIN index on a tsvector column instead of LIKE, and add the
migration as its own step before the query function.

Jeśli plan pomija oczywiste ograniczenia, najpierw podnieś poziom rozumowania, a dopiero potem myśl o zmianie modelu: /effort high (o stopień wyżej niż domyślne medium w Opus 5.5, domyślnym modelu od v2.1.280; na modelach, które domyślnie mają już high, spróbuj xhigh). Kiedy to się opłaca, opisuje strona o dogłębnym rozumowaniu. Gdy plan jest dobry, zatwierdź go i wyjdź z trybu planowania. W trybie planowania Claude nie może edytować plików repozytorium, więc do tej pory plan istnieje tylko w sesji. Pierwszym poleceniem po zatwierdzeniu niech będzie jego zapisanie:

Save the approved plan to docs/plans/search-endpoint.md. Do not implement anything yet.

Zapisanie planu do pliku znaczy więcej, niż się wydaje. Plik przetrwa /compact, /clear i nową sesję, więc Claude może go ponownie przeczytać, zamiast polegać na pamięci rozmowy. Budowę planu szerzej omawia planowanie funkcji z Claude Code.

Krok 3: Dlaczego testy piszesz przed implementacją?

Testy to ta część zmiany, którą czytasz uważnie. Jeśli poprawnie kodują kryteria akceptacji, zielony wynik mówi ci, że zachowanie jest właściwe, bez czytania każdej linii implementacji. Na tym polega wymiana: uwagę recenzenta poświęcasz 60 liniom testów zamiast 400 liniom kodu.

Prompt do skopiowania: utrwal zachowanie testami, które jeszcze nie przechodzą

Implement only the test step of docs/plans/search-endpoint.md.

Write integration tests for GET /api/search that cover every acceptance
criterion, one test per criterion, named after it. Follow the style of the
existing tests in @tests/api/products.test.ts. Do not write any endpoint code.

Run the new tests and show me the output. Every test should fail because the
endpoint does not exist yet, not because of a setup or import error. If any
test fails for another reason, fix the test setup and run them again.

Zanim pójdziesz dalej, sprawdź dwie rzeczy: każde kryterium ma test, a każdy test nie przechodzi z właściwego powodu. Potem powiedz Claude’owi, że testy są zamrożone:

These tests are now the specification. Do not modify, skip, or delete any of them
for the rest of this session. If you believe a test is wrong, stop and tell me why.

Następnie zacommituj zatwierdzone testy na swojej gałęzi, żeby mieć stały punkt odniesienia do późniejszego porównania:

git add tests/api/search.test.ts
git commit -m "test: pin search endpoint behaviour"

Jeśli twoje CI wymaga, żeby każdy commit przechodził, przed pushem połącz (squash) ten commit z commitem funkcji. Prompt to prośba, a nie gwarancja, dlatego krok 5 sprawdza, czy testy się nie zmieniły. Sprawdzenia, których agent w ogóle nie może edytować, opisuje artykuł o ochronie wyroczni.

Krok 4: Jak implementować po kawałku, nie zatwierdzając każdego polecenia?

Implementuj po jednym kroku planu i po każdym uruchamiaj bramki. Błąd typów znaleziony po jednym fragmencie kosztuje minutę; ten sam błąd znaleziony po pięciu fragmentach zdążył się rozejść po kodzie, który na nim zbudowano.

Zespół DORA z Google Cloud argumentuje tak samo za małymi partiami zmian: „AI can easily generate massive blocks of code, which are hard to review and test. Enforcing the discipline of small batches counteracts this risk” (Nathen Harvey i Allison Park, blog Google Cloud, 2025-12-10).

Pozwól Claude’owi uruchamiać sprawdzenia bez pytania

Dodaj reguły allow dla poleceń sprawdzających w .claude/settings.json, żeby krok bramek nie zatrzymywał się za każdym razem na zatwierdzenie. Użyj nazw skryptów ze swojego projektu:

{
  "permissions": {
    "allow": [
      "Bash(npm run typecheck)",
      "Bash(npm run lint)",
      "Bash(npm test)",
      "Bash(npm test *)"
    ]
  }
}

Od v2.1.283 (oba kanały wydań na 2026-10-12) sesje interaktywne (w terminalu i VS Code, na modelach obsługujących tryb auto) startują w trybie auto (auto), w którym klasyfikator zatwierdza rutynowe akcje. Reguły allow i tak czynią polecenia bramek przewidywalnymi, a najbardziej przydają się w trybie Manual i w uruchomieniach claude -p, które startują w trybie Manual (od v2.1.285 w trybie auto u zewnętrznych dostawców lub z wyłączoną telemetrią). Bash(npm test *) obejmuje npm test -- search i inne warianty z argumentami, a osobna reguła Bash(npm test) obejmuje samo polecenie. Składnię reguł wyjaśnia strona o konfiguracji, a to, na co pozwalać, a na co nigdy, opisuje artykuł o uprawnieniach i sandboxingu.

Żeby sprawdzanie typów uruchamiało się po każdej edycji bez pytania, dodaj hook PostToolUse. Konfigurację pokazuje strona o automatyzacji z hookami.

Prompt do skopiowania: jeden fragment z bramkami

Implement the next unfinished step of docs/plans/search-endpoint.md, and only that step.

When you are done:
1. List the files you changed.
2. Run npm run typecheck, npm run lint, and the tests named in the plan for this step.
3. Show me the summary lines of each command's output.
4. Mark the step as done in the plan file.

If any check fails, fix it before reporting. Do not start the next step.

Powtarzaj ten prompt, aż wszystkie kroki będą gotowe. Gdy fragment pójdzie źle, cofnij się zamiast się spierać: naciśnij dwa razy Esc przy pustym polu promptu (albo uruchom /rewind), żeby przywrócić kod i rozmowę do ostatniego dobrego punktu kontrolnego, a potem daj inny kierunek. Punkty kontrolne szczegółowo opisuje strona o wychodzeniu z błędów.

Sprawdź działającą funkcję, nie tylko testy

Testy jednostkowe i integracyjne mogą przechodzić, a endpoint wciąż źle działać przez HTTP, na przykład z powodu brakującej rejestracji trasy albo middleware’u, który przepisuje odpowiedź.

Prompt do skopiowania: test end-to-end na serwerze deweloperskim

Start the dev server if it is not running. Then call the new endpoint with curl
and show me each request and response:

1. a valid query that should return results
2. an empty query (expect the validation error from the acceptance criteria)
3. a query that matches nothing (expect an empty list, status 200)
4. the second page, using the cursor from the first response

Compare each response with the acceptance criteria and list any mismatch.
Stop the dev server when you finish.

Krok 5: Jak przejrzeć diff bez czytania każdej linii?

Sesja, która napisała kod, jest jego najsłabszym recenzentem, bo dzieli założenia, z których ten kod powstał. Rób przegląd w świeżym kontekście. W Claude Code 2.1.283 /code-review to wbudowany skill, który przegląda commity gałęzi wyprzedzające jej upstream oraz wszystkie niezacommitowane zmiany. Działa jako subagent w tle z własnym oknem kontekstu, więc nie dziedziczy rozmowy z implementacji. Bez upstreamu porównuje z main; inny cel podasz jako nazwę gałęzi lub numer PR, np. /code-review search-endpoint.

/code-review

Potem uruchom sprawdzenia, których recenzent nie zobaczy w samym diffie.

Prompt do skopiowania: sprawdź zmianę względem kontraktu

Check this branch against docs/plans/search-endpoint.md and the acceptance criteria:

1. Find the commit "test: pin search endpoint behaviour", run
   git diff --stat <that commit> -- '*.test.ts', and tell me whether any
   approved test was modified, skipped, or deleted since then.
2. For each acceptance criterion, name the test that covers it and confirm it passes.
3. Run the full test suite, npm run typecheck, and npm run lint, and report the totals.
4. List any file changed that the plan did not mention, and explain why.

Report facts only. Do not fix anything in this step.

Zamiast całego diffu czytasz teraz cztery krótkie rzeczy: uwagi z przeglądu, listę zmian w plikach testów, mapowanie kryteriów na testy i ewentualne nieplanowane pliki. Kod czytasz tylko tam, gdzie któraś z nich wskazuje problem. Przed commitem napraw albo świadomie odrzuć każdą uwagę.

Przy zmianie wysokiego ryzyka /code-review ultra uruchamia w chmurze przegląd wieloagentowy, który odtwarza każde znalezisko. Po trzech darmowych uruchomieniach na planach Pro i Max kosztuje zwykle od 5 do 25 USD za przegląd w kredytach użycia. Nie jest dostępny na Bedrock, Google Cloud, Microsoft Foundry ani dla organizacji z Zero Data Retention.

Krok 6: Jak zacommitować zmianę, żeby recenzent mógł jej zaufać?

Poproś Claude’a o commit w sesji. Napisze opis na podstawie faktycznego diffu i może dołączyć dowody z kroku 5.

Prompt do skopiowania: commit z dowodami

Commit these changes using Conventional Commits. In the commit body include:
- what the endpoint does, in two sentences
- the acceptance criteria and the test that covers each one
- the final type check, lint, and test totals
- the /code-review findings you fixed and the ones I dismissed, with the reason

Claude Code 2.1.283 nie ma podpolecenia claude commit. Commituj w sesji jak wyżej, uruchom git commit samodzielnie albo użyj trybu headless z powłoki. Uruchomienie claude -p startuje w trybie Manual (od v2.1.285 w trybie auto u zewnętrznych dostawców lub z wyłączoną telemetrią) i nie może cię o nic zapytać, więc zezwól na potrzebne polecenia git:

claude -p "Commit the staged changes with a Conventional Commits message" \
  --allowedTools "Bash(git diff *)" "Bash(git commit *)"

Gałęzie, pull requesty i dzielenie splątanego diffu na kilka commitów opisuje strona o kontroli wersji z Claude Code. Pełny pakiet dowodów do PR opisuje artykuł o pakiecie dowodów.

Kto zatwierdza: ty zatwierdzasz kryteria akceptacji, testy i podsumowanie dowodów. Recenzent z twojego zespołu sprawdza te same dowody i czyta kod tam, gdzie dowody na to wskazują. Żadne z was nie musi czytać każdej linii, żeby wiedzieć, że endpoint działa zgodnie ze specyfikacją.

Jak utrzymać dłuższą funkcję na kursie przez kilka sesji?

Funkcja rozciągnięta na kilka podejść pozostaje spójna, gdy jej stan żyje w plikach, a nie w rozmowie. Tym stanem są plik planu z kroku 2 i testy z kroku 3.

• Wznów pracę od ostatniego miejsca: claude -c kontynuuje ostatnią rozmowę w bieżącym katalogu. claude -r search-endpoint otwiera wybór sesji przefiltrowany tym hasłem.
• Zwolnij kontekst: /compact keep the plan file path, the acceptance criteria, and the failing tests streszcza rozmowę i zachowuje to, co wymienisz.
• Zacznij od czystej karty: /clear, a potem Read docs/plans/search-endpoint.md and continue with the next unfinished step.
• Wskazuj konkretne pliki: Add a category filter to @src/api/routes/search.ts following @src/api/routes/products.ts jest bezpieczniejsze niż „zaktualizuj moduł wyszukiwania”.

Dziel pracę według planu, a nie według zegara: schemat i migracja w jednej sesji, zapytanie i trasa w następnej, przegląd i commit w ostatniej.

Co się psuje przy budowie funkcji z Claude Code?

Objaw	Prawdopodobna przyczyna	Naprawa
Diff na 600 linii, którego nie da się ocenić	Prompt prosił o całą funkcję naraz	Cofnij się przez Esc Esc albo /rewind i uruchamiaj prompt z kroku 4 po jednym kroku planu
Testy przechodzą, ale plik testów zmienił się po zatwierdzeniu	Claude dopasował test do kodu	Przywróć testy z commita testów przez git checkout TEST_COMMIT -- tests/api/search.test.ts (TEST_COMMIT to hash twojego commita test:), powtórz polecenie „testy są specyfikacją” i uruchom fragment ponownie
Testy przechodzą, ale endpoint nie działa przez HTTP	Testy mockują warstwę, która jest zepsuta	Uruchom prompt end-to-end z kroku 4, a potem dodaj test integracyjny dla nieudanego żądania
Claude edytuje pliki, których plan nie wymienia	Nieprecyzyjne odwołania do plików	Używaj odwołań @ do dokładnych ścieżek i poproś Claude’a o uzasadnienie każdego nieplanowanego pliku, zanim pójdzie dalej
Nowy kod ignoruje twoje konwencje	CLAUDE.md ich nie opisuje	Dopisz brakującą regułę do CLAUDE.md, każ Claude’owi przeczytać go ponownie i powtórzyć fragment
Ta sama poprawka zawodzi trzy razy	Claude utknął w jednym podejściu	Wpisz „Stop. That approach is not working. List two alternatives and their trade-offs.” Jeśli pętla trwa, użyj /clear i zacznij od pliku planu
Claude zapomina decyzje sprzed godziny	Kontekst wypełniły stare wyniki narzędzi	/compact z wyraźnymi instrukcjami, co zachować, albo /clear i ponowne przeczytanie pliku planu

Dokąd dalej po pierwszej funkcji w Claude Code

Kontrola wersji z Claude Code Gałęzie, dzielenie commitów, pull requesty i worktree.

Wychodzenie z błędów Punkty kontrolne, rewind, pętle poprawek i przeładowany kontekst.

Testowanie z Claude Code Generowanie testów, TDD z agentem i luki w pokryciu.

Ścieżka dewelopera Ścieżka od pierwszej sesji do zweryfikowanej pracy autonomicznej.

Pracujesz w innym narzędziu? Ta sama pętla jest opisana dla Codexa w pierwszym zadaniu i dla Cursora w pierwszej funkcji.