Wyznaczanie zakresu zadań w Claude Code: od niejasnych próśb do commitów

Dlaczego niejasne zgłoszenia funkcji marnują czas

Niejasne prośby brzmią niewinnie: „Dodaj lepszą wyszukiwarkę”, „Uprość onboarding”, „Użytkownicy potrzebują powiadomień.” W rzeczywistych zespołach zwykle trafiają jako jednozdaniowy wpis na czacie, zrzut ekranu ze strzałkami albo półzapamiętana rozmowa z klientem. Wszyscy się zgadzają, ale każdy wyobraża sobie coś innego.

Koszt pojawia się później. Gdy zakres jest niejasny, ludzie działają na domysłach. Pierwsze demo zamienia się w kolejną rundę wyjaśnień: „To nie o to mi chodziło.” Praca jest przerabiana, a zmiana cicho się rozrasta. Poprawki projektowe wywołują zmiany w kodzie, potem więcej testów. Przeglądy spowalniają, bo nieostre zmiany ciężko zweryfikować. Jeśli nikt nie potrafi powiedzieć, jak wygląda „poprawne” zachowanie, recenzenci debatują nad zachowaniem zamiast sprawdzać jakość.

Zwykle można rozpoznać niejasne zadanie wcześnie:

• Brak przykładu krok po kroku, co użytkownik ma zrobić
• Brak przypadków brzegowych (stany puste, uprawnienia, błędy)
• Prace „na wszelki wypadek”, które puchną do ogromnego PR-a
• Komentarze w przeglądzie kłócące się o zachowanie, nie o implementację
• „Ustalimy po drodze” staje się planem

Dobrze sprofilowane zadanie daje zespołowi linię mety: jasne kryteria akceptacji, minimalny plan UI i API oraz wyraźne granice tego, co nie jest w zakresie. To różnica między „ulepszyć wyszukiwanie” a małą zmianą, którą łatwo zbudować i zrecenzować.

Jednym z praktycznych nawyków jest oddzielenie „definicji ukończenia” od „miło-by-było”. „Ukończone” to krótka lista kontroli, które można uruchomić (na przykład: „Wyszukiwanie zwraca wyniki po tytule, pokazuje ‘Brak wyników’ gdy puste i zachowuje zapytanie w URL”). „Miło-by-było” to wszystko, co może poczekać (synonimy, dopracowanie rankingów, podświetlanie, analityka). Oznaczenie tego z góry zapobiega niezamierzonemu rozszerzaniu zakresu.

Zacznij od rezultatu, nie od rozwiązania

Niejasne prośby często zaczynają się od proponowanych poprawek: „Dodaj przycisk”, „Przejdź na nowy flow”, „Użyj innego modelu”. Zrób pauzę i najpierw przetłumacz sugestię na rezultat.

Prosty format pomaga: „Jako [użytkownik], chcę [zrobić coś], aby [osiągnąć cel].” Trzymaj to prosto. Jeśli nie potrafisz powiedzieć tego jednym zdaniem, to wciąż jest zbyt niejasne.

Następnie opisz, co się zmienia dla użytkownika, gdy zadanie będzie skończone. Skoncentruj się na widocznym zachowaniu, nie na szczegółach implementacyjnych. Na przykład: „Po wysłaniu formularza widzę potwierdzenie i mogę znaleźć nowy rekord na liście.” To daje jasną linię mety i utrudnia wkradnięcie się „jeszcze jednej poprawki”.

Zapisz też, co zostaje bez zmian. Non-goals chronią zakres. Jeśli prośba brzmi „ulepszyć onboarding”, non-goalem może być „bez redesignu dashboardu” albo „bez zmian logiki planów cenowych”.

Na koniec wybierz jedną główną ścieżkę do obsłużenia najpierw: pojedynczy end-to-end kawałek, który udowadnia, że funkcja działa.

