Wytwarzanie oparte na specyfikacji w czasach AI

Zmiana, o której nikt cię nie uprzedził

Przez trzydzieści lat środek ciężkości w wytwarzaniu oprogramowania leżał w pisaniu kodu. Specyfikacja była lekkim wsadem - wystarczająco zarysowanym, żeby ruszyć, doprecyzowywanym w rozmowie w trakcie pracy. Dobry programista wchłaniał niejasności, pytał kolegę z zespołu, podejmował decyzję w środku sprintu i szedł dalej. Specyfikacja była punktem wyjścia; kod był tym, co się dowoziło.

Naturalnym odruchem przy pracy z AI stał się tak zwany vibe coding - luźne, iteracyjne dogadywanie się z modelem metodą kolejnych przybliżeń, w tę i z powrotem, aż coś zadziała. To się nie sprawdza. Taki tryb generuje ogromne ilości długu technicznego, który narasta z każdą iteracją. Najostrzej widać to w rozwoju ugruntowanych już produktów, gdzie nowy, niekontrolowany kod zderza się z istniejącą architekturą. Ale projekty greenfield też nie są bezpieczne - one również stopniowo zbierają dług techniczny i śmieci, które po jakimś czasie wychodzą na wierzch i sprawiają, że produkt przestaje się nadawać do dalszego rozwoju. Rozwiązaniem jest całkowite odwrócenie proporcji: nie back and forth z AI metodą przybliżeń, tylko wyspecyfikowanie wszystkiego pixel perfect, bez cienia wątpliwości - i dopiero wtedy danie AI zielonego światła na kodowanie.

Agentic development całkowicie odwraca dotychczasową zależność. Kiedy agent potrafi wygenerować kod funkcji, testy i dokumentację w godziny, a nie w dni, wąskim gardłem przestaje być implementacja. Przesuwa się ono na początek procesu - w precyzję specyfikacji, którą dajesz agentowi. Kosztowna, wolna i wartościowa część pracy to już nie pisanie kodu; to precyzyjne myślenie i spisanie tego myślenia, zanim powstanie choćby jedna linijka kodu.

To nie jest drobne ulepszenie sposobu pisania historyjek. To inna dyscyplina, a większość zespołów ją lekceważy. Wdrażają agenta, kierują go na niedospecyfikowany ticket i - gdy efekt rozczarowuje - uznają, że narzędzie jest słabe. Narzędzie było w porządku. To wsad nie był.

Nowy budżet czasu

W klasycznym modelu specyfikacja zajmowała godziny, a kodowanie dni albo tygodnie. W modelu AI-native te proporcje się odwracają: specyfikacja zajmuje dni, kodowanie godziny. Na początku jest to niewygodne - inżynierowie przyzwyczajeni do mierzenia postępu wrzuconym kodem teraz spędzają większość tygodnia w dokumentach, w doprecyzowaniu i klarowaniu zakresu pracy z AI. Ale ta zamiana zdecydowanie się opłaca. Pięć minut byle jakiego promptu przy złożonej funkcji daje ogólnikowy wynik, który kosztuje trzydzieści minut poprawek. Jasność, którą zainwestujesz na wejściu, procentuje na każdym kolejnym etapie - za każdym razem.

Od pomysłu do wdrożonego kodu - przebieg pracy

Każda praca idzie tą samą drogą: od potrzeby biznesowej, przez warstwowe doprecyzowanie i projekt testów, do fazy kodowania, która staje się niemal automatyczna, gdy wcześniejsza praca jest zrobiona dobrze. Przebieg ma dwa wyraźne poziomy doprecyzowania - strategiczny i wykonawczy - oraz czyste przejście między nimi.

P1 - Poziom strategiczny (poziom epika): najpierw ustal architekturę i wysokopoziomowe wymagania

Pierwszy poziom doprecyzowania ustala jasność na poziomie całej funkcji i epika, zanim powstanie pojedyncza historyjka. Trzeba tu rozstrzygnąć trzy rzeczy: potrzebę biznesową, obecny stan właściwego fragmentu kodu i architekturę na wysokim poziomie. To praca eksploracyjna, oparta na rozmowie - jaki problem właściwie rozwiązujemy, jak system wygląda dziś, które podejście architektoniczne ma sens i jakie są kompromisy. Tu też decydujemy, co jest in scope, a co out of scope, szykujemy makiety i widoki oraz domykamy wszystkie prerekwizyty. To praca całego zespołu przy wsparciu AI, a nie zadanie jednej osoby. Asystent AI w trybie planowania albo „myślenia" świetnie się tu sprawdza: analiza opcji, omówienie kompromisów i szkicowanie decyzji architektonicznych - wszystko dzieje się na tym etapie.

