Programowanie oparte na specyfikacji w systemie Jira
Programowanie oparte na specyfikacji polega na przygotowaniu uporządkowanej specyfikacji, zanim agent zacznie tworzyć. Dzięki temu powstaje właściwe rozwiązanie, a nie trafnie brzmiące przypuszczenie. W Jirze specyfikacja mieści się w zgłoszeniu, na którym już pracujesz — o ile zawiera rzeczywiste założenia: rezultaty, zakres, ograniczenia i kryteria akceptacji. Zgłoszenie może zawierać pełną specyfikację jednego zadania lub fragment większej specyfikacji funkcji podzielonej na kilka zgłoszeń.
W tym przewodniku wyjaśniamy, co sprawia, że specyfikacja jest gotowa dla agenta, dlaczego jej właściwym miejscem jest zgłoszenie i jak napisać pierwszą specyfikację. W skrócie — programowanie oparte na specyfikacji w Jirze daje trzy rzeczy:
pojedyncze źródło rzetelnych informacji, na którym opiera się agent i które weryfikuje recenzent;
kryteria akceptacji określające zakończenie prac zarówno dla agenta, jak i dla osoby;
mniej poprawek, ponieważ intencja jest ustalona, zanim agent napisze choćby jedną linię kodu.
Czym jest programowanie oparte na specyfikacji?
Programowanie oparte na specyfikacji to praktyka, w której piszesz uporządkowaną specyfikację określającą, co ma powstać i jak mierzyć sukces, a agent ją realizuje, zamiast zgadywać na podstawie jednozdaniowego prompta.
Specyfikacja staje się źródłem rzetelnych informacji. To ona wyznacza plan, przebieg prac i weryfikację, a w Jirze wszystkie trzy etapy odbywają się w tym samym zgłoszeniu. Sama idea jest starsza niż SI — wyrosła z projektowania interfejsów API i metod formalnych, w których zachowanie definiuje się, zanim przystąpi się do jego zbudowania.
Definicja zmienia się wraz z rozwojem narzędzi, dlatego należy traktować ją jako praktyczne wytyczne, a nie sztywną specyfikację. Kluczowe działanie jest niezmienne: należy zdefiniować zadanie, zanim agent je wykona.
Różnica polega na momencie rozstrzygnięcia niejasności. W modelu vibe coding problem rozwiązywany jest po napisaniu kodu, natomiast w rozwoju opartym na specyfikacji — przed jego napisaniem.
Vibe coding: Użytkownik steruje agentem za pomocą promptów i akceptuje otrzymane wyniki, więc przyjęte ograniczenia, zakres i przypadki brzegowe ujawniają się dopiero po wygenerowaniu kodu.
Rozwój oparty na specyfikacji: Najpierw użytkownik określa zamiar, ograniczenia i kryteria akceptacji, dzięki czemu agent realizuje zadanie zgodnie z określoną definicją, a nie na podstawie przypuszczeń, a podczas przeglądu sprawdzane są dane w odniesieniu do tej samej definicji bezpośrednio w zgłoszeniu.
Jeśli kod musi funkcjonować w rzeczywistej bazie kodu, agent bez ustalonego kontekstu może podejść do rozwiązania zgłoszenia zbyt dosłownie i pominąć istotne ograniczenie. W takim przypadku zaczyna się praca nad poprawkami.
Dwie kwestie, które często nie są rozgraniczane w promptach: specyfikacja określa, co tworzysz, a plan — sposób realizacji. W rozwoju opartym na specyfikacji najpierw ustala się, co należy zrobić, a dopiero potem — jak to zrealizować na tej podstawie. To właśnie krok, który tryb planowania w narzędziach kodowania opartych na sztucznej inteligencji często pomija: tworzy sposób realizacji bezpośrednio z promptu, zwykle bez uzgodnionej specyfikacji.
Tryb planowania może pełnić rolę uproszczonej specyfikacji, jednak tworzy sposób realizacji na podstawie bieżącego promptu, a nie na podstawie uzgodnionej specyfikacji powiązanej z zadaniem.
Dlaczego specyfikacje są istotne podczas programowania opartego na sztucznej inteligencji
Gdy koszty generowania kodu spadają, trudnością przestaje być samo pisanie kodu. Jest nią określenie, co właściwie ma powstać. Oznacza to, że specyfikacja, a nie prompt, stanowi najistotniejszy artefakt, który zapewniasz.
Pojedynczy prompt pozostawia luki, które agent wypełnia założeniami i generuje kod wyglądający poprawnie, ale rozwiązujący niewłaściwy problem. Specyfikacja najpierw eliminuje luki, dzięki czemu agent tworzy pod kątem precyzyjnie określonej definicji, a nie opiera się na przypuszczeniach. W Jirze specyfikację stanowi zgłoszenie, które zespół już planuje, przypisuje i poddaje przeglądowi.
Co powinno znaleźć się w specyfikacji, na podstawie której agent może generować kod?
Specyfikacja gotowa do współpracy z agentem odpowiada na pytania, które przed rozpoczęciem pracy zadałby dobry inżynier. W Jirze znajdują się one w podsumowaniu, opisie, powiązanych wymaganiach i kryteriach akceptacji zgłoszenia. Ważnych jest sześć elementów:
Rezultaty: Co mamy osiągnąć przez zmianę, sformułowane w sposób umożliwiający ich sprawdzenie przez recenzenta.
Zakres: Co do niego należy i, równie istotna kwestia, co jest poza nim.
Ograniczenia: Ograniczenia związane z architekturą, bezpieczeństwem i wydajnością, które mają zostać uwzględnione.
Poprzednie decyzje: Już ustalony kontekst, aby agent nie rozstrzygał ponownie tych kwestii.
Podział zadań: Praca rozłożona na etapy na tyle małe, aby można je było weryfikować.
Kryteria akceptacji: Możliwa do przetestowania definicja gotowości, którą realizuje agent i względem której jest oceniany rezultat. W Jirze znajdują się one w zgłoszeniu, a przegląd kodu oparty na sztucznej inteligencji może zweryfikować zmianę względem nich, zanim trafi ona do osoby.
Jak zgłoszenie staje się specyfikacją w Jirze
Poprawnie przygotowane zgłoszenie może służyć jako specyfikacja, na podstawie której agent generuje kod i względem której go weryfikuje. Specyfikacja może również znajdować się w powiązanym dokumencie — to typowe rozwiązanie w wielu narzędziach SDD. Jira umożliwia jednak utrzymywanie jej tam, gdzie już wykonywana jest praca. Spełnia wymagania specyfikacji, gdy zawiera sześć powyższych elementów. Zgłoszenie zawierające jeden wiersz, np. „napraw błąd logowania”, nie jest specyfikacją.
Utrzymywanie specyfikacji bezpośrednio w zgłoszeniu oznacza jedną istotną zaletę strukturalną: znajduje się ona tam, gdzie odbywa się praca, więc trudniej ją porzucić niż plik markdown w repozytorium, którego już nikt nie otwiera. To nie sprawia, że system utrzymuje się samodzielnie. To oznacza, że specyfikacja i zadania zawsze są powiązane.
Wszystko jest umieszczone w tym samym miejscu: podsumowanie, opis, powiązane wymagania z Confluence i kryteria akceptacji. Zarówno agent, jak i recenzent mogą je tam odczytać.
Z kolei plik repozytorium znajduje się poza obszarem, w którym zgłoszenia są śledzone, recenzowane i zamykane, dlatego staje się nieaktualny, jeśli zmieni się plan.
To samo zgłoszenie staje się miejscem przeglądu po zakończeniu pracy przez agenta. To tutaj zespół uzgadnia wymagania i odpowiada na zadane pytania.
Jira definiuje plany z wbudowanymi jasno określonymi wymaganiami, zadaniami i szacunkami.
Jak Planer Jiry generuje uporządkowaną specyfikację
Poprzednia sekcja dotyczyła punktu odniesienia: samodzielnego przekształcania pojedynczego zgłoszenia w specyfikację. Planer Jiry służy do realizacji złożonych inicjatyw obejmujących wiele zespołów, w których ręczne tworzenie każdej specyfikacji przestaje być skalowalne. Całość rozpoczyna się od inicjatywy podzielonej na ustrukturyzowane zgłoszenia, każde z własną specyfikacją.
Planer Jiry przyspiesza pracę, ale nie stanowi punktu odniesienia. Podstawowa metoda SDD opiera się na dobrze sformułowanym zgłoszeniu wraz z kryteriami akceptacji — i każdy zespół może tak pracować już dziś. Planer Jiry przyspiesza najtrudniejszy etap tego procesu: przejście od złożonego, niejasnego żądania do ustrukturyzowanej specyfikacji.
W przypadku złożonych projektów Planer Jiry korzysta z Teamwork Graph w tym z bazy kodu, historii Jiry i Confluence oraz kontekstu zespołu, aby określić wymagania i wygenerować ustrukturyzowaną specyfikację techniczną w Confluence, na podstawie której deweloper lub agent kodowania może dalej pracować. Jeden plan, wielu odbiorców: czytelny dla człowieka, przydatny dla agenta.
Jak to działa:
Zapewnia przestrzeń do współpracy dla Ciebie i Twojego zespołu, pozwalając na ustalenia przed rozpoczęciem realizacji działań przez agenta.
Pobiera kontekst z całej Twojej pracy, dzięki czemu specyfikacja opiera się na danych znanych już zespołowi i nie musisz zaczynać od pustego promptu.
Tworzy specyfikację czytelną dla użytkownika i łatwą do przetworzenia przez agenta, dzięki czemu ten sam artefakt może służyć zarówno do przeglądu, jak i realizacji.
Utrzymuje specyfikację w Confluence w powiązaniu ze zgłoszeniem, dzięki czemu zamiary i decyzje pozostają udokumentowane.
Planer Jiry przekształca wstępne pomysły w uporządkowane specyfikacje gotowe do użycia przez agenta
Planer Jiry jest w fazie wczesnego dostępu — zapisz się na listę oczekujących
Jak napisać swoją pierwszą specyfikację dostosowaną do agentów w Jirze
Zacznij od jednego zgłoszenia i ręcznie je zmodyfikuj, aby stanowiło specyfikację dostosowaną do agentów. Skorzystaj z sześciu elementów jako listy kontrolnej.
Rozpocznij od zgłoszenia. W opisie uwzględnij rezultaty, granice zakresu i ograniczenia, nie tylko tytuł.
Przekształć zamiar w ustrukturyzowaną specyfikację.Na tym polega zadanie SDD. Przekształć wcześniejszy kontekst w rezultaty, zakres i ograniczenia w zgłoszeniu, aby agent mógł przejąć jego definicję.
Utwórz możliwe do przetestowania kryteria akceptacji. Agent realizuje zadanie na ich podstawie, a recenzent weryfikuje względem nich. Większość kryteriów wymaga zazwyczaj kilku powtórzeń, zanim będzie można je przetestować.
Przypisz do agenta kodowania. Zgłoszenie spełniające wymagania specyfikacji zapewnia agentowi wystarczających informacji, aby mógł zaimplementować i otworzyć powiązany pull request.
Oceń pull requesty względem kryteriów, a następnie dopracuj. Doprecyzuj specyfikację tam, gdzie agent zastosował własne założenia, i zastosuj ten schemat do kolejnego zgłoszenia.
Najczęściej zadawane pytania dotyczące rozwoju opartego na specyfikacji
Czy do rozwoju opartego na specyfikacji potrzebuję Planera Jiry?
Nie. Punkt odniesienia stanowi prawidłowo określone zgłoszenie z kryteriami akceptacji. Każdy zespół może to przygotować już dziś. Planer Jiry przyspiesza pracę nad złożonymi zadaniami, rozpoczynając od planu najwyższego poziomu, czyli inicjatywy. Dzieli ją następnie na ustrukturyzowane zgłoszenia Jiry — specyfikacja jest wypełniona w każdym z nich, dzięki czemu nie trzeba tego robić ręcznie.
Czym różni się specyfikacja od kryteriów akceptacji?
Specyfikacja określa całość zmiany: rezultaty, zakres, ograniczenia i kontekst. Kryteria akceptacji stanowią tylko jeden z elementów — możliwą do przetestowania definicję gotowości, którą realizuje agent i względem której recenzent ocenia rezultat.
Czy naprawdę dobry prompt jest wystarczający?
W przypadku niewielkich, odwracalnych zadań — często tak jest. W przypadku złożonych lub trudnych do cofnięcia działań zastosowanie promptu sprawia, że agent zgaduje, co zostało pominięte. Specyfikacja eliminuje zgadywanie.
Czy specyfikacja powinna znajdować się w pliku repozytorium czy w zgłoszeniu Jiry?
Zgłoszenie utrzymuje specyfikację w środowisku, w którym praca jest śledzona, przeglądana i zamykana. Dzięki temu ryzyko niezgodności jest mniejsze niż w przypadku pliku markdown w repozytorium, którego już nikt nie otwiera.
Czy rozwój oparty na specyfikacji spowalnia pracę zespołów?
Początkowo wymaga większego nakładu pracy, ale pozwala uniknąć poprawek na późniejszych etapach. Przy złożonych zadaniach przynosi to realne korzyści. W przypadku prostych poprawek pomiń specyfikację i przejdź od razu do promptu.
Kiedy warto przygotować specyfikację, a kiedy najlepiej z niej zrezygnować?
Specyfikację warto sporządzić w przypadku złożonych zadań o dużym wpływie, trudnych do odwrócenia lub wszelkich prac związanych z istotnymi ograniczeniami architektury lub bezpieczeństwa. Pomiń ten krok w przypadku drobnych, odwracalnych poprawek, gdy zastosowanie szybkiego promptu działa szybciej.