Specyfikacje funkcji Claude Code z kodu — prosty proces

Dlaczego potrzebujesz specyfikacji, które odzwierciedlają kod

Ludzie mają różne wspomnienia o tym, co robi aplikacja, bo pamiętają różne wersje. Support pamięta ostatni zły ticket. Sprzedaż pamięta ścieżkę z dema. Inżynierowie pamiętają, co funkcja miała robić. Zapytaj trzy osoby, a usłyszysz trzy pewne odpowiedzi — i żadna nie będzie pasować do obecnej wersji.

Z czasem kod staje się jedynym źródłem, które pozostaje aktualne. Dokumenty odpływają, tickety są zamykane, a szybkie poprawki się kumulują. Trasa dostaje nowe reguły walidacji. Przełącznik w UI zmienia domyślną wartość. Handler zaczyna zwracać inne błędy. Nikt nie aktualizuje specyfikacji, bo wydaje się to opcjonalne, a każda zmiana zbyt drobna, by ją zapisywać.

To tworzy przewidywalne problemy. Zespoły wypuszczają zmiany, które psują przypadki brzegowe, o których nie wiedziały. QA testuje happy path i przegapia reguły ukryte w handlerach. Nowi członkowie zespołu kopiują zachowanie z UI nie rozumiejąc prawdziwych ograniczeń. Interesariusze spierają się opiniami zamiast wskazywać na uzgodnione zachowanie.

Dobry rezultat to nie idealny dokument, lecz wspólna jasność. Każdy powinien potrafić odpowiedzieć: "Co się stanie, jeśli zrobię X?" i "Co system gwarantuje?" bez zgadywania. Mniej niespodzianek, krótsze przeglądy i mniej momentów "Czekaj, już to robi" — bo zespół patrzy na tę samą prawdę.

Gdy specyfikacja zgadza się z kodem, można bezpiecznie planować zmiany. Widać, co jest stabilne, co jest przypadkowe i czego brakuje, zanim wdroisz.

Czym jest żywa specyfikacja i lista luk

Żywa specyfikacja to krótki, edytowalny opis tego, co aplikacja faktycznie robi dziś. To nie dokument jednorazowy. Zmienia się zawsze, gdy zmienia się zachowanie, dzięki czemu zespół jej ufa.

Gdy mówimy o specyfikacjach funkcji wygenerowanych z kodu (na przykład z użyciem Claude Code), cel jest prosty: odczytać rzeczywiste zachowanie z tras, handlerów i ekranów, a potem zapisać to prostym językiem.

Przydatna żywa specyfikacja skupia się na tym, co widzi użytkownik i co system obiecuje. Powinna obejmować:

• Zachowanie widoczne dla użytkownika (co się dzieje po kliknięciu, wysłaniu formularza, zalogowaniu)
• Zasady i ograniczenia (pola wymagane, limity, obliczenia)
• Przypadki brzegowe (stany puste, błędy, ponawianie, limity czasowe)
• Uprawnienia (kto może przeglądać, tworzyć, edytować, usuwać)
• Ważne rezultaty (wysyłane e‑maile, tworzone rekordy, zmiany statusów)

Czego nie powinno obejmować: organizacji kodu. Jeśli zaczynasz wymieniać nazwy plików i plany refaktoryzacji, schodzisz w szczegóły implementacyjne. Unikaj:

• Nazw funkcji i klas, drzew komponentów
• Debat architektonicznych i planów przepisania

Lista luk to coś oddzielnego. To krótka lista niezgodności i niejasności, które znajdujesz podczas pisania specyfikacji.

• Bug: kod narusza aktualne zachowanie lub uzgodnioną regułę.
• Prośba o funkcję: chcemy nowe zachowanie.
• Luka: nie da się ustalić, jakie powinno być prawidłowe zachowanie, albo zachowanie jest niespójne między ekranami/rolami.