Na wyjściu z P1, przy pomocy AI, rozbijamy dokument specyfikacji (na poziomie ficzera i epika) na poszczególne historyjki - małe elementy pracy, które będą dowożone w odpowiedniej sekwencji.

P2 - Specyfikacja historyjki: tu buduje się precyzja

Warstwa wykonawcza zamienia doprecyzowaną funkcję w gotową do budowy specyfikację, jedną historyjkę naraz. To poziom historyjek oraz planu implementacji (implementation plan) przygotowanego w trybie planowania (planning mode) razem z AI. Tu mieszka precyzja. Efektem jest kompletna specyfikacja plus plan implementacji na tyle szczegółowy, że agent zbuduje z niego rozwiązanie bez ani jednego pytania doprecyzowującego. Test jest prosty: daj specyfikację komuś - albo czemuś - bez żadnego kontekstu i sprawdź, czy zbuduje to poprawnie. Jeśli nie, lukę trzeba domknąć, zanim historyjka trafi do budowy.

Faza kodowania robi się wręcz nudna

Kiedy specyfikacja jest kompletna, i wszystkie warunki spełnione, budowa jest niemal automatyczna. Agent czyta całą specyfikację, implementuje funkcję, generuje testy i dokumentuje zmiany - bez człowieka w pętli wykonawczej. Automatyczna walidacja rusza od razu. Inżynier przegląda potem efekt, a nie linijki: czy spełnia kryteria akceptacji, czy testy przechodzą, czy są kwestie bezpieczeństwa. To przegląd zorientowany na efekt - i jedna z największych zmian myślenia w całym modelu.

Łańcuch artefaktów

Funkcja budowana w ten sposób zostawia za sobą odpowiedni set dokumentów/artefaktów, zanim powstanie kod. Ten ślad to nie biurokracja - to sama granica, w której działa agent. Każdy dokument jest wsadem do następnego, a razem przenoszą funkcję od potrzeby biznesowej do zweryfikowanego, gotowego do wdrożenia kodu. Pominięcie ogniwa albo robienie ich równolegle psuje wszystko, co dalej.

Artefakt	Perspektywa
Specyfikacja wymagań	CO i DLACZEGO
Opis rozwiązania	JAK (funkcjonalnie)
Historyjki użytkownika	CO (rozbite)
Przypadki testowe E2E	JAK weryfikować
Plan implementacji	JAK zbudować

Specyfikacja wymagań - CO i DLACZEGO

Dokument fundamentalny. Kompletna specyfikacja odpowiada na siedem pytań: po co w ogóle warto budować tę funkcję i komu służy; jakie są kluczowe możliwości i konkretne akcje użytkownika; jak wyglądają ścieżki użytkownika, łącznie ze ścieżkami alternatywnymi i obsługą błędów; jakie są kryteria akceptacji na poziomie funkcji; jakie założenia i zależności; jakie wymagania pozafunkcjonalne; oraz - bezdyskusyjnie - co jest poza zakresem.

Trzy warstwy „JAK"

Warto być precyzyjnym co do rozróżnienia, które zespoły rutynowo zlewają w jedno. Są trzy osobne pytania „jak", każde to osobny artefakt z osobnym odbiorcą:

• Opis rozwiązania - jak funkcja działa funkcjonalnie, z punktu widzenia użytkownika i systemu. Najczęściej pomijana, a najczęściej generująca poprawki sekcja to integracja z istniejącymi funkcjami: nigdy nie zakładaj, że sposób połączenia nowego ze starym jest oczywisty.
• Historyjki użytkownika - CO, rozbite na niezależnie wdrażalne, pionowo pokrojone kawałki, każdy mniej więcej na tydzień pracy. Ich kryteria akceptacji muszą być weryfikowalne maszynowo: agent musi umieć je przeczytać i jednoznacznie stwierdzić, czy implementacja jest poprawna. Opisy wymagające ludzkiej interpretacji nie przechodzą tej poprzeczki.
• Plan implementacji - jak to zbudować technicznie: struktura plików, zależności komponentów, krok po kroku. To jedyny artefakt, który sam szkicuje agent kodujący, czytając wszystko, co wcześniej. Ale doprowadzenie go do gotowości to znacznie więcej niż jedno kliknięcie „zatwierdź" - to niezliczone dialogi z AI, pytania kontrolne, doprecyzowania i kolejne rundy poprawek, aż plan osiągnie stan, w którym nie ma już przestrzeni do interpretacji: wszystko jest zdefiniowane, nakreślone, powiedziane i zdecydowane. Dopiero taki plan wpuszczamy do kodowania.

