Naucz się określać zakres zadań w Claude Code: jak zamienić niejasne zgłoszenia funkcji w testowalne kryteria akceptacji, minimalny plan UI/API i serię małych commitów.
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:
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.
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”.
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:
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).
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.
Napisz każde kryterium jako pojedynczy test, który ktoś może wykonać:
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:
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.
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.
Większość zmian UI potrzebuje kilku przewidywalnych stanów. Wypisz tylko te, które mają zastosowanie:
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).
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 ekranuPOST /items/{id}/update przyjmuje tylko to, co użytkownik może zmienić i zwraca zaktualizowany stanNapisz 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.
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:
Po otrzymaniu odpowiedzi przeczytaj ją jak recenzent. Jeśli zobaczysz sformułowania typu „ulepszyć wydajność” lub „uporządkować”, poproś o mierzalne sformułowania.
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.
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:
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.
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:
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.
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łę.
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.
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.
Jeśli ich nie zapiszesz, przegapisz je. Zawrzyj przynajmniej jedną ścieżkę nieudaną i jedną regułę uprawnień w kryteriach akceptacji.
Unikaj „szybko” lub „intuicyjnie”, chyba że dodasz liczbę lub konkretny test. Zastąp je czymś, co da się udowodnić w przeglądzie.
Przybij zadanie tak, żeby współpracownik mógł przeglądać i testować bez czytania w myślach:
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”.
Gdy masz już zadanie o ograniczonym zakresie, chroń je. Przed kodowaniem zrób szybki sanity check z osobami, które prosiły o zmianę:
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.
Zacznij od zapisania rezultatu w jednym zdaniu (co użytkownik będzie mógł zrobić, gdy zadanie będzie skończone), a potem dodaj 3–7 kryteriów akceptacji, które tester może zweryfikować.
Jeśli nie potrafisz opisać „poprawnego” zachowania bez dyskusji, zadanie nadal jest niejasne.
Użyj szybkiego formatu:
Następnie dodaj jedno konkretne przykładowe zachowanie. Jeśli nie potrafisz podać przykładu, odtwórz ostatni raz, gdy problem wystąpił: co było na ekranie, co kliknięto i czego oczekiwano.
Najpierw napisz krótką listę Definition of done (kontrole, które muszą przejść), a potem oddzielną listę Nice-to-have.
Domyślna zasada: jeśli nie jest potrzebne do udowodnienia działania funkcji end-to-end, trafia do nice-to-have.
Zadaj pytania, które faktycznie zmieniają zakres:
Te pytania wymuszają decyzje, które zwykle są pomijane.
Traktuj przypadki brzegowe jak elementy zakresu, a nie niespodzianki. Dla v1 uwzględnij te, które naruszą zaufanie:
Wszystko inne można wyraźnie odłożyć jako out-of-scope.
Użyj testowalnych stwierdzeń, które każdy może uruchomić bez zgadywania:
Dołącz przynajmniej jeden przypadek błędny i jedną zasadę uprawnień. Jeśli kryterium nie da się przetestować, przepisz je, aż będzie możliwe do weryfikacji.
Nazwij dokładne ekrany i jedną widoczną zmianę na ekran.
Również wypisz wymagane stany UI:
Utrzymaj też kopię UI (tekst przycisków, błędy) w zakresie, nawet jeśli to tekst tymczasowy.
Trzymaj kontrakt mały: zwykle jedno odczytanie i jedno zapisanie wystarczą dla v1.
Zdefiniuj:
Przechowuj fakty; oblicz widoki tam, gdzie to możliwe.
Poproś o zamknięty rezultat:
Potem poproś o doprecyzowanie wszelkich niejasnych wyrażeń jak „ulepszyć wydajność” na mierzalne cele.
Domyślna sekwencja:
Zasada: jeden commit = jedno nowe widoczne zachowanie + szybki sposób na dowód działania. Unikaj „przy okazji” refaktorów w commitach funkcji.