Przykład: jedna trasa odrzuca pliki >10MB, ale UI mówi 25MB. To luka dopóki zespół nie zdecyduje, która reguła jest prawdziwa i nie zaktualizuje kodu lub specyfikacji.

Wybierz zakres i prosty format specyfikacji

Zacznij od małego fragmentu. Jeśli spróbujesz udokumentować całą aplikację, skończysz z kupą notatek, którym nikt nie zaufa. Wybierz jedną ścieżkę, którą użytkownicy potrafią opisać zdaniem, np. "zaprosić współpracownika", "checkout" lub "reset hasła". Dobry zakres to pojedynczy obszar funkcji, moduł lub podróż użytkownika od punktu wejścia do rezultatu.

Wybierz punkt wejścia według tego, gdzie leży prawda:

• Jeśli potrzebujesz prawdziwych reguł — zacznij od tras i handlerów.
• Jeśli potrzebujesz rzeczywistego doświadczenia — zacznij od punktów wejścia w UI.
• Jeśli funkcja jest splątana — zacznij od najwyższego poziomu strony/kontrolera i pracuj na zewnątrz.

Zanim zaczniesz czytać kod, zbierz kilka wejść, żeby rozbieżności były widoczne szybko: istniejąca dokumentacja API, stare notatki produktowe, tickety supportu i „znane bolączki”. Nie zastępują one kodu, ale pomagają zauważyć brakujące stany jak błędy, przypadki brzegowe i uprawnienia.

Trzymaj format specyfikacji prosty i spójny. Zespoły szybciej się porozumiewają, gdy każda specyfikacja czyta się tak samo.

Szablon specyfikacji (powtarzaj dla każdego przepływu widocznego dla użytkownika)

• Purpose: czego użytkownik próbuje dokonać
• Entry points: gdzie zaczyna się przepływ (URL, menu, przycisk)
• Preconditions: auth, role, wymagane dane
• Main flow: 5–10 kroków w prostym języku
• Data and side effects: tworzone/aktualizowane rekordy, e‑maile, logi
• Errors and edge cases: co się dzieje, gdy coś idzie nie tak
• Open questions: niejasne zachowania do potwierdzenia

Używaj tej struktury wielokrotnie — twoje specyfikacje będą czytelne, porównywalne i łatwe do aktualizacji.

Wydobywanie zachowania z tras i handlerów

Zacznij od punktów wejścia na serwerze. Trasy i handlery pokazują „co aplikacja robi” w konkretnych terminach: kto może je wywołać, co muszą przesłać, co dostają w odpowiedzi i co zmienia się w systemie.

Wypisz trasy w zakresie i przypisz każdej zamiar użytkownika. Nie pisz „POST /api/orders.” Napisz „Złóż zamówienie” lub „Zapisz szkic.” Jeśli nie potrafisz nazwać zamiaru prostymi słowami, to już luka w specyfikacji.

Czytając każdy handler, zapisuj inputy i reguły walidacji jako wymagania widoczne dla użytkownika. Dołącz pola wymagane, dopuszczalne formaty i reguły, które powodują rzeczywiste błędy. Na przykład: „E‑mail musi być poprawny”, „Ilość musi być co najmniej 1”, „Data rozpoczęcia nie może być w przeszłości.”

Zapisuj też sprawdzenia autoryzacji i ról w prosty sposób. Zamiast "middleware: requireAdmin" udokumentuj: "Tylko admini mogą anulować dowolne zamówienie. Zwykli użytkownicy mogą anulować tylko swoje zamówienie w ciągu 10 minut." Jeśli kod sprawdza własność, flagi funkcji lub granice tenantów, dodaj to również.

Następnie zanotuj wyjścia i wyniki. Co zwraca sukces (stworzony ID, zaktualizowany obiekt)? Jak wyglądają typowe niepowodzenia (401 niezalogowany, 403 brak uprawnień, 404 nie znaleziono, 409 konflikt, 422 błąd walidacji)?