Przykład: zamiast „dodać snapshoty wszędzie”, napisz: „Jako właściciel projektu mogę przywrócić najnowszy snapshot aplikacji, aby cofnąć złą zmianę.” Non-goals: „bez masowego przywracania, bez redesignu UI”.

Zadaj kilka pytań, które usuwają niejednoznaczność

Niejasne zgłoszenie rzadko brakuje pracy. Brakuje decyzji.

Zacznij od ograniczeń, które potajemnie zmieniają zakres. Terminy są ważne, ale równie istotne są reguły dostępu i wymagania zgodności. Jeśli budujesz na platformie z planami i rolami, zdecyduj wcześnie, kto dostaje funkcję i w jakim planie.

Potem poproś o jeden konkretny przykład. Zrzut ekranu, zachowanie konkurencji albo poprzedni ticket ujawniają, co znaczy „lepiej”. Jeśli zleceniodawca nie ma przykładu, poproś, by odtworzył ostatni raz, kiedy odczuł problem: na jakim ekranie był, co kliknął, czego oczekiwał?

Przypadki brzegowe to miejsce, gdzie zakres puchnie, więc nazwij największe z nich wcześnie: brak danych, błędy walidacji, wolne lub nieudane połączenia sieciowe oraz co naprawdę znaczy „cofnij”.

Na koniec ustal, jak zweryfikujecie sukces. Bez testowalnego wyniku zadanie zamienia się w opinie.

Te pięć pytań zwykle usuwa największą część niejednoznaczności:

• Kto ma dostęp (poziom i role)?
• Jaki jest termin i jaka jest najmniejsza akceptowalna wersja?
• Jaki jest jeden przykład oczekiwanego zachowania?
• Co się dzieje w pustych stanach, przy błędach i przy wolnym łączu?
• Jak potwierdzimy, że to działa (konkretne kryteria lub metryka)?

Przykład: „Dodaj custom domains dla klientów” staje się jaśniejsze, gdy zdecydujesz, do którego planu należy, kto może to skonfigurować, czy lokalizacja hostingu ma znaczenie dla zgodności, jaki błąd pokażesz przy nieprawidłowym DNS i co znaczy „gotowe” (domena zweryfikowana, HTTPS aktywne i bezpieczny plan rollbacku).

Zamień chaotyczne notatki w kryteria akceptacji

Chaotyczne prośby mieszają cele, domysły i półpamiętane przypadki brzegowe. Zadaniem jest przekształcić to w stwierdzenia, które każdy może przetestować bez czytania w myślach. Te same kryteria powinny prowadzić projekt, kodowanie, przegląd i QA.

Prosty wzorzec utrzymuje jasność. Możesz użyć Given/When/Then albo krótkich punktów znaczących to samo.

Krótki szablon kryteriów akceptacji

Napisz każde kryterium jako pojedynczy test, który ktoś może wykonać:

• Given stan początkowy, when użytkownik robi X, then Y się dzieje.
• Uwzględnij reguły walidacji (jakie dane wejściowe są dozwolone).
• Dołącz przynajmniej jeden przypadek błędny (jaki błąd widzi użytkownik).
• Zdefiniuj „sygnał ukończenia” (co QA sprawdza, czego oczekują recenzenci).

Teraz zastosuj to w praktyce. Załóżmy, że notatka mówi: „Ułatwić snapshoty. Chcę cofnąć, jeśli ostatnia zmiana coś zepsuła.” Zamień to w testowalne stwierdzenia:

• Given projekt z 2 snapshotami, when otwieram Snapshots, then widzę oba z czasem i krótką etykietą.
• Given snapshot, when klikam Roll back i potwierdzam, then projekt wraca do tego snapshotu i aplikacja buduje się pomyślnie.
• Given że nie jestem właścicielem projektu, when próbuję cofnąć, then widzę błąd i nic się nie zmienia.
• Given rollback w trakcie, when odświeżam stronę, then nadal widzę status i końcowy wynik.
• Given rollback się nie powiódł, when się zatrzyma, then widzę jasny komunikat, a bieżąca wersja pozostaje aktywna.

