O autorze

Jakub Stankowski – programista .NET i Angular od 2018 roku. Pracował nad projektami frontendowymi, backendowymi i fullstackowymi, przestrzegając zasad czystego kodu, DRY i stosując CQRS. Ma również doświadczenie jako trener programowania.

Od 2023 roku intensywnie pracuje z Claude AI oraz metodą Spec-Driven Development (SDD) – produkcyjnym workflow do pracy z AI opartym na zasadzie: najpierw specyfikacja, potem implementacja. Na ProgramujZAI.pl dzieli się praktyczną wiedzą o tym, jak programować z AI bez chaosu w kodzie.

Poznaj Jakuba →

Dobra specyfikacja dla AI to dokument, który opisuje cel, dokładny format danych wejściowych i wyjściowych, przypadki brzegowe oraz mierzalne kryteria akceptacji — bez tych czterech elementów AI wypełnia luki własnymi założeniami, które rzadko pokrywają się z Twoją intencją. W tym artykule dostajesz gotowy szablon, który możesz od razu skopiować, wypełnić i wkleić do Claude Code albo innego narzędzia pracującego w podejściu spec driven development.

Spis treści

• Dlaczego szablon zmienia jakość specyfikacji
• Krok 1: Kontekst i cel — po co ta funkcja istnieje
• Krok 2: Dokładny format danych wejściowych i wyjściowych
• Krok 3: Przypadki brzegowe, które AI ma pilnować
• Krok 4: Kryteria akceptacji, które da się przetestować
• Gotowy szablon specyfikacji do skopiowania
• Jak wdrożyć to w praktyce
• FAQ — najczęstsze pytania
• Podsumowanie

Szablon eliminuje losowość, bo wymusza te same decyzje przy każdym zadaniu

Specyfikacja pisana za każdym razem od zera bez struktury łatwo pomija któryś istotny element — raz zabraknie formatu błędów, innym razem kryteriów akceptacji. Szablon działa jak checklista, która nie pozwala przejść dalej, dopóki nie uzupełnisz wszystkich sekcji.

To właśnie różnica między specyfikacją a zwykłym opisem zadania w Jirze: opis zadania mówi „co ma powstać”, specyfikacja mówi „jak dokładnie ma się zachować w każdej sytuacji”. Szablon z tego artykułu wymusza tę drugą perspektywę niezależnie od tego, kto go wypełnia.

Drugi powód, dla którego szablon działa lepiej niż pisanie specyfikacji od zera, to porównywalność między zadaniami. Kiedy każda specyfikacja ma tę samą strukturę, review zajmuje mniej czasu — recenzent wie dokładnie, gdzie szukać kryteriów akceptacji, a gdzie przypadków brzegowych, zamiast za każdym razem odczytywać inny format zapisu.

Krok 1: Kontekst i cel odpowiadają na pytanie, dlaczego ta funkcja w ogóle istnieje

Kontekst nie jest formalnością — to on pozwala AI podejmować trafne decyzje w sytuacjach, których nie opisałeś wprost. Jeśli AI wie, że funkcja waliduje dane przed wysyłką do zewnętrznego API płatności, sam dobierze bardziej rygorystyczne podejście do błędów niż przy walidacji formularza kontaktowego.

W tej sekcji opisz jednym-dwoma zdaniami, po co ta funkcjonalność powstaje, kto z niej korzysta i jakie ma miejsce w większym systemie. Unikaj ogólników typu „poprawia UX” — zamiast tego napisz konkretnie, jaki problem użytkownika rozwiązuje.

Przykład różnicy w praktyce: „dodaj eksport danych do CSV” to zadanie bez kontekstu. „Dodaj eksport danych do CSV dla działu księgowości, który raz w miesiącu pobiera zestawienie transakcji do rozliczenia podatkowego” to kontekst, który podpowiada AI, że format liczb powinien być zgodny z polskimi standardami księgowymi, a nie amerykańskimi.

Krok 2: Format danych wejściowych i wyjściowych musi być jednoznaczny, nie przybliżony

Format danych to najczęstsze źródło rozjazdu między oczekiwaniami a implementacją. Samo „funkcja przyjmuje dane użytkownika” nie mówi nic konkretnego — trzeba wskazać typy pól, ich opcjonalność i strukturę odpowiedzi.