Na koniec zapisz efekty uboczne, bo są częścią zachowania: tworzone/aktualizowane rekordy, wysyłane e‑maile/powiadomienia, publikowane zdarzenia, kolejkowane zadania w tle i wszystko, co uruchamia inne przepływy. Te szczegóły zapobiegają niespodziankom, gdy później zespół będzie polegać na specyfikacji.

Wydobywanie zachowania z komponentów i przepływów UI

Trasy mówią, co aplikacja może zrobić. Komponenty mówią, jak użytkownik to doświadcza. Traktuj UI jako część kontraktu: co się wyświetla, co jest zablokowane i co się dzieje, gdy coś pójdzie nie tak.

Znajdź ekrany wejściowe dla funkcji. Szukaj komponentu strony, wrappera layoutu i kilku „komponentów decyzyjnych”, które kontrolują pobieranie danych, uprawnienia i nawigację. To zwykle tam leży prawdziwe zachowanie.

Czytając komponenty, zapisuj reguły, które użytkownik odczuwa: kiedy akcje są wyłączone, wymagane kroki, pola warunkowe, stany ładowania i jak błędy się pojawiają (błędy pod polem vs toast, automatyczne ponawianie, przycisk „spróbuj ponownie”). Zwróć uwagę na stan i cache: wyświetlanie przestarzałych danych najpierw, optymistyczne aktualizacje czy znaczniki „ostatnio zapisano”.

Szukaj też ukrytych przepływów, które cicho zmieniają to, co użytkownicy widzą. Przeszukaj kod pod kątem feature flagów, eksperymentów i bramek tylko dla adminów. Zauważ też ciche przekierowania, np. wysyłanie niezalogowanych do logowania lub użytkowników bez dostępu na ekran uaktualnienia.

Konkret: na ekranie „Zmień e‑mail” udokumentuj, że przycisk Zapisz jest wyłączony, dopóki e‑mail nie będzie poprawny, podczas żądania pokazuje się spinner, sukces wyświetla baner potwierdzający, a błędy walidacji z backendu renderują się pod polem. Jeśli w kodzie pojawia się flaga newEmailFlow, zanotuj obie warianty i różnice.

Pisz każdy przepływ UI jako krótkie kroki (co użytkownik robi, co UI robi w odpowiedzi) i trzymaj warunki oraz błędy przy kroku, którego dotyczą. To ułatwia czytelność i wykrywanie luk.

Przepisz obserwacje na czytelne specyfikacje funkcji

Surowe notatki z tras i komponentów są przydatne, ale trudne do dyskusji. Przepisz obserwacje w specyfikację, którą PM, designer, QA i inżynier mogą przeczytać i zgodzić się co do niej.

Praktyczny wzorzec to jedna historia użytkownika na trasę lub ekran. Trzymaj ją małą i konkretną. Na przykład: „Jako zalogowany użytkownik mogę zresetować hasło, aby odzyskać dostęp.” Jeśli kod pokazuje różne zachowanie w zależności od roli (admin vs user), rozdziel to na osobne historie zamiast ukrywać w przypisach.

Napisz kryteria akceptacji, które odzwierciedlają rzeczywiste ścieżki kodu, nie idealny produkt. Jeśli handler zwraca 401, gdy brakuje tokena, to jest kryterium. Jeśli UI wyłącza wysyłanie, dopóki pole nie będzie poprawne, to też jest kryterium.

Dołącz reguły dotyczące danych prostym językiem, zwłaszcza te, które powodują zaskoczenia: limity, kolejność, unikalność, pola wymagane. „Nazwy użytkowników muszą być unikalne (sprawdzane przy zapisie)” jest jaśniejsze niż „unikalny indeks”.

Przypadki brzegowe często decydują o tym, czy dokument jest ładny, czy użyteczny. Wypisz stany puste, wartości null, ponawiania, limity czasowe i to, co widzi użytkownik przy błędzie API.

