Rozwój oparty na specyfikacjach: pozytywne aspekty – i czego nauczyliśmy się po trzech miesiącach

Po trzech miesiącach mieliśmy jaśniejszy obraz tego, kiedy dodana struktura była pomocna, a kiedy przeszkadzała.

Jeden z naszych inżynierów przygotowywał migrację danych i zdecydował się skorzystać z metody programowania opartego na specyfikacjach (SDD), aby zaplanować pracę. SDD miało pomóc w wczesnym wykrywaniu luk, ułatwić przegląd podejścia i zapewnić agentowi jasne wytyczne. Powstały plan był szczegółowy i na papierze wyglądał całkiem rozsądnie. Praca została w nim zorganizowana w następujący sposób:

Problem → Badanie → Specyfikacja → Przegląd → Wdrożenie → Weryfikacja

W miarę postępu prac wdrożeniowych inżynier zdał sobie sprawę, że dwa zadania mogą działać równolegle i tworzyć zduplikowane pola niestandardowe. To podejście sprawiało również, że kod stawał się coraz bardziej skomplikowany i trudny do zrozumienia. Na szczęście problem został wykryty, wstrzymano wdrażanie, sporządzono jednostronicowy dokument projektowy i oznaczono kilku współpracowników, aby uzyskać od nich informacje zwrotne. Wspólnie przeanalizowali projekt i znaleźli bezpieczniejsze podejście.

Oryginalna specyfikacja spełniła nasze oczekiwania: utrzymała projekt na pierwotnym kursie. Problem polegał na tym, że kierunek był niewłaściwy. Dzięki szczegółowej specyfikacji można było łatwo kontynuować projekt, nawet jeśli wyjściowy pomysł był chwiejny. Agent mógł szybciej rozwinąć ten pomysł, zanim ktokolwiek zdążył się zatrzymać i go zakwestionować.

Ten projekt pokazał jedno ryzyko związane z dodatkową strukturą: jeden agent mógł przenieść to samo błędne założenie ze specyfikacji do kodu i testów. Specyfikacja, kod i testy były ze sobą zgodne, ale to nie oznaczało, że podstawowe założenie było słuszne. W przypadku bardziej ryzykownych decyzji ktoś inny nadal musiał wrócić do pierwotnego celu i poszukać sposobów, w jakie implementacja mogłaby go naruszyć.

Mimo to agenci podejmowali się zadań, które trwały dłużej niż jedną sesję, a samo polecenie często nie wystarczało, aby zachować informacje o celu projektu lub jego uzasadnieniu. Doprowadziło to do stworzenia /spec-driven, czyli środowiska testowego dla przepływów pracy, w którym centralne miejsce zajmuje specyfikacja. Specyfikacja sprawiała, że kierunek projektu był dostępny podczas kolejnej sesji. Skrypty dostarczały kontekst i przeprowadzały weryfikacje. Gdy podczas uruchomienia wykryto brakującą regułę, weryfikację lub element kontekstu, mogliśmy dodać je do przepływu pracy, aby późniejsi agenci nie musieli ponownie odkrywać tej samej luki.

Nadal istnieje spora rozbieżność zdań co do tego, czy dodatkowa struktura SDD jest tego warta. Microsoft i AWS promują SDD, podczas gdy Thoughtworks opisuje tę metodologię jako nową i kontrowersyjną, a praktycy zgłaszają mieszane doświadczenia. Krytycy ostrzegają, że SDD może generować więcej kodu Markdown, niż inżynierowie są w stanie utrzymać, zamieniać szczegółową specyfikację w kod napisany prozą lub pozostawiać po sobie kolejny opis systemu, który odbiega od kodu.[1][2][3]

Po trzech miesiącach rzeczywistego użytkowania dowiedzieliśmy się, że ważne pytanie nie brzmiało, czy korzystać z SDD. Chodziło o to, czego brakowało agentowi w tym projekcie. Czasami odpowiedzią była specyfikacja. Czasami był to lepszy przykład, automatyczna weryfikacja lub inżynier, który znał się na danej dziedzinie.

Dlaczego stworzyliśmy /spec-driven

Niektórzy inżynierowie w Asanie wypróbowali już GitHub Spec Kit i OpenSpec, ale żadne z tych narzędzi nie stało się częścią ich standardowego przepływu pracy. Chcieliśmy mieć wersję, którą moglibyśmy dostosowywać w miarę zdobywania wiedzy i połączyć ją z procesem tworzenia oprogramowania w Asanie.

Wbudowany tryb planowania był już w stanie przeanalizować bazę kodu i stworzyć użyteczny plan wdrożenia przed wprowadzeniem zmian. SDD nadało temu planowi bardziej uporządkowaną strukturę: sprawiło, że problem, kluczowe decyzje i kryteria akceptacji były widoczne na etapie wdrażania i weryfikacji.

Przed wdrożeniem /spec-driven przedstawił swoje zrozumienie problemu i poruszył kwestie, które mogłyby zmienić plan. Dawało to inżynierowi szansę na skorygowanie kierunku działań, zanim konieczne stało się przepisanie kodu.

Zapisaliśmy ten stan w repozytorium, aby podczas późniejszych sesji nie trzeba było zgadywać, co się wydarzyło. Chcieliśmy, aby reguły przepływu pracy były deterministyczne, dlatego skrypty zajmowały się prowadzeniem dokumentacji i przeprowadzaniem kontroli. Model zajmował się elementami, które wymagały oceny: zadawaniem pytań, rozważaniem kompromisów i wyjaśnianiem decyzji.

Przepływ pracy obejmował kilka poleceń. Inżynierowie używali polecenia /spec-driven spec, aby przeanalizować otwarte pytania i opracować specyfikację oraz plan wdrożenia. Po zapoznaniu się z planem używali polecenia /spec-driven ship, aby go wdrożyć, zweryfikować wynik i przygotować pracę do sprawdzenia. Automat skończony śledził projekt w miarę wykonywania tych poleceń, dzięki czemu podczas późniejszych sesji wiadomo było, co się wydarzyło i co będzie dalej.

Od samego początku chcieliśmy, aby polecenie /spec-driven było czymś więcej niż tylko sposobem na tworzenie i realizację specyfikacji. Chcieliśmy również, aby zarządzało przepływami pracy wykorzystującymi agentów. Porządkuje zadania według zależności i przechowuje nakładające się zmiany w plikach w oddzielnych rundach wykonywania. Wysyła niezależne zadania do wielu agentów równolegle, a następnie na podstawie wyników decyduje, co może być wykonane w kolejnym kroku.

To jak nawigacja w pracy: w każdej chwili wiadomo, jaki jest następny krok i gdzie należy podjąć faktyczne decyzje, więc trudno o utknięcie w martwym punkcie.”

Inżynierowie Asany korzystali z polecenia /spec-driven zarówno w podejściu „spec-first”, jak i „spec-anchored”. W przypadku podejścia „spec-first” wykorzystywali specyfikację, aby wybrać kierunek, a następnie przestawali ją aktualizować. W przypadku podejścia opartego na specyfikacji aktualizowali ją na bieżąco w miarę zmian w pracy. Inżynierowie tworzyli również niezależne specyfikacje dla części większego przedsięwzięcia, dzięki czemu jedna osoba mogła korzystać z przepływu pracy bez konieczności wdrażania go przez cały zespół.

Kiedy /spec-driven jest warte dodatkowej pracy

Dodatkowa struktura najbardziej się opłacała, gdy ważny kontekst musiał być zachowany podczas kolejnych sesji, przekazywania zadań lub w wielu powiązanych ze sobą zadaniach. Inżynierowie mogli sprawdzić, jak zmienił się plan, a kierunek projektu pozostawał dostępny, gdy praca została przeniesiona do innej sesji agenta lub do innej osoby. W przypadku dwóch przedsięwzięć produktowych specyfikacje były aktualizowane przez około dwa do trzech miesięcy: w ramach jednego z nich tworzono ważną nową funkcję, a w ramach drugiego przenoszono daty podzadań do zadań nadrzędnych.

Właśnie ukończyłem dość duży projekt oparty na specyfikacjach i myślę, że naprawdę mi to pomogło! Pracowałem nad planem przez około dwa dni, a następnie wykonałem wszystkie prace inżynieryjne i scaliłem je w ciągu trzech dni.”

Specyfikacje ułatwiały przekazywanie zadań. Osoba przejmująca wstrzymany projekt mogła zobaczyć, co zespół próbował zrobić, dlaczego projekt przybrał taką formę i co pozostało do wykonania. Nie musieli odtwarzać projektu na podstawie zatwierdzeń i konwersacji.

Inżynierowie korzystali również z opcji /spec-driven do koordynowania dużych partii zadań wykonywanych przez agenta. W Konsoli administratora Asany, w której zespoły IT w firmach klientów zarządzają ustawieniami dotyczącymi bezpieczeństwa, dostępu, integracji i udostępniania w całej organizacji, inżynierowie wykorzystali ją do przeniesienia 66 ustawień do wspólnych struktur. Przeniesienie tych ustawień wymagało około 150 migracji w ramach kilku struktur Konsoli administratora. Każda migracja stała się zgłoszeniem w Asanie dla agenta chmurowego, a inżynierowie realizowali je w równoległych partiach, aktualizując pozostałe zgłoszenia na podstawie wcześniejszych wyników.

Zespół odpowiedzialny za to zadanie poinformował, że 91% migracji nie wymagało żadnych poprawek po weryfikacji oraz że cały proces został ukończony ponad miesiąc wcześniej niż pierwotnie planowano.

Inna duża migracja wymagała jedynie krótkiego monitu. Różnica polegała na tym, w jakim stopniu baza kodu była już jasna. Zawierała przykłady, którymi agenci mogli się kierować, oraz mechanizmy weryfikacji wyników. Agenci Konsoli administratora nie byli w stanie zidentyfikować wszystkich wymagań na podstawie kodu, dlatego praca wymagała bardziej uporządkowanej struktury.

Podejście /spec-driven pomogło również w szybkim tworzeniu prototypów. Inżynierowie mogli szybko udzielić odpowiedzi na wystarczającą liczbę otwartych pytań dotyczących produktu, aby stworzyć działające, kompleksowe rozwiązanie. Menedżerowie produktu i projektanci mogli wypróbować prototyp, zanim inżynierowie zainwestowali w dopracowanie go pod kątem środowiska produkcyjnego. Jeśli inżynierowie decydowali się zachować kod, zazwyczaj wymagał on znacznego uporządkowania, zanim można go było scalić. Do tego czasu prototyp już pokazał, czy warto było realizować dany pomysł.

Co pokazały pierwsze dane

Zachęcaliśmy wszystkich do jednorazowego wypróbowania podejścia /spec-driven, ale nie wymagaliśmy dalszego korzystania z niego. Około połowa inżynierów wypróbowała tę funkcję. W ostatnim miesiącu z funkcji tej korzystało co tydzień od 30 do 50 inżynierów. Wśród wbudowanych i opracowanych przez Asanę umiejętności agenta, z których inżynierowie korzystali bezpośrednio, /spec-driven zajęło trzecie miejsce. Ciągłe korzystanie z funkcji było obiecujące, ale nie wskazywało, w jaki sposób /spec-driven wpływa na realizację zadań.

Powszechnie wiadomo, że tempo pracy inżynierów jest trudne do zmierzenia. Pull requesty i dodatki do kodu implementacyjnego nie są idealnymi wskaźnikami produktywności, ale uważamy, że często są użytecznymi miernikami kierunkowymi. Aby porównać szybkość pracy, przeanalizowaliśmy dane dotyczące siedmiu inżynierów i 524 scalonych pull requestów w ciągu czterech miesięcy. Porównaliśmy pracę przed i po pierwszym wyraźnym użyciu przez każdego inżyniera polecenia /spec-driven i wykluczyliśmy specyfikacje, plany i inne artefakty związane z przepływem pracy. W przypadku porównania dotyczącego cofania zmian sklasyfikowaliśmy pull requesta jako /spec-driven, gdy zmieniał on pliki projektu w przepływie pracy.

Liczba pull requestów tygodniowo wzrosła o 38%, a liczba dodanych wierszy kodu implementacyjnego wzrosła 2,66 raza. Jeden krótki okres o wyjątkowo dużej liczbie zadań wpłynął na wynik dotyczący dodanego kodu. Nawet bez niego liczba dodanych linii kodu była nadal o 66% wyższa. Wskaźnik wyraźnego cofnięcia był również nieco niższy: 1,2% w przypadku pracy opartej na /spec w porównaniu z 1,66% w przypadku innych pull requestów.

Większa ilość kodu niekoniecznie jest dobrym wynikiem. Agent może utworzyć obszerną implementację, podczas gdy wystarczyłaby mniejsza, więc wzrost liczby dodanych wierszy kodu mógł odzwierciedlać niepotrzebnie rozbudowane rozwiązania, a nie większą ilość ukończonej pracy. Standardowy przegląd dał nam jedną możliwość sprawdzenia pod kątem tego rodzaju błędu. Polegaliśmy na recenzentach, którzy mieli zgłaszać implementacje większe lub bardziej złożone, niż wymagał tego problem, a te zmiany nadal przechodziły. Dzięki temu mogliśmy mieć pewność, że nadmiernie rozbudowane implementacje nie były przyczyną całego wzrostu.

Te porównania nie były kontrolowane i nie mogliśmy oddzielić wpływu /spec-driven od zróżnicowania projektów lub szerszych ulepszeń w narzędziach agenta. Mimo tych ograniczeń wyniki dodały nam otuchy.

Co jeszcze wymaga dopracowania

Weryfikacja dokumentów może stać się wąskim gardłem

Utworzenie specyfikacji zajmowało od 30 minut do kilku dni, w zależności od znajomości danego obszaru przez inżyniera oraz złożoności i ryzyka związanego z projektem. Inżynierowie mogli używać polecenia /spec-driven, aby agent szybko przygotował wersję roboczą specyfikacji, ale jej przegląd nadal wymagał czasu.

W ramach jednego nakładu pracy inżynier spędził wiele godzin na przeglądaniu pull requesta z plikiem roboczym research.md, w którym agent zapisał to, czego dowiedział się z bazy kodu, dokumentacji i wcześniejszych decyzji przed sporządzeniem wersji roboczej specyfikacji. Niektóre z tych ustaleń były niejasne, niedokładne lub nieco błędne.

Ten przegląd wykazał, że nie uzgodniliśmy, czy te pliki są tymczasowymi notatkami roboczymi, czy też dokumentacją, na której przyszli inżynierowie powinni polegać. Niektórzy inżynierowie cenili sobie zapis sposobu podjęcia decyzji. Inni obawiali się, że zatwierdzenie niedoskonałych wyników badań sprawi, iż będą one postrzegane jako wiarygodne.

W jednym z zespołów ds. infrastruktury przegląd specyfikacji stał się nowym czynnikiem blokującym przed wdrożeniem.

Wydawało mi się, że polecenia i przepływ pracy są znacznie bardziej skomplikowane i czasochłonne niż samo wygenerowanie planu, a następnie jego wdrożenie.”

Większość recenzentów nie chciała czytać długiej specyfikacji, a potem jeszcze sprawdzać kodu. Zanim praca dotarła do etapu pull requesta, przekazanie musiało zawierać podsumowanie decyzji, powód jej podjęcia, elementy, które wydawały się ryzykowne, oraz sposób sprawdzenia wyniku. Jeśli sam kierunek wymagał weryfikacji, musieliśmy poprosić o to wcześniej, gdy jeszcze można go było łatwo zmienić.

Przydatna specyfikacja zmienia się wraz z postępem projektu

Inżynierowie w trakcie wdrażania planu stale zdobywali nową wiedzę. Aktualizowanie specyfikacji o zdobytą wiedzę wymagało nakładu pracy. Jej szczegółowość była pomocna podczas wdrażania, ponieważ pokazywała, co według agenta było tworzone. Później wiele z tych szczegółów powielało kod.

Obecnie uważamy, że użyteczna specyfikacja powinna się rozwijać, gdy projekt jest jeszcze niepewny, i zmniejszać się, gdy kod może wyjaśnić sposób implementacji. To, co pozostanie, powinno pomóc kolejnemu czytelnikowi zrozumieć projekt, ważne decyzje, ograniczenia i nierozwiązane ryzyka.

Układanie ukończonych specyfikacji rodzi powiązane pytanie: co powinno się z nimi stać? Zbyt długo zwlekaliśmy z udzieleniem odpowiedzi. Pozostawienie ich w monorepo ułatwia ich znalezienie, ale sprawia też, że pozostają tam dokumenty, za które nikt nie jest odpowiedzialny. Przenosimy je do osobnego archiwum. Nadal potrzebujemy krótszego procesu przekazywania, który zachowa to, co będzie ważne później. Jeśli dokument generował więcej pracy, niż jej oszczędzał, to nie był pomocny.

Wbudowywanie pętli informacji zwrotnych w system

Czasami rozwiązaniem nie był kolejny dokument, ale zmiana w systemie otaczającym agenta. Jednym z przykładów był błąd w sposobie, w jaki /spec-driven odczytywał język Markdown: nagłówki i pola wyboru w przykładach mogły być mylnie interpretowane jako rzeczywiste kamienie milowe lub niedokończone zadania. Po zarejestrowaniu błędu przeszukaliśmy pozostałą część /spec-driven i znaleźliśmy kilka poleceń z własnym małym parserem Markdown i tym samym problemem. Zastąpiliśmy je jednym wspólnym parserem, dodaliśmy testy regresji i kontrolę architektury, a następnie wprowadziliśmy poprawkę do środowiska. OpenAI opisuje powiązane podejście jako inżynierię uprzęży: umieszczaj ważną wiedzę tam, gdzie agenci mogą ją znaleźć, spraw, by zasady były egzekwowalne, i wykorzystuj błędy do ulepszania środowiska wokół agenta.

Inne wnioski nie mogły zostać przekształcone w testy ani reguły dotyczące architektury. Na podstawie powtarzających się błędów opracowaliśmy wskazówki. Ponieważ /spec-driven prowadził użytkowników przez przewidywalny przepływ pracy, mogliśmy wyświetlać każdą lekcję, gdy agent docierał do odpowiedniego etapu. Inżynierowie nadal decydowali, które wnioski mają zastosowanie poza pierwotnym projektem.

Przetestowaliśmy wskazówki na ośmiu wcześniejszych pull requestach, a także na sztucznych przypadkach zaprojektowanych w celu wychwycenia nieistotnych porad. W dalszej kolejności przetestowaliśmy trzy z tych wcześniejszych zadań z użyciem krótkich, średnich i szczegółowych podpowiedzi, co dało łącznie dziewięć porównań. W ośmiu z dziewięciu porównań wskazówki ujawniły przydatne dodatkowe pytanie lub granicę planowania. Oddzielny test objął jeszcze trzy wcześniejsze zadania. Wyraźnie poprawił dwa plany; w trzecim agent bez wskazówek już zauważył problem.

Najbardziej przydatne wskazówki dotyczyły zmian w zachowaniu, konsumentów i wariantów, których dotyczyły zmiany, oraz kontraktów między interfejsami API, schematami lub parserami. Oceny obejmowały tylko pytania i plany. Nie mierzyliśmy, czy wytyczne przyspieszyły wdrożenie. Wąskie wytyczne również szybciej traciły aktualność, a czasami pojawiały się w zadaniach, które nie były z nimi powiązane.

Utrzymanie wytycznych i ocen wymagało więcej pracy niż stworzenie pierwszej wersji. Mogliśmy zidentyfikować „minę” za pomocą wytycznych, usunąć ją, naprawiając leżący u jej podstaw system, lub zaakceptować ryzyko, że agent lub recenzent będzie musiał ją ponownie znaleźć. Zazwyczaj najpierw ją lokalizowaliśmy, ponieważ było to tańsze rozwiązanie. Naprawienie podstawowego interfejsu API, testu, dokumentacji lub przykładu wymagało więcej pracy, ale przyniosło korzyści wszystkim i wyeliminowało potrzebę stosowania wytycznych.

Jak teraz podeszlibyśmy do podejścia opartego na specyfikacjach

Chcieliśmy zapobiec sytuacji, w której inżynierowie powtarzają te same monity i na nowo wyjaśniają projekt, nie eliminując przy tym użytecznych przeszkód. Agent nadal musiał się zatrzymać, gdy miał ważne pytanie, brakowało dowodów lub kolejny krok wymagał oceny człowieka. Opracowaliśmy kilka praktycznych wytycznych:

• W przypadku większości drobnych, lokalnych zmian wystarczy konwersacja lub krótki plan.

• Skorzystaj z podejścia „najpierw specyfikacja”, aby uzgodnić kierunek działań. Zachowaj specyfikację jako punkt odniesienia, gdy decyzje muszą pozostać ważne podczas późniejszych sesji lub przekazywania zadań.

• Nie umieszczaj w specyfikacji wszystkich brakujących elementów. Narzędzie powinno dostarczać kontekstu i przeprowadzać kontrole; ocena architektury nadal wymaga weryfikacji przez człowieka.

Jeśli specyfikacja jest warta zachowania, sporządź ją z myślą o kolejnym czytelniku. Zadbaj o to, aby decyzje i ryzyka były łatwe do znalezienia, dodawaj linki do dowodów zamiast je kopiować i zdecyduj, co powinno się stać ze specyfikacją po zakończeniu projektu.

Co dalej?

Po trzech miesiącach inżynierowie nadal korzystają z /spec-driven, gdy praca trwa przez wiele sesji, jest przekazywana między osobami lub dzieli się na wiele powiązanych ze sobą zadań. Używali jej do utrzymywania ciągłości realizacji wielomiesięcznych projektów oraz do organizowania dużych partii zadań wykonywanych przez agentów. To dobry wynik jak na eksperyment wewnętrzny.

W miarę rozszerzania zakresu /spec-driven, aby obsługiwać więcej rodzajów pracy, niektóre nowe funkcje rozwiązywały rzeczywiste problemy konkretnych zespołów, ale jednocześnie sprawiały, że przepływ pracy stawał się bardziej skomplikowany dla wszystkich. W kolejnej wersji chcemy skupić się na mniejszym, bardziej ukierunkowanym rdzeniu.

Ludzie mają stanowcze zdanie na temat SDD i inżynierii wiązek przewodów. Więcej dowiedzieliśmy się, wypróbowując je w ramach rzeczywistej pracy, niż dyskutując o każdym z nich. Zanim dodamy więcej procesów, teraz pytamy, czego brakuje agentowi w danym projekcie. Zacznij od małych kroków, sprawdź, w których miejscach przepływ pracy pomaga, a w których przeszkadza, a następnie dostosuj go na podstawie zdobytych spostrzeżeń.

[1] Birgitta Böckeler, „Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl”, październik 2025 r.

[2] François Zaninotto, „Spec-Driven Development: The Waterfall Strikes Back” („Programowanie oparte na specyfikacjach: kontratak modelu kaskadowego”), listopad 2025 r.

[3] Gabriella Gonzalez, „A sufficiently detailed spec is code” („Wystarczająco szczegółowa specyfikacja to kod”), marzec 2026 r.

O autorze

Walter Li jest inżynierem oprogramowania w zespole ds. podstawowej infrastruktury pamięci masowej w Asanie, a Rohan Batra jest inżynierem oprogramowania w zespole ds. struktur backendowych. Obaj spędzili kilka miesięcy w zespole Agent Success Tiger Team, gdzie kierowali opracowywaniem i oceną opisanego w tym artykule przepływu pracy opartego na specyfikacjach (/spec-driven).

Podziękowania dla zespołu

Szczególne podziękowania dla Leo Zhanga, Karola Krupy, Gordiego Levitsky'ego i Mitcha Conquera za pomoc w opracowaniu i rozwinięciu podejścia /spec-driven oraz za to, że byli jednymi z pierwszych użytkowników.