Jeśli QA może uruchomić te sprawdzenia, a recenzenci zweryfikować je w UI i logach, jesteś gotowy zaplanować prace UI i API oraz podzielić je na małe commity.

Szkic minimalnego planu UI

Minimalny plan UI to obietnica: najmniejsza widoczna zmiana, która udowadnia, że funkcja działa.

Zacznij od nazwania ekranów, które się zmienią, i co osoba zauważy w ciągu 10 sekund. Jeśli prośba brzmi „ułatwić” albo „uporządkować”, przetłumacz to na jedną konkretną zmianę, którą możesz wskazać.

Napisz to jako małą mapę, nie redesign. Na przykład: „Strona zamówień: dodaj pasek filtrów nad tabelą” albo „Ustawienia: dodaj nowy przełącznik w sekcji Powiadomień.” Jeśli nie potrafisz nazwać ekranu i dokładnego elementu, który się zmienia, zakres wciąż jest niejasny.

Zdefiniuj kluczowe stany UI

Większość zmian UI potrzebuje kilku przewidywalnych stanów. Wypisz tylko te, które mają zastosowanie:

• Ładowanie
• Pusty widok
• Błąd (i czy istnieje retry)
• Sukces (toast, komunikat inline, zaktualizowana lista)

Potwierdź teksty, które zobaczy użytkownik

Kopia UI jest częścią zakresu. Zanotuj etykiety i komunikaty, które muszą zostać zaakceptowane: tekst przycisków, etykiety pól, tekst pomocniczy i komunikaty o błędach. Jeśli sformułowanie jest otwarte, oznacz je jako zastępczy tekst i zapisz, kto to potwierdzi.

Trzymaj małą notatkę „nie teraz” dla wszystkiego, co nie jest wymagane do używania funkcji (polerka responsywna, sortowania zaawansowane, animacje, nowe ikony).

Szkic minimalnego planu API i danych

Zadanie o ograniczonym zakresie potrzebuje małego, jasnego kontraktu między UI, backendem i danymi. Cel nie jest projektować cały system, tylko zdefiniować najmniejszy zestaw zapytań i pól, które udowodnią, że funkcja działa.

Zacznij od listy danych, których potrzebujesz i skąd pochodzą: istniejące pola do odczytu, nowe pola do zapisu i wartości, które możesz policzyć. Jeśli nie potrafisz wskazać źródła każdego pola, nie masz jeszcze planu.

Trzymaj powierzchnię API małą. Dla wielu funkcji jedno zapytanie odczytu i jedno zapytanie zapisu wystarczy:

• GET /items/{id} zwraca stan potrzebny do renderowania ekranu
• POST /items/{id}/update przyjmuje tylko to, co użytkownik może zmienić i zwraca zaktualizowany stan

Napisz wejścia i wyjścia jako proste obiekty, nie akapity. Uwzględnij pola wymagane vs opcjonalne oraz co się dzieje przy typowych błędach (not found, validation failed).

Przeprowadź szybki przegląd auth zanim dotkniesz bazy. Zdecyduj, kto może czytać, a kto pisać, i opisz regułę jednym zdaniem (np.: „każdy zalogowany użytkownik może czytać, tylko admini mogą pisać”). Pominięcie tego często prowadzi do przeróbek.

Na koniec zdecyduj, co trzeba przechowywać, a co można policzyć. Prosta zasada: przechowuj fakty, obliczaj widoki.

Użyj Claude Code, aby wygenerować zadanie o ograniczonym zakresie

Claude Code działa najlepiej, gdy dasz mu jasny cel i wąskie granice. Zacznij od wklejenia chaotycznego zgłoszenia i wszystkich ograniczeń (termin, użytkownicy objęci, reguły danych). Potem poproś o wynikowy zakres, który zawiera:

1. Jasne, w prostym języku, streszczenie zakresu i krótką listę kryteriów akceptacji.
2. Małą sekwencję commitów (celuj w 3–7), każdy z jasnym rezultatem.
3. Prawdopodobne pliki lub foldery dotknięte na commit i co w nich się zmieni.
4. Szybki plan testów dla każdego commita (jeden happy path i jeden przypadek brzegowy).
5. Wyraźne notatki o tym, co jest poza zakresem.

Po otrzymaniu odpowiedzi przeczytaj ją jak recenzent. Jeśli zobaczysz sformułowania typu „ulepszyć wydajność” lub „uporządkować”, poproś o mierzalne sformułowania.

Mini przykład (jak wygląda „dobrze”)

Zgłoszenie: „Dodaj sposób na wstrzymanie subskrypcji.”

Szkic zakresu może brzmieć: „Użytkownik może wstrzymać subskrypcję na 1–3 miesiące; następna data rozliczenia się aktualizuje; admin widzi status wstrzymania,” a poza zakresem: „Brak zmian w prorytacji”.

Stąd plan commitów staje się praktyczny: jeden commit dla kształtu DB i API, jeden dla kontroli UI, jeden dla walidacji i obsługi błędów, jeden dla testów end-to-end.

Podziel pracę na małe, przeglądalne commity

Duże zmiany ukrywają błędy. Małe commity przyspieszają przeglądy, ułatwiają rollbacky i pomagają zauważyć, kiedy odpływasz od kryteriów akceptacji.

Przydatna zasada: każdy commit powinien odblokować jedno nowe zachowanie i zawierać szybki sposób na udowodnienie, że działa.

Typowa sekwencja wygląda tak:

• Model danych lub migracja (jeśli potrzeba) plus testy
• Zachowanie API i walidacja
• Podłączenie UI z pustymi i błędnymi stanami
• Logowanie lub analityka tylko jeśli wymagane, potem drobne dopracowanie

Trzymaj każdy commit skupiony. Unikaj refaktorów „przy okazji”. Utrzymuj aplikację działającą end-to-end, nawet jeśli UI jest podstawowe. Nie pakuj migracji, zachowania i UI w jeden commit, chyba że masz dobry powód.

Przykładowe przejście: „Export raportów”

Interesariusz mówi: „Dodamy Export raportów?” To kryje wiele wyborów: który raport, jaki format, kto może eksportować i jak dostarczanie działa.

Zadaj tylko pytania, które zmieniają projekt:

• Które typy raportów wchodzą w zakres v1?
• Jaki format jest wymagany dla v1 (CSV, PDF)?
• Kto może eksportować (admini, konkretne role)?
• Czy to bezpośrednie pobranie czy wysłane mailem?
• Jakie ograniczenia (max zakres dat, limit wierszy, timeouty)?

Załóżmy odpowiedzi: „Sales Summary, tylko CSV, rola managera, bezpośrednie pobranie, maksymalnie ostatnie 90 dni.” Teraz kryteria akceptacji v1 są konkretne: managerowie mogą kliknąć Export na stronie Sales Summary; CSV odpowiada kolumnom widocznej tabeli; eksport respektuje aktualne filtry; eksport powyżej 90 dni pokazuje jasny błąd; pobranie kończy się w 30 sekund dla do 50k wierszy.

Minimalny plan UI: jeden przycisk Export obok akcji tabeli, stan ładowania podczas generowania i komunikat błędu informujący, jak naprawić (np. „Wybierz maksymalnie 90 dni”).

Minimalny plan API: jedno endpoint, który przyjmuje filtry i zwraca wygenerowany CSV jako odpowiedź pliku, używając tego samego zapytania co tabela i wymuszając regułę 90 dni po stronie serwera.