Gdy natrafisz na nieznane, zaznacz to zamiast zgadywać:

• Unknown: jaki komunikat ma się pokazać, gdy e‑mail nie zostanie znaleziony?
• Unknown: czy pozwalamy na 0 pozycji, czy wymuszamy co najmniej 1?
• Unknown: czy ten błąd ma być widoczny użytkownikowi, czy tylko zapisywany w logu?

Takie markery zamienią się w szybkie pytania dla zespołu, zamiast w ciche założenia.

Stwórz listę luk, nie backlog

Lista luk to nie kolejny Jira. To krótki, oparty na dowodach zapis miejsc, gdzie kod i zamierzona funkcja się nie zgadzają lub gdzie nikt nie potrafi jasno wyjaśnić, co jest „poprawne”. Dobrze zrobiona, staje się narzędziem do porozumienia, nie walki o priorytety.

Bądź rygorystyczny przy definiowaniu luki:

• Niejasne zachowanie: aplikacja robi coś, ale reguła nie jest nigdzie zapisana.
• Niespójność: dwa miejsca zachowują się inaczej w tym samym przypadku.
• Brakująca reguła: istnieje przypadek brzegowy, ale w kodzie i dokumentach nie ma decyzji.

Gdy wpisujesz lukę, dołącz trzy elementy, by pozostała uziemiona:

• Typ: bug (kod wygląda na błędny) lub brakująca decyzja (intencja niejasna)
• Wpływ: zamieszanie użytkownika, ryzyko bezpieczeństwa, utrata danych lub drobna sprawa
• Dowód: gdzie to widziano i co zaobserwowano (trasa/handler/komponent)

Dowód zapobiega przemianie listy w opinie. Przykład: „POST /checkout/apply-coupon akceptuje przeterminowane kupony, ale CouponBanner.tsx blokuje je w UI. Wpływ: przychody i zamieszanie użytkowników. Typ: bug lub brakująca decyzja (potwierdź docelową regułę).”

Trzymaj listę krótką. Ustal twardy limit, np. 10 pozycji na pierwszy przegląd. Jeśli znajdziesz 40 problemów, pogrupuj je w wzory (niespójności walidacji, sprawdzenia uprawnień, stany puste) i zachowaj tylko najlepsze przykłady.

Unikaj dat i harmonogramów w liście luk. Jeśli potrzebujesz właściciela, zanotuj, kto powinien podjąć decyzję (produkt) lub kto może zweryfikować zachowanie (inżynieria), a planowanie przenieś do backlogu.

Przykład: dokumentowanie realnej funkcji z kodu

Wybierz mały, często używany zakres: checkout z kodami promocyjnymi i opcjami wysyłki. Celem nie jest przepisywanie całego produktu, lecz uchwycenie tego, co aplikacja robi dziś.

Zacznij od backendowych tras. To tam często pojawiają się reguły. Możesz znaleźć trasy takie jak POST /checkout/apply-promo, GET /checkout/shipping-options, POST /checkout/confirm.

Z tych handlerów zapisz zachowanie prostym językiem:

• Kody promocyjne walidowane są po stronie serwera (wygaśnięcie, limit użyć, kwalifikowalność klienta).
• Po zastosowaniu promocyjnego kodu sumy są przeliczane, ale dopiero po ponownym sprawdzeniu dostępności zapasów.
• Opcje wysyłki zależą od miejsca docelowego, wagi i od tego, czy któryś przedmiot jest oznaczony jako "restricted".
• Potwierdzenie nie powiedzie się, jeśli dostępność pozycji zmieniła się od momentu załadowania koszyka.
• Podatek jest obliczany po wyborze wysyłki (nie podczas stosowania promocji).