Dobra praktyka to podanie przykładowego obiektu JSON dla wejścia i dla wyjścia, wraz z typami pól i informacją, które są wymagane. Jeśli funkcja zwraca błędy, opisz też ich strukturę — kod błędu, komunikat, ewentualnie pole, którego dotyczy. Taki poziom precyzji eliminuje większość pytań, które AI musiałoby sobie „dopowiedzieć”.

Warto też jawnie wskazać, które pola są opcjonalne, a które wymagane, oraz jakie typy danych są dopuszczalne — czy data to string w formacie ISO, czy timestamp, czy kwota to liczba całkowita w groszach, czy liczba zmiennoprzecinkowa w złotówkach. Te pozornie drobne decyzje są źródłem większości błędów integracyjnych, gdy zabraknie ich w specyfikacji.

Krok 3: Przypadki brzegowe decydują o tym, czy kod przetrwa realne warunki

Happy path to zaledwie połowa specyfikacji — druga połowa to sytuacje, w których coś idzie nie tak: puste pole, nieprawidłowy typ danych, przekroczony limit, równoczesne żądania. Bez tej sekcji AI implementuje tylko scenariusz idealny, a resztę zostawia na przypadek.

Wypisz konkretne sytuacje brzegowe, które mają znaczenie dla danej funkcji, i dla każdej krótko opisz oczekiwane zachowanie. Nie musisz wymieniać wszystkich teoretycznie możliwych przypadków — skup się na tych, które realnie mogą się zdarzyć w Twoim systemie.

Dla funkcji importu plików typowe przypadki brzegowe to: pusty plik, plik przekraczający limit rozmiaru, nieprawidłowe kodowanie znaków, duplikat już zaimportowanego rekordu. Każdy z nich wymaga innej reakcji systemu — jeden powinien zwrócić błąd walidacji, inny ostrzeżenie, a jeszcze inny cichą deduplikację. Bez tej sekcji AI musiałoby zgadywać, którą strategię zastosować.

Krok 4: Kryteria akceptacji muszą dać się bezpośrednio przełożyć na test

Kryterium akceptacji, które da się od razu zamienić na test jednostkowy, to znak, że specyfikacja jest wystarczająco konkretna. Zdanie typu „funkcja powinna działać poprawnie” nie spełnia tego warunku — nie wiadomo, co dokładnie sprawdzić.

Formułuj kryteria w schemacie „gdy [warunek], wtedy [oczekiwany rezultat]” — na przykład „gdy pole email jest puste, funkcja zwraca błąd 400 z komunikatem w polu error.email„. Taki zapis możesz skopiować niemal jeden do jednego jako scenariusz testu akceptacyjnego.

Liczba kryteriów zależy od złożoności zadania, ale w praktyce trzy do sześciu punktów zwykle wystarcza, żeby pokryć zarówno happy path, jak i najważniejsze przypadki brzegowe opisane w poprzedniej sekcji. Jeśli lista rośnie powyżej dziesięciu punktów, to sygnał, że zadanie warto podzielić na mniejsze specyfikacje.

Gotowy szablon specyfikacji do skopiowania

Poniższy szablon możesz wklejać przy każdym nowym zadaniu — wypełniasz nawiasy kwadratowe własną treścią, struktura zostaje bez zmian.

## Specyfikacja: [nazwa funkcjonalności]
 
### Kontekst
[Po co ta funkcja istnieje, kto z niej korzysta, jakie miejsce zajmuje w systemie]
 
### Dane wejściowe
[Struktura obiektu wejściowego z typami pól i informacją, które są wymagane]
 
### Dane wyjściowe
[Struktura odpowiedzi w przypadku sukcesu]
 
### Obsługa błędów
[Struktura odpowiedzi błędu — kod, komunikat, pole którego dotyczy]
 
### Przypadki brzegowe
- [Sytuacja 1]: [oczekiwane zachowanie]
- [Sytuacja 2]: [oczekiwane zachowanie]
- [Sytuacja 3]: [oczekiwane zachowanie]
 
### Kryteria akceptacji
- Gdy [warunek], wtedy [oczekiwany rezultat]
- Gdy [warunek], wtedy [oczekiwany rezultat]
- Gdy [warunek], wtedy [oczekiwany rezultat]
 
### Poza zakresem
[Co celowo NIE ma zostać zaimplementowane w tym zadaniu]