Następnie wydaj to w kilku zwartych commitach: najpierw endpoint dla ustalonego happy path, potem podłączenie UI, potem walidacja i komunikaty dla użytkownika, wreszcie testy i dokumentacja.

Typowe błędy w określaniu zakresu (i jak ich unikać)

Ukryte wymagania się wkradają

Prośby typu „dodaj role zespołu” często ukrywają reguły dotyczące zapraszania, edycji i losów istniejących użytkowników. Jeśli łapiesz się na zgadywaniu, zapisz założenie i zamień je w pytanie lub wyraźną regułę.

Polerka UI miesza się z kluczowym zachowaniem

Zespół traci dni, gdy jedno zadanie obejmuje „zrobić to działać” i „upiększyć”. Trzymaj pierwsze zadanie skupione na zachowaniu i danych. Styling, animacje i odstępy zostaw do kolejnego zadania, chyba że są wymagane do użycia funkcji.

Chcesz rozwiązać wszystkie przypadki brzegowe w v1

Przypadki brzegowe są ważne, ale nie wszystkie muszą być rozwiązane od razu. Zajmij się tymi, które mogą złamać zaufanie (podwójne wysłanie, konfliktujące edycje) i odłóż resztę z jasnymi notatkami.

Stany błędów i uprawnienia odkładane „na później”

Jeśli ich nie zapiszesz, przegapisz je. Zawrzyj przynajmniej jedną ścieżkę nieudaną i jedną regułę uprawnień w kryteriach akceptacji.

Kryteria, których nie da się zweryfikować

Unikaj „szybko” lub „intuicyjnie”, chyba że dodasz liczbę lub konkretny test. Zastąp je czymś, co da się udowodnić w przeglądzie.

Szybka lista kontrolna przed rozpoczęciem kodowania

Przybij zadanie tak, żeby współpracownik mógł przeglądać i testować bez czytania w myślach:

• Wynik i non-goals: jedno zdanie rezultatu i 1–3 wyraźne non-goals.
• Kryteria akceptacji: 5–10 testowalnych sprawdzeń w prostym języku.
• Stany UI: minimalne ładowanie, pusty widok, błąd i sukces.
• Notatki API i danych: najmniejszy kształt endpointu i ewentualne zmiany danych, plus kto czyta i kto pisze.
• Plan commitów z testami: 3–7 commitów, każdy z krótkim dowodem.

Przykład: „Dodaj saved searches” staje się „Użytkownicy mogą zapisać filtr i ponownie go zastosować”, z non-goals jak „brak dzielenia” i „bez zmian sortowania”.

Kolejne kroki: utrzymaj zakres podczas budowy

Gdy masz już zadanie o ograniczonym zakresie, chroń je. Przed kodowaniem zrób szybki sanity check z osobami, które prosiły o zmianę:

• Przeczytaj kryteria akceptacji i potwierdź, że odpowiadają rezultatowi.
• Potwierdź uprawnienia, puste stany i zachowanie przy błędach.
• Ponownie potwierdź, co jest poza zakresem.
• Zgódźcie się na najmniejsze zmiany UI i API, które spełnią kryteria.
• Ustalcie, jak zademonstrujecie funkcję i co oznacza „gotowe”.

Potem przechowaj kryteria tam, gdzie się pracuje: w tickecie, w opisie PR i wszędzie, gdzie zespół faktycznie patrzy.

Jeśli budujesz w Koder.ai (koder.ai), dobrze najpierw zablokować plan, a potem generować kod z niego. Planning Mode dobrze pasuje do takiego workflow, a snapshoty i rollback pozwalają bezpiecznie eksperymentować, gdy trzeba spróbować podejścia i szybko go cofnąć.

Gdy w trakcie pracy pojawiają się nowe pomysły, trzymaj zakres stabilny: zapisz nowe pomysły na liście follow-up, zatrzymaj się i przeszacuj, jeśli zmieniają kryteria akceptacji, i trzymaj commity powiązane z jedną rzeczą na raz.