Następnie sprawdź komponenty UI. PromoCodeInput może pokazywać, że sumy odświeżają się dopiero po udanej odpowiedzi, a błędy renderują pod polem. ShippingOptions może automatycznie wybrać najtańszą opcję przy pierwszym załadowaniu i wywołać pełne odświeżenie rozbicia ceny, gdy użytkownik ją zmieni.

Masz teraz czytelną specyfikację i małą listę luk. Na przykład: komunikaty o błędach różnią się między trasą promocyjną a UI ("Invalid code" vs "Not eligible") i nikt nie potrafi wskazać jasnej reguły zaokrąglania podatku (po pozycji vs suma zamówienia).

W planowaniu zespół najpierw zgadza się co do rzeczywistości, a potem decyduje, co zmienić. Zamiast debatować opinie, przegląda się udokumentowane zachowania, wybiera jedną niespójność do naprawy i zostawia resztę jako "aktualne zachowanie" dopóki nie będzie warto go zmieniać.

Zweryfikuj specyfikację z zespołem i utrzymuj ją aktualną

Spec pomaga tylko wtedy, gdy zespół zgadza się, że odzwierciedla rzeczywistość. Zrób krótkie czytanie z jednym inżynierem i jedną osobą z produktu. Krótkie i konkretne: 20–30 minut skupienia na tym, co użytkownik może zrobić i co system odpowiada.

Podczas przeglądu zamieniaj stwierdzenia na pytania tak/nie. "Gdy użytkownik trafi na tę trasę, czy zawsze zwracamy 403 bez sesji?" "Czy ten pusty stan jest zamierzony?" To oddziela zamierzone zachowanie od przypadkowego, które wślizgnęło się z upływem czasu.

Uzgodnij słownictwo zanim zaczniesz edytować. Używaj słów widocznych w UI (napisy przycisków, tytuły stron, komunikaty). Dodawaj nazwy wewnętrzne tylko wtedy, gdy pomagają inżynierom znaleźć kod (nazwy tras, komponentów). To zapobiega rozjazdom typu produkt mówi "Workspace", a spec mówi "Org".

Aby utrzymać aktualność, określ właścicielstwo i rytm:

• Właściciel specu: jedna osoba, która scala zmiany (często właściciel funkcji lub tech lead)
• Wyzwalacz aktualizacji: przy merge’owaniu PR zmieniającego zachowanie lub przy każdym releasie
• Szybka kontrola: dodaj pole „spec updated?” do szablonu PR
• Miejsce przechowywania: trzymaj blisko kodu, by zmieniało się razem z nim

Jeśli używasz narzędzia typu Koder.ai, snapshoty i rollback pomagają porównać "przed" i "po" podczas aktualizacji specyfikacji, szczególnie po dużym refaktorze.

Najczęstsze błędy i pułapki

Najszybszy sposób, by stracić zaufanie do specyfikacji, to opisywać produkt, jaki chcesz, a nie ten, który masz. Twarda zasada: każde stwierdzenie powinno być poparte czymś, na co możesz wskazać w kodzie lub na ekranie.

Inna pułapka to przepisywanie kształtu kodu w dokumencie. Spec, który wygląda jak "Controller -> Service -> Repository" nie jest specyfikacją, to mapa folderów. Pisz w języku użytkownika: co wyzwala akcję, co widzi użytkownik, co jest zapisywane i jak wyglądają błędy.

Uprawnienia i role często ignorowane są na końcu — potem wszystko się sypie. Dodaj reguły dostępu wcześnie, nawet jeśli są nieporządne. Wypisz, które role mogą przeglądać, tworzyć, edytować, usuwać, eksportować lub zatwierdzać oraz gdzie reguła jest wymuszana (tylko UI, tylko API, albo oba).

Nie pomijaj ścieżek nie‑happy. Rzeczywiste zachowanie ukrywa się w ponowieniach, niepełnych błędach i regułach czasowych jak wygaśnięcia, cooldowny, zadania harmonogramowe czy limity typu "raz na dzień". Traktuj je jako pierwszorzędne zachowania.

Szybki sposób na odkrycie luk to sprawdzenie:

• Błędów walidacji i dokładnych komunikatów widocznych dla użytkownika
• Obsługi zduplikowanych zgłoszeń (idempotencja)
• Pracy w tle (kolejki, cron) i co się dzieje, gdy zawiedzie
• Problemów z konkurencją (dwóch użytkowników zmieniających ten sam rekord)
• Zachowań związanych z czasem (timeouty, wygaśnięcia, limity)

Wreszcie, popychaj listę luk do przodu. Każda luka powinna dostać etykietę: "unknown/needs decision", "bug/fix" lub "missing feature/plan". Jeśli coś nie zostanie oznaczone, lista stoi, a spec przestaje być żywy.

Krótka lista kontrolna przed udostępnieniem specyfikacji

Zrób szybki przegląd pod kątem jasności, pokrycia i możliwości działania. Ktoś, kto nie pisał specu, powinien zrozumieć, co funkcja robi dziś i co jest nadal niejasne.

Jasność i wspólne zrozumienie

Przeczytaj spec jak nowy członek zespołu w dniu pierwszym. Jeśli potrafi podsumować funkcję w minutę, jesteś blisko. Jeśli ciągle pyta "gdzie to się zaczyna?" lub "jaka jest wolna ścieżka?", popraw otwarcie.

Sprawdź:

• Test na jedną stronę: otwarcie mówi cel użytkownika, gdzie przepływ się zaczyna i gdzie się kończy.
• Role i dostęp: kluczowe role i co każda może lub nie może robić.
• Wyniki: jak wygląda sukces i co widzi użytkownik przy porażce (komunikaty, przekierowania, ponawianie).
• Krawędzie i limity: limity rozmiaru, limity szybkości, timeouty, reguły walidacji i co się dzieje przy brakujących danych.
• Język: używaj najpierw terminologii z UI; jeśli trzeba, raz zdefiniuj żargon.

Luki, które pomagają, a nie szkodzą

Każda luka powinna być konkretna i testowalna. Zamiast "Obsługa błędów niejasna", napisz: "Jeśli provider płatności zwróci 402, UI pokazuje ogólny toast; potwierdź docelowy komunikat i zachowanie ponawiania." Dodaj jedną następną akcję (zapytać produkt, dodać test, sprawdzić logi) i zanotuj, kto powinien odpowiedzieć.

Następne kroki na ten tydzień

Wybierz jedną funkcję i ogranicz ją czasowo do 60 minut. Wybierz coś małego, ale realnego (logowanie, checkout, wyszukiwanie, ekran admina). Napisz jedno zdanie zakresu: co jest w zakresie, a co wykluczone.

Przeprowadź workflow end‑to‑end raz: przejrzyj kluczowe trasy/handlery, prześledź główny przepływ UI i zapisz obserwowalne zachowania (inputy, outputy, walidacja, stany błędów). Jeśli utkniesz — zapisz pytanie jako lukę i idź dalej.

Gdy skończysz, udostępnij spec zespołowi do komentarzy i ustal jedną zasadę: każda zmiana zachowania powinna zaktualizować spec w tym samym oknie dostawy, nawet jeśli to tylko pięć linijek.

Trzymaj listę luk oddzielnie od backlogu. Grupuj je w "nieznane zachowanie", "niespójne zachowanie" i "brak testów", potem przeglądaj szybko co tydzień, by zdecydować, co jest ważne teraz.

Jeśli tworzenie i iteracja idą zbyt wolno, narzędzie czatowe jak Koder.ai może pomóc szybko uzyskać wersję początkową. Opisz funkcję, wklej kluczowe fragmenty lub nazwy tras, dopracuj w rozmowie i eksportuj źródła gdy potrzebujesz. Chodzi o szybkość i wspólną jasność, nie o większy proces.