Przypadki testowe E2E - pisane przed kodem, nie po nim

Zaprojektowanie przypadków testowych E2E względem kryteriów akceptacji przed implementacją robi trzy rzeczy naraz: waliduje specyfikację, wyłapuje luki w wymaganiach w najtańszym możliwym momencie i daje agentowi jasną poprzeczkę dotyczącą jakości do samodzielnego spełnienia. Trwałość zapewniają dwie zasady. Po pierwsze, podwójna czytelność: każdy krok musi być czytelny dla człowieka i automatyzowalny przez maszynę bez zmian - używaj odwołań po roli („kliknij przycisk Zatwierdź"), nigdy po wewnętrznych selektorach. Po drugie, dwukierunkowe pokrycie: każde kryterium akceptacji ma co najmniej jeden test, a każdy test wraca do konkretnego kryterium. Luki w obie strony domknij przed budową.

Lista kontrolna kompletności - twoja najważniejsza bramka

Jeśli z tego przewodnika wdrożysz jedną rzecz, niech to będzie ta. Lista kontrolna kompletności to bramka, którą historyjka musi przejść, zanim wpuścisz ją do fazy kodowania. To różnica między agentem, który buduje właściwą rzecz za pierwszym razem, a agentem, który zawraca trzy razy. Poniżej startowa lista - dostosuj ją, ale nie rezygnuj z samego posiadania takiej listy.

• Opis rozwiązania - jak funkcja działa funkcjonalnie, z punktu widzenia użytkownika i systemu. Najczęściej pomijana, a najczęściej generująca poprawki sekcja to integracja z istniejącymi funkcjami: nigdy nie zakładaj, że sposób połączenia nowego ze starym jest oczywisty.
• Historyjki użytkownika - CO, rozbite na niezależnie wdrażalne, pionowo pokrojone kawałki, każdy mniej więcej na tydzień pracy. Ich kryteria akceptacji muszą być weryfikowalne maszynowo: agent musi umieć je przeczytać i jednoznacznie stwierdzić, czy implementacja jest poprawna. Opisy wymagające ludzkiej interpretacji nie przechodzą tej poprzeczki.
• Plan implementacji - jak to zbudować technicznie: struktura plików, zależności komponentów, krok po kroku. To jedyny artefakt, który sam szkicuje agent kodujący, czytając wszystko, co wcześniej. Ale doprowadzenie go do gotowości to znacznie więcej niż jedno kliknięcie „zatwierdź" - to niezliczone dialogi z AI, pytania kontrolne, doprecyzowania i kolejne rundy poprawek, aż plan osiągnie stan, w którym nie ma już przestrzeni do interpretacji: wszystko jest zdefiniowane, nakreślone, powiedziane i zdecydowane. Dopiero taki plan wpuszczamy do kodowania.

Pozycja listy	Co znaczy „spełnione"
Kryteria akceptacji weryfikowalne maszynowo	Każde kryterium to testowalne stwierdzenie z jasnymi warunkami. Żadna pozycja nie wymaga ludzkiej interpretacji do oceny zaliczone/niezaliczone.
Zakres wykluczeń jest jawny	Możliwości, których funkcja nie ma budować, są nazwane wprost, a nie domyślne.
Stany błędów zdefiniowane dla każdej interakcji	Każde wywołanie zewnętrzne, wejście i warunek brzegowy ma zdefiniowane zachowanie przy błędzie - nie tylko happy path.
Punkty integracji nazwane, a nie opisane ogólnikowo	Istniejące komponenty, których funkcja dotyka, są nazwane wprost, z opisem charakteru każdej interakcji.
Każde kryterium akceptacji ma test	Potwierdzone dwukierunkowe pokrycie; żadnych osieroconych kryteriów, żadnych osieroconych testów.
Agent zbudowałby to bez pytania	Końcowy test gotowości. Jeśli kompetentny agent musiałby dopytać, specyfikacja nie jest skończona.

Jak to się łączy z dojrzałością zespołu

Wytwarzanie oparte na specyfikacji to model pracy na przejście, które czeka każdy zespół: od AI wspiera pojedynczych inżynierów w zadaniach kodowych do zespół definiuje, jak wygląda „poprawnie", i deleguje wykonanie agentom w tych granicach. To przejście ma dwa bezdyskusyjne warunki wstępne, a zespoły, które je ignorują, grzęzną na dobre:

• Automatyczne pokrycie testami powyżej ~80% na modułach, które chcesz oddelegować. Bez testów agent nie potrafi sam zweryfikować swojego wyniku. Każda praktyka delegowania od tego zależy. To z naszego doświadczenia największa pojedyncza bariera, na jaką trafiają zespoły - i trzeba ją zaadresować świadomie, a nie zakładać, że się rozejdzie.
• Kryteria akceptacji weryfikowalne maszynowo. Formalizacja, która sprawia, że delegowanie staje się bezpieczne. Agent musi umieć przeczytać specyfikację i jednoznacznie zdecydować, czy mu się udało.

Dojrzałość nie jest odznaką, którą zespół nosi na stałe. Odzwierciedla to, co zespół zakodował jako warunki brzegowe do tej pory. Zespół działający na wysokim poziomie w stabilnym, dobrze ograniczonym obszarze i tak zacznie zupełnie nową pracę na niższym poziomie - bo warunki brzegowe dla tej nowej pracy jeszcze nie istnieją. To właśnie zakodowanie wiedzy w testy, specyfikacje i reguły przesuwa granicę do przodu. Każdy nowy moduł zaczyna tę drogę od nowa.

Jak i gdzie zacząć

Nie musisz transformować całej organizacji, żeby ruszyć. Najszybsza droga do dowodu to jedna funkcja zrobiona porządnie od początku do końca, przez jeden zespół, który chce, żeby się udało.

Czterotygodniowa sekwencja na start

Tydzień	Na czym się skupić
Tydzień 1 - Punkt odniesienia	Wybierz jedną nadchodzącą funkcję. Zmierz uczciwie obecny czas realizacji, zanim cokolwiek zmienisz - przyda ci się porównanie później. Sprawdź pokrycie testami na zaangażowanych modułach.
Tydzień 2 - Specyfikacja	Przejdź cały łańcuch artefaktów na tej jednej funkcji. Rozstrzygnij architekturę na P1. Zbuduj kompletną specyfikację P2. Napisz przypadki testowe E2E przed kodem. Spodziewaj się, że będzie się wlec - to jest ta inwestycja.
Tydzień 3 - Budowa i przegląd	Daj gotową specyfikację agentowi kodującemu. Ćwicz przegląd zorientowany na efekt. Notuj każde miejsce, gdzie agent się pomylił - każde wskazuje lukę w specyfikacji, a nie błąd narzędzia.
Tydzień 4 - Podsumowanie	Porównaj czas realizacji i liczbę poprawek z punktem odniesienia. Zapisz, które pozycje listy kontrolnej zapobiegłyby każdej poprawce, i wzmocnij listę.

Trzy błędy, które grzebią wdrożenie

• Traktowanie pokrycia testami jako opcji. Zespoły, które je odkładają, wybierają pozostanie na najniższym poziomie możliwości - czy chcą tego, czy nie. Pokrycie jest bramką do wszystkiego.
• Specyfikowanie równolegle zamiast po kolei. Artefakty tworzą łańcuch nie bez powodu. Każdy jest wsadem do następnego; robienie ich naraz psuje jakość wszystkiego, co dalej.
• Obwinianie modelu. Najdroższy błąd. Każda rozmowa „AI zawodzi", która nie zaczyna się od sprawdzenia jakości wsadu, to rozmowa, która wróci w następnym sprincie.

Jak wygląda dobry wynik po kwartale

Zespoły, które utrzymują dyscyplinę, raportują ten sam kształt wyniku: czas realizacji liczony w dniach zamiast w tygodniach, poprawki topniejące wraz z poprawą jakości specyfikacji i granicy warunków brzegowych, oraz wysiłek walidacji przesuwający się z czytania kodu na potwierdzanie efektów. Pierwsze tygodnie są wolniejsze - to inwestycja na wejściu, która pojawia się przed zwrotem na wyjściu. Zespoły, które porzucają model, prawie zawsze robią to w tym pierwszym, niewygodnym kwartale, tuż przed momentem, w którym krzywa się wygina. Dobrze zaimplementowane rozwiązanie po czterech-pięciu miesiącach powinno dawać efekty na poziomie tego, co zespół dowoził przed AI - wszystko, co następuje po tym okresie, to już czysty zysk. Nasze doświadczenia pokazują, że w tej fazie zespół wykonuje nawet do 3,5 raza więcej pracy niż uprzednio.

Nie musisz zaczynać od zera

Cały ten model nie wymaga budowania własnego oprzyrządowania od podstaw. Można sięgnąć po rozwiązania już sprawdzone w boju, które działają dokładnie zgodnie z filozofią nakreśloną powyżej - specyfikacja jako artefakt pierwszej klasy, żyjąca w repozytorium obok kodu, przegląd intencji przed napisaniem choćby jednej linijki.

Jeśli nie wiesz, na którym poziomie pracuje dziś Twój zespół, zacznij od przewodnika o poziomach adopcji AI i wróć tutaj z profilem dojrzałości.