Sekcja „Poza zakresem” jest tak samo ważna jak reszta — jawnie wyklucza funkcjonalności, które AI mogłoby dopisać z własnej inicjatywy, rozszerzając zadanie poza jego pierwotny cel.

Jak wdrożyć to w praktyce

Najprostszy sposób na wdrożenie szablonu to zapisanie go jako plik w repozytorium projektu, obok kodu, i kopiowanie go za każdym razem, gdy zaczynasz nowe zadanie. Kilka zasad, które warto od razu wprowadzić:

• Nie zaczynaj implementacji, dopóki wszystkie sekcje szablonu nie są wypełnione — puste pole to sygnał, że czegoś jeszcze nie przemyślałeś.
• Wklej wypełniony szablon bezpośrednio jako prompt do Claude Code — im mniej parafraz między specyfikacją a promptem, tym mniej miejsca na błąd interpretacji.
• Trzymaj specyfikację blisko kodu, najlepiej w tym samym repozytorium, żeby łatwo było ją zaktualizować przy zmianach.
• Rewiduj sekcję kryteriów akceptacji jako pierwszą — jeśli te są niejasne, cała reszta specyfikacji zwykle też wymaga poprawek.

Przy pierwszych kilku zadaniach wypełnianie szablonu może wydawać się wolniejsze niż zwykłe pisanie promptu z głowy. To normalne — wraz z praktyką czas wypełniania spada, a korzyść w postaci mniejszej liczby rund poprawek pojawia się już przy drugim, trzecim zadaniu. Warto przetrwać ten początkowy opór, zamiast wracać do pisania specyfikacji „na czuja” po pierwszej trudniejszej sesji.

Więcej o typowych błędach, które psują nawet dobrze rozpoczętą specyfikację, znajdziesz w artykule Najczęstsze błędy w Spec Driven Development, a pełny przepływ pracy z konkretnym narzędziem opisałem w Claude Code + Spec Driven Development. Jeśli zależy Ci na tym, żeby sam prompt wysyłany do AI był równie precyzyjny jak specyfikacja, zajrzyj też do Efektywnych promptów w Claude Code.

FAQ — najczęstsze pytania o pisanie specyfikacji dla AI

Jak napisać dobrą specyfikację dla AI?

Dobra specyfikacja opisuje kontekst funkcjonalności, dokładny format danych wejściowych i wyjściowych, przypadki brzegowe oraz mierzalne kryteria akceptacji — im mniej dwuznaczności w każdej z tych sekcji, tym trafniejsza implementacja bez dodatkowych rund poprawek.

Czy jest gotowy szablon spec driven development, który mogę skopiować?

Tak — szablon w tym artykule zawiera sześć sekcji: kontekst, dane wejściowe, dane wyjściowe, obsługę błędów, przypadki brzegowe i kryteria akceptacji, plus sekcję „poza zakresem” wykluczającą funkcjonalności spoza zadania. Możesz go kopiować przy każdym nowym zadaniu bez modyfikacji struktury.

Czym różni się specyfikacja od zwykłego promptu?

Specyfikacja to w praktyce bardzo precyzyjny, ustrukturyzowany prompt — różnica polega na tym, że wymusza podjęcie konkretnych decyzji (format danych, przypadki brzegowe, kryteria akceptacji) przed napisaniem jakiegokolwiek kodu, zamiast pozostawiać je do interpretacji podczas generowania.

Ile czasu zajmuje napisanie specyfikacji według tego szablonu?

Dla typowego, średniej wielkości zadania wypełnienie szablonu zajmuje od dziesięciu do dwudziestu minut — czas ten zwykle zwraca się wielokrotnie, bo eliminuje kolejne rundy poprawek wynikające z błędnej interpretacji niedoprecyzowanych wymagań.

Podsumowanie

Dobra specyfikacja dla AI nie wymaga talentu do pisania — wymaga konsekwentnego wypełniania tych samych czterech elementów: kontekstu, formatu danych, przypadków brzegowych i kryteriów akceptacji. Szablon z tego artykułu zamienia to w rutynę, którą stosujesz przy każdym zadaniu, zamiast wymyślać strukturę specyfikacji od nowa za każdym razem. Praktyczne przykłady wdrożenia tego podejścia znajdziesz na standev.it/ai-workflow-bonus oraz na moim kanale YouTube.