Z promptu do PR z Claude Code — małe zmiany

Dlaczego Prompt-to-PR bije duże jednorazowe promptu

Duże jednorazowe prompty często prowadzą do dużych, nieporządnych zmian: dziesiątki zmodyfikowanych plików, niepowiązane refaktory i kodu, którego nie miałeś czasu zrozumieć. Nawet jeśli wynik jest technicznie poprawny, przegląd wydaje się ryzykowny, bo trudno ustalić, co i dlaczego się zmieniło.

Małe zmiany temu zapobiegają. Gdy każda zmiana jest ograniczona i celowa, możesz ją przeczytać w kilka minut, wcześnie wychwycić błędy i uniknąć psucia rzeczy, których nie miałeś zamiaru dotykać. Recenzenci bardziej ufają małym PR-om, więc mergowanie przebiega szybciej i z mniejszą liczbą komentarzy.

Prompt-to-PR to prosty cykl:

• Poproś o jedną małą zmianę z jasnymi granicami.
• Sprawdź diff i potwierdź, że zgadza się z zamierzeniem.
• Uruchom standardowe checki (testy, lint, build).
• Jeśli coś zawiedzie, zrób re-prompt z dokładnym błędem i kontekstem.
• Powtarzaj, aż PR będzie gotowy do merge.

Ten rytm zamienia porażki w szybki feedback zamiast niespodzianki na końcu. Jeśli prosisz Claude Code o dostosowanie reguły walidacji, ogranicz się do tej jednej reguły. Jeśli test pada, wklej wyjście błędu i poproś o najmniejszą poprawkę, która sprawi, że test przejdzie, a nie o przepisanie całego modułu.

Jedna rzecz się nie zmienia: nadal odpowiadasz za końcowy kod. Traktuj model jak lokalnego partnera-programistę, który szybko pisze, a nie autopilota. To ty decydujesz, co trafi do repo, co zostaje, i kiedy bezpiecznie otworzyć PR.

Przygotuj repo i lokalne środowisko do parowania

Zacznij od czystej bazy. Jeśli twoja gałąź jest za mainem lub testy już nie przechodzą, każda sugestia staje się zgadywanką. Zrób pull najnowszych zmian, zrebase'uj albo scal według preferencji zespołu i upewnij się, że aktualny stan jest zdrowy przed poproszeniem o cokolwiek.

„Lokalny partner-programista” oznacza, że Claude Code edytuje pliki w twoim repo, podczas gdy ty zachowujesz kontrolę nad celem, zasadami i każdym diffem. Model nie zna twojego kodu, jeśli mu go nie pokażesz, więc bądź konkretny co do plików, ograniczeń i oczekiwanego zachowania.

Zanim wyślesz pierwszy prompt, zdecyduj, gdzie będą uruchamiane checki. Jeśli możesz uruchamiać testy lokalnie, feedback przyjdzie w kilka minut, co utrzyma iteracje małe. Jeśli niektóre checki działają tylko w CI (pewne reguły lintu, długie suite'y, kroki builda), ustal kiedy polegasz na CI, aby nie czekać po każdej drobnej zmianie.

Prosty pre-flight:

• Zaktualizuj swoją gałąź i potwierdź, że aplikacja się buduje lub uruchamia.
• Uruchom szybkie checki lokalnie (lint, testy jednostkowe, sprawdzenie typów).
• Zanotuj, które checki są tylko w CI i ile zwykle trwają.
• Potwierdź, że potrafisz odtworzyć problem lub zobaczyć brakującą funkcję jasno.
• Upewnij się, że możesz łatwo cofnąć zmiany (czysty status, małe commity).

Miej mały scratchpad otwarty podczas pracy. Zapisuj ograniczenia jak „bez zmian API”, „zachowaj kompatybilność wsteczną”, „dotknij tylko modułu X” oraz decyzje, które podejmujesz. Gdy test pada, wklej dokładny komunikat o błędzie tam także. Ten scratchpad stanie się najlepszym inputem do następnego promptu i zapobiegnie dryfowi sesji.

Pisanie promptów, które naturalnie prowadzą do małych diffów

Małe diffy zaczynają się od celowo wąskiego promptu. Najszybsza droga do mergowalnego kodu to jedna zmiana, którą możesz przejrzeć w minutę, a nie refactor, który musisz zrozumieć przez godzinę.

Dobry prompt nazywa jeden cel, jeden obszar kodu i jeden oczekiwany rezultat. Jeśli nie potrafisz wskazać, gdzie powinna trafić zmiana (plik, folder, moduł), model będzie zgadywał i diff się rozrośnie.

Kształt promptu, który utrzymuje zmiany zwarte:

• Cel: pojedyncze zachowanie, które chcesz zmienić.
• Lokalizacja: plik(i) lub komponent, które mają być zmienione.
• Ograniczenia: co nie może się zmienić.
• Akceptacja: jak wygląda „gotowe”.
• Rozmiar diffu: wyraźnie poproś o najmniejszą działającą zmianę.

Granice to tajna broń. Zamiast „napraw błąd logowania”, napisz, co musi pozostać bez zmian: „Nie zmieniaj kształtu API”, „Nie zmieniaj nazw publicznych funkcji”, „Bez edycji formatowania”, „Unikaj nowych zależności.” To mówi partnerowi-programiście, gdzie nie próbować być zbyt sprytnym.

Gdy zmiana jest wciąż niejasna, poproś o plan przed kodem. Krótki plan wymusza podział na kroki i daje ci szansę zatwierdzić pierwszy mały ruch.

Goal: Fix the null crash when rendering the profile header.
Location: src/components/ProfileHeader.tsx only.
Constraints: Do not change styling, props, or any exported types.
Expected outcome: If user.name is missing, show "Anonymous" and no crash.
Diff constraint: Minimal diff. No refactors. No unrelated formatting.
If unclear: First reply with a 3-step plan, then wait for approval.

Jeśli pracujesz w zespole, dodaj ograniczenia recenzji: „Trzymaj poniżej ~30 zmienionych linii” albo „Jedynie jeden plik, chyba że to absolutnie konieczne.” To ułatwia skanowanie diffu i sprawia, że kolejne prompt’y są ostrzejsze, gdy coś zawiedzie.

Wybierz właściwą jednostkę pracy dla każdej iteracji

Trzymaj każdą pętlę skupioną na jednej, małej, testowalnej zmianie. Jeśli potrafisz opisać cel jednym zdaniem i przewidzieć, jakie pliki się zmienią, to właściwy rozmiar.

Dobre jednostki pracy to: naprawienie jednego błędu na jednym ścieżce (z reprodukcją i strażnikiem), dopracowanie jednego testu dla jednego zachowania, refactor zachowujący zachowanie (zmiana nazwy, wyciągnięcie funkcji, usunięcie duplikacji) albo poprawa pojedynczego komunikatu o błędzie lub reguły walidacji.

Ogranicz czas każdej pętli. 10–20 minut zwykle wystarcza, by napisać jasny prompt, zastosować diff i uruchomić szybki check. Jeśli nadal eksplorujesz po 20 minutach, zmniejsz jednostkę albo przejdź do fazy badań (notatki, logowanie, nieudany test) i zatrzymaj się.

Zdefiniuj „gotowe” zanim zaczniesz:

• Zmiana pozostaje w zamierzonych plikach i w ramach oczekiwanego zachowania.
• Jeden check dowodzi, że działa (test, lint lub proste uruchomienie).
• Brak nowych warningów lub głośnych zmian formatowania.
• Diff da się opisać w dwóch zdaniach.

Gdy zakres zaczyna rosnąć, zatrzymaj się wcześnie. Jeśli łapiesz się na „przy okazji”, właśnie znalazłeś kolejny iteracyjny task. Zapisz go jako follow-up, skomituj bieżący mały diff i idź dalej.

Przejrzyj diff przed uruchomieniem checków

Zanim uruchomisz testy lub build, przeczytaj diff jak recenzent. To moment, w którym workflow albo pozostaje czysty, albo cicho dryfuje w stronę „dlaczego dotknął tego pliku?”.

Zacznij od poproszenia Claude Code o streszczenie tego, co zmienił prostym językiem: pliki dotknięte, zmiana zachowania i czego nie zmienił. Jeśli nie potrafi jasno wyjaśnić zmiany, diff prawdopodobnie robi za dużo.

Potem przejrzyj samodzielnie. Najpierw zerknięcie na zakres, potem czytanie w kontekście intencji. Szukasz dryftu: niepowiązanego formatowania, dodatkowych refaktorów, zmienionych symboli lub zmian, o które nie prosiłeś.

Szybki pre-check:

• Czy zmienione pliki odpowiadają temu, o co prosiłeś?
• Czy są drive-by edity (zmiany białych znaków, niepowiązane refaktory)?
• Czy wprowadzono nowe zachowanie, o które nie prosiłeś?
• Czy pojawiła się nowa zależność lub zmiana konfiguracji wymagająca uzasadnienia?
• Czy recenzent mógłby to zrozumieć bez czytania pięciu innych plików?

Jeśli diff jest większy niż oczekiwano, nie próbuj rozwiązywać tego testami. Cofnij i ponownie poproś o mniejszy krok. Na przykład: „Najpierw dodaj test reprodukujący błąd. Zero refaktorów.” Małe dify utrzymują porażki łatwiejszymi do interpretacji i czynią kolejny prompt precyzyjnym.

Uruchamiaj checki po każdej małej zmianie

Małe diffy mają sens tylko wtedy, gdy od razu je weryfikujesz. Celem jest ciasna pętla: zmień niewiele, sprawdź niewiele, wychwyć błędy, póki kontekst jest świeży.

Zacznij od najszybszego checku, który może powiedzieć „to jest złe”. Jeśli zmieniłeś formatowanie lub importy, uruchom lint/format najpierw. Jeśli dotknąłeś logiki biznesowej, uruchom najmniejsze jednostkowe testy obejmujące plik lub pakiet. Jeśli edytowałeś typy lub konfigurację builda, zrób szybkie kompilowanie.

Praktyczna kolejność:

• Lint lub format.
• Celowane testy jednostkowe dla zmienionego obszaru.
• Build lub typecheck, żeby potwierdzić zgodność.
• Wolniejsze suite'y (integracja, e2e) po przejściu podstaw.

Gdy coś zawiedzie, zanotuj dwa elementy zanim cokolwiek naprawisz: dokładną komendę i pełny output błędu (skopiuj tak, jak jest). Ten zapis utrzymuje następny prompt konkretnym i zapobiega pętlom „wciąż nie działa”.

Trzymaj zakres wąski. Jeśli lint i testy zawodzą, napraw najpierw lint, uruchom ponownie, potem zajmij się testami. Nie mieszaj „szybkich porządków” z naprawą crasha w tej samej pętli.

Re-promptuj z błędami, aż checki będą zielone

Gdy checki zawodzą, traktuj wyjście błędu jako następny prompt. Najszybsza pętla: wklej błąd, otrzymaj diagnozę, zastosuj minimalną poprawkę, uruchom ponownie.

Wklejaj błędy dosłownie, łącznie z komendą i pełnym stack trace. Poproś najpierw o najbardziej prawdopodobną przyczynę, nie o listę opcji. Claude Code lepiej działa, gdy może zakotwiczyć się w dokładnych numerach linii i komunikatach zamiast zgadywać.

Dodaj jedno zdanie o tym, co już próbowałeś, żeby nie krążyć w kółko. Powtórz ograniczenia, które mają znaczenie („nie zmieniaj publicznych API”, „zachowaj bieżące zachowanie, tylko napraw crash”). Potem poproś o najmniejszy patch, który powoduje przejście checku.

Dobry failure prompt zawiera:

• Dokładne wyjście błędu (dosłownie).
• Plik(i) i linie zaangażowane.
• Co zmieniłeś w ostatnim diffie.
• Co już próbowałeś.
• Prośbę o najmniejszy patch naprawiający check.

Jeśli proponowana poprawka zmienia zachowanie, poproś o test, który udowodni nowe zachowanie jako poprawne. Jeśli handler teraz zwraca 400 zamiast 500, zażądaj jednego skupionego testu, który pada na starym kodzie i przechodzi po poprawce. To trzyma pracę uczciwą i ułatwia zaufanie do PR-a.

Zatrzymaj się, gdy checki są zielone, a diff nadal wygląda jak jedna koncepcja. Jeśli model zaczyna poprawiać niepowiązany kod, re-promptuj: „Tylko zajmij się nieudanym testem. Zero porządków.”

Ułatw PR do przeglądu i mergowania

PR najłatwiej zmergować, gdy jest oczywiste, co się zmieniło, dlaczego i jak to sprawdzić. W tym workflowie PR powinien czytać się jak krótka historia: małe kroki, jasne powody.

Trzymaj commity zgodne z iteracjami. Jeśli poprosiłeś o jedną zmianę zachowania, zrób jeden commit. Jeśli potem naprawiłeś test, zrób kolejny commit. Recenzenci mogą podążać ścieżką i ufać, że nie wprowadziłeś dodatkowych zmian.

Pisz wiadomości commitów mówiące o intencji, nie o nazwach plików. „Napraw przekierowanie po wygaśnięciu sesji” bije „Aktualizuj middleware auth.” Gdy opis nazywa efekt widoczny dla użytkownika, recenzenci mniej zgadują.

Unikaj mieszania refaktorów z zmianami zachowania w tym samym commicie. Jeśli chcesz zmienić nazwy zmiennych lub przenieść helpery — zrób to oddzielnie (albo odpuść teraz). Szum spowalnia review.

W opisie PR trzymaj się krótko i rzeczowo:

• Co się zmieniło (1–2 zdania).
• Dlaczego to się zmieniło (błąd lub wymaganie).
• Jak przetestować (dokładne kroki, łącznie z flagami lub potrzebnymi danymi).
• Czego nie zmieniono (ustawia oczekiwania).
• Ryzyko / notatka o rollbackie.

Przykład: strona billing crashowała z powodu null customer record. Commit 1 dodaje strażnik i czytelny stan błędu. Commit 2 dodaje test dla null case. Opis PR: „Otwórz Billing, załaduj klienta bez profilu, potwierdź, że strona pokazuje nowy stan pusty.” To PR, który recenzenci mogą szybko zaakceptować.

Typowe pułapki, które cię spowalniają

Ten rytm się psuje, gdy zakres cicho się rozszerza. Prompt zaczynający się od „napraw ten nieudany test” zmienia się w „ulepsz obsługę błędów w całym module” i nagle recenzujesz duży diff o niejasnej intencji. Trzymaj to ciasno: jeden cel, jeden zestaw zmian, jeden zestaw checków.

Innym spowalniaczem jest akceptowanie ładniejszych refaktorów tylko dlatego, że wyglądają dobrze. Zmiany nazw, przenoszenie plików i zmiany stylu generują szum w przeglądzie i utrudniają dostrzeżenie rzeczywistej zmiany zachowania.

Typowe pułapki:

• Pozwalanie modelowi dotykać niepowiązanych plików „przy okazji”.
• Naprawianie symptomów (dodatkowe null checki) zamiast przyczyny wskazanej przez test.
• Wklejanie tylko ostatnich linii logów i ukrywanie pierwszego błędu.
• Pomijanie szybkiego przeglądu diffu przed uruchomieniem checków.
• Re-promptowanie z „wciąż nie działa” zamiast z dokładną komendą i outputem.

Konkretna ilustracja: test pada z „expected 400, got 500.” Jeśli wkleisz tylko koniec stack trace, często dostaniesz ogólne sugestie try/catch. Jeśli wkleisz pełne wyjście testu, możesz zobaczyć prawdziwy problem: brakujący branch walidacji. To prowadzi do małego, ukierunkowanego diffu.

Zanim skomitujesz, przeczytaj diff jak recenzent. Zapytaj: czy każda linia służy żądaniu i czy potrafię to wyjaśnić w jednym zdaniu? Jeśli nie, cofnij dodatkowe zmiany i ponownie poproś o węższe zadanie.

Przykład: naprawa błędu do mergowalnego PR-a w kilku pętlach

Użytkownik zgłasza: „Strona ustawień czasami wraca do domyślnych po zapisaniu.” Robisz pull z main, uruchamiasz testy i widzisz jedno niepowodzenie. Albo nie ma testów, jest tylko jasna reprodukcja.

Traktuj to jako pętlę: jedno małe żądanie, jeden mały diff, potem checki.

Najpierw daj Claude Code najmniejszy użyteczny kontekst: output nieudanego testu (lub kroki reprodukcji), ścieżkę pliku, którą podejrzewasz, i cel („zachowaj zachowanie, tylko napraw reset”). Poproś o diagnozę i minimalny patch, nie refactor.

Potem pracuj w krótkich pętlach:

1. Loop 1 (minimalny patch): Zastosuj najmniejszą zmianę, która prawdopodobnie naprawi błąd. Trzymaj to zwartym: warunek strażnika, brakujący null check, zły domyślny, lub błędna lista zależności.

Uruchom checki po przejrzeniu diffu.

2. Loop 2 (odpowiedz z dokładnym błędem): Jeśli testy padają, wklej dokładne wyjście i poproś: „Jaka najmniejsza zmiana naprawi to niepowodzenie bez rozszerzania zakresu?”

Jeśli checki przechodzą, a obawiasz się regresji, dodaj pokrycie testowe.

3. Loop 3 (dostosowanie testu lub nowy test): Dodaj test, który pada bez poprawki i przechodzi z nią. Trzymaj go skupionego na błędzie. Uruchom checki ponownie.

Zakończ z krótkim opisem PR: jaki błąd, dlaczego powstał i co się zmieniło. Dodaj notatkę dla recenzenta: „dotyka tylko pliku X” lub „dodano jeden test dla przypadku resetu”, żeby przegląd był bezpieczny.

Szybka lista kontrolna przed otwarciem PR

Tuż przed otwarciem pull requesta zrób ostatnie sprawdzenie, aby upewnić się, że praca jest łatwa do przeglądu i bezpieczna do zmergowania.

• Diff odpowiada pierwotnemu celowi i jest mały na tyle, by go zrozumieć w kilka minut.
• Uruchomiłeś odpowiednie checki (testy, lint, typecheck, build) i przechodzą. Jeśli używacie CI, potwierdź, że te same checki tam zadziałają.
• Zmiana ma odpowiednie zabezpieczenie: test dla błędu lub funkcji, jeśli to praktyczne, albo jasne uzasadnienie, dlaczego test nie jest potrzebny.
• Opis PR jest konkretny: co zmieniono, dlaczego i dokładne kroki weryfikacji.
• Brak drive-by edytów: niepowiązane formatowanie, zmiany tylko stylu lub refaktory, które nie są konieczne.

Krótki przykład: jeśli naprawiłeś bug logowania, ale też sformatowałeś 20 plików, cofnij commit z formatowaniem. Twój recenzent powinien skupić się na naprawie logowania, a nie zastanawiać się, co jeszcze się przesunęło.

Jeśli którykolwiek punkt zawiedzie, zrób jedną małą pętlę więcej: drobny diff, uruchom checki i zaktualizuj notatki PR. Ta ostatnia pętla często oszczędza godzinę dwie rozmów zwrotnych.

Następne kroki: uczynienie tego rytmu nawykiem

Konsekwencja zmienia dobrą sesję w niezawodny workflow. Wybierz domyślną pętlę i powtarzaj ją za każdym razem. Po tygodniu zauważysz, że twoje prompt’y stają się krótsze, a diffy łatwiejsze do review.

Prosty rytuał:

• Wybierz jeden malutki cel (jeden błąd, jeden edge case, jedna funkcja).
• Poproś o jeden mały diff i krótkie wyjaśnienie, co się zmieniło.
• Przeczytaj diff jak recenzent, potem uruchom checki lokalnie.
• Re-promptuj z dokładnym outputem błędu i nazwami plików.
• Zatrzymaj się w momencie, gdy checki są zielone, a zmiana jest czytelna.

Osobisty szablon promptu pomoże ci zachować dyscyplinę: „Zmieniaj tylko to, co konieczne. Dotykaj maksymalnie 2 plików. Zachowaj publiczne zachowanie, chyba że powiem inaczej. Powiedz mi komendę do uruchomienia i jak wygląda sukces.”

Jeśli budujesz w Koder.ai, możesz użyć tej samej pętli w jego interfejsie chat. Tryb planowania dobrze nadaje się do określenia najmniejszego mergowalnego kawałka (wejścia, wyjścia i kryteria akceptacji), a snapshoty i rollback pomagają szybko odzyskać stan, gdy eksperyment się nie powiedzie.

Gdy zmiana jest stabilna, wyeksportuj źródła, uruchom swoje standardowe narzędzia lokalne, CI i review zespołu. Wdróż, gdy potrzebujesz prawdziwej walidacji w środowisku, np. sprawdzenia przepływu end-to-end.

Uczyń tę pętlę swoim domyślnym sposobem pracy. Małe prompt’y, małe diffy, częste checki i szybkie poprawki dają PR-y, które są nudne w najlepszy możliwy sposób.