Rozwój kierowany specyfikacjami z użyciem agentów kodujących AI: praktyczny przewodnik
Rozwój oparty na specyfikacjach z użyciem agentów kodujących AI: czterofazowy proces pracy, pliki AGENTS.md i SPEC.md, role wielu agentów, poziomy dojrzałości oraz sposoby wykrywania odchyleń.
Źródła: Spec-Driven Development with AI Coding Agents: The Definitive Guide
Narzędzia takie jak Claude Code, GitHub Copilot, Cursor i Windsurf potrafią teraz generować, przekształcać i testować kod znacznie szybciej niż jakikolwiek człowiek. Szybkość bez precyzji jednak często staje się wadą. Wiele zespołów używających tych narzędzi pracuje w błędnym cyklu poleceń, otrzymywania wyników, naprawiania błędów i ponownych poleceń, a ten cykl pogarsza się w miarę rozwoju bazy kodu. Przyczyną zazwyczaj nie jest model – chodzi o to, że nikt nie ma uporządkowanego sposobu na poinformowanie agenta o tym, czego się oczekuje.
Rozwój oparty na specyfikacjach (SDD) to jedna z rozwiązań. Traktuje on strukturalną specyfikację jako główny produkt procesu dostarczania: dokument, z którego wyprowadzany, sprawdzany i kontrolowany jest kod.
Podstawy koncepcyjne
Dlaczego podejście oparte na nastroju w kodowaniu zawodzi
„Kodowanie na podstawie nastroju” oznacza opisywanie pożądanego rezultatu w sposób konwersacyjny oraz kierowanie wynikiem za pomocą nieformalnych pytań dodatkowych. Dobra jest do zadań izolowanych, szybkich prototypów oraz eksperymentów jednosesyjnych. Słabo radzi sobie w skali większej, a powód tego jest wart zrozumienia.
Zanik kontekstu
Każda sesja odbywa się w ramach okna kontekstowego, czyli ograniczonej ilości informacji, nad którą agent może rozważać jednocześnie. Podczas kodowania na podstawie nastroju stan projektu istnieje tylko w historii rozmowy. W miarę wydłużania się konwersacji wczesne decyzje architektoniczne, ograniczenia bezpieczeństwa oraz wybory bibliotek wychodzą poza to okno. Agent zastępuje je wtedy wiarygodnymi alternatywami, często bez podania tego faktu. To właśnie jest zanik kontekstu.
Jego typowym objawem jest odchylenie w implementacji: powolne oddzielanie się tego, co agent uważa, że buduje, od tego, o co pierwotnie prosił biznes. Kod przechodzi testy, działa samodzielnie i wygląda poprawnie, jednak łamie wcześniej ustalone zasady strukturalne lub biznesowe. W systemach korporacyjnych jest to rodzaj błędu najtrudniejszy do zdiagnozowania i najdroższy w naprawie.
Główna idea
SDD opiera się na jednej zasadzie architektonicznej: specyfikacja jest głównym produktem, a implementacja wynika z niej. To coś więcej niż tylko drobna modyfikacja procesu pracy. Odwraca tradycyjny model, w którym najpierw pojawia się kod, a dokumentacja idzie za nim.
W tym podejściu specyfikacja jest czytelna dla maszyn, kontrolowana wersjami, dynamiczna i wykonywalna. Pełni rolę umowy pomiędzy intencją człowieka a działaniem agenta, który działa w ramach ograniczeń tej umowy, zamiast zgadywać. Dokładna umowa zapewnia przewidywalny wynik, natomiast niejednoznaczna powoduje zmienność. Krótko mówiąc, nie można kontrolować tego, co stworzy agent, dopóki nie zdefiniowano dokładnie, co ma zostać stworzone.
Sześć elementów specyfikacji czytelnej dla maszyn
Specyfikacja przeznaczona dla agenta musi przezwyciężyć niejednoznaczność języka naturalnego. Sześć elementów zwykle wymienianych jako niezbędne, aby zapobiec niepożądanym założeniom ze strony agenta to:
- Wyniki – rezultaty, które powinno osiągnąć zadanie.
- Zakres – w tym to, co jest wyraźnie pomijane.
- Ograniczenia, takie jak wymagane technologie, zasady bezpieczeństwa i limity wydajności.
- Decyzje już podjęte, więc nie są ponownie otwierane.
- Zadania – praca podzielona na kroki.
- Kryteria weryfikacji – sprawdzenia potwierdzające ukończenie zadania.
Proces SDD
Cztery fazy z kontrolami ludzkimi
Proces składa się z czterech kolejnych faz, a każda z nich zawiera moment, w którym konieczna jest interwencja osoby. Te ludzkie punkty kontrolne nie są biurokracją. Zapobiegają one narastaniu błędów w dalszej części procesu, a pomijanie jednego z nich w celu „przyspieszenia” zazwyczaj przynosi efekt odwrotny.
Faza 1 – określenie szczegółów. Rozwijający opisuje cel na poziomie ogólnym, a następnie albo agent, albo sam rozwijający przerabia to na ustrukturyzowaną specyfikację funkcjonalną: ścieżki użytkownika, wyniki biznesowe, kryteria akceptacji oraz wyraźne granice zakresu. Zadaniem tej osoby jest przegląd architektoniczny – sprawdzenie wyniku pod kątem halucynacji, pominięć i błędnych interpretacji przed rozpoczęciem jakichkolwiek planowań. Należy odłożyć fazę 2, dopóki faza 1 nie będzie wolna od niejednoznaczności: niejasna specyfikacja rzadko prowadzi do niejasnej implementacji, lecz do takiej, która jest pewna siebie, ale błędna.
Faza 2, plan. Po zatwierdzeniu specyfikacji agent opracowuje plan techniczny, który obejmuje decyzje architektoniczne, modele danych, umowy API oraz wybory technologiczne. Plan zawiera również ograniczenia organizacyjne, takie jak „przechowywanie danych w PostgreSQL” lub „każdy punkt końcowy API wymaga autoryzacji JWT”. Weryfikacja przez człowieka w tym etapie pozwala wykryć błędy architektoniczne, zanim zostaną one zapisane w tysiącach wygenerowanych linijek kodu.
Faza 3, podział zadań. Zatwierdzony plan jest dzielony na małe zadania, z których każde można przetestować niezależnie. Granularność jest prawdopodobnie najmniej docenianą zmienną w SDD. Zadanie powinno być realizowalne i weryfikowalne w ramach jednego uruchomienia agenta, a jeśli zmusza agenta do jednoczesnego radzenia sobie z więcej niż trzema odrębnymi kwestiami, jest zbyt duże. Dobrze podzielony wykaz służy również jako podstawa dla rozwoju opartego na testach, ponieważ każde zadanie ma jasne warunki sukcesu przed rozpoczęciem pracy, a projekt posiada częste punkty weryfikacji.
Faza 4, implementacja i weryfikacja. Agent pisze kod zadanie po zadaniu, przy czym wyniki są skoncentrowane i można je audytować oraz powiązać z konkretnym wymogiem. Ta faza jest łączona z wzorcem weryfikatora, w którym jeden agent generuje kod, a drugi agent lub zautomatyzowany zestaw testów sprawdza go pod kątem kryteriów przyjęcia.
Aktualizacja specyfikacji w obu kierunkach
Jedną z najważniejszych praktyk, która jest jednak często łamana, jest dwukierunkowa aktualizacja. Załóżmy, że w fazie 4 agent podejmuje decyzję, której specyfikacja nie obejmuje, na przykład wybór biblioteki z powodów wydajnościowych lub radzenie sobie z przypadkiem krawędziowym w niewidocznym sposób. Decyzja ta powinna zostać natychmiast zapisana z powrotem do specyfikacji.
Jeśli tak nie jest, gromadzi się „dług specyfikacyjny”: udokumentowane intencje i rzeczywiste zachowanie zaczynają się różnić. Ta rozbieżność zamienia żywą specyfikację w przestarzały plik, któremu nikt nie ufa i który ostatecznie nikt nie czyta, a staje się bezużyteczny dokładnie wtedy, gdy jest najbardziej potrzebny, podczas późniejszych zmian wspomaganych przez sztuczną inteligencję. Zasada jest prosta: gdy implementacja odbiega od specyfikacji, należy ją zaktualizować natychmiast, a nie w następnym sprintzie. Dług specyfikacyjny rośnie szybciej niż dług techniczny, ponieważ zatruwa punkt wyjścia dla każdej kolejnej generacji programów.
Artefakty trwałości i konstytucja projektu
Dlaczego agenci potrzebują konstytucji
Agent kodujący nie ma pamięci między sesjami. Każda nowa sesja zaczyna się od tego, co wprowadzisz do jej kontekstu. Bez mechanizmu przechowywania danych każda sesja jest jak czysta kartka – agent nie zna twoich standardów bezpieczeństwa, konwencji nazewania, zablokowanych bibliotek ani decyzji architektonicznych.
„Konstytucja projektu” to zbiór trwałych plików, które rozwiązują ten problem. Są to uporządkowane pliki zapisywane w repozytorium obok kodu źródłowego, które zapewniają agentowi wiedzę instytucjonalną, dzięki której może działać jak członek zespołu, a nie osoba z zewnątrz.
Główne pliki
AGENTS.md lub CLAUDE.md – instrukcja obsługi. To najważniejszy plik: README przeznaczony dla agenta, który jest czytany na początku każdej sesji, aby dowiedzieć się, jak funkcjonuje dany projekt. Powinien być napisany tak, aby był łatwy do przetworzenia przez maszyny, a niekoniecznie czytelny dla ludzi. Skuteczny plik zawiera trzy rodzaje informacji:
- Detale operacyjne, których agent nie może wywnioskować: dokładne polecenia kompilacji z flagami, sposób uruchamiania testów, konfiguracja narzędzia do sprawdzania kodu oraz nazwy zmiennych środowiskowych.
- Konwencje nazewnicze i strukturalne: do czego służy każdy katalog, jak nazywane są pliki oraz jak zorganizowane są moduły.
- Hierarchia stopni powagi działań agenta, wykorzystująca spójny system sygnałów. Zawsze wykonywaj czynności takie jak sprawdzanie kodu, uruchamianie odpowiednich testów oraz przestrzeganie konwencji nazewania. Najpierw zapytaj, zanim zmienisz schematy bazy danych, dodasz zależności lub modyfikujesz umowy API. Nigdy nie zapisuj w historii sekretów, nie edytuj plików
.envani nie zmieniaj logiki autoryzacji bez przeglądu.
SPEC.md – żywa specyfikacja. Jest to autorytatywny opis tego, co system powinien robić. Nie jest to zapis historii. Odzwierciedla aktualne zamierzone zachowanie, włączając każdą decyzję podjętą podczas implementacji. Jeśli kod odbiega od SPEC.md, plik jest aktualizowany, a gdy zmieniają się wymagania, najpierw edytuje się SPEC.md, a następnie implementacja.
PLAN.md – dokument architektury. Zawiera decyzje architektoniczne, wybory technologiczne oraz ograniczenia dotyczące całego systemu. Odpowiada na pytanie „dlaczego zbudowano to w taki sposób?”, dostarczając uzasadnienia, które zapobiega temu, by późniejsze agenty i inżynierowie cofali starannie podjęte decyzje.
Pliki konfiguracyjne specyficzne dla narzędzi. Każde narzędzie ma własne zasady dotyczące plików z regułami. Warto wspomnieć o formacie .mdc używanym przez Cursor, ponieważ łączy Markdown z elementami YAML, umożliwiając przypisywanie reguł do wzorów plików. Reguły backendowe, takie jak wymagania autoryzacyjne i wzorce dostępu do bazy danych, mogą być wtedy stosowane tylko wtedy, gdy agent pracuje z plikami backendowymi, co chroni pamięć roboczą przed nieistotnym kontekstem podczas pracy z interfejsem frontendowym.
Orchestracja wielu agentów
Dlaczego jeden agent nie wystarcza
Jedyny agent odpowiedzialny za całą bazę kodów przedsiębiorstwa napotyka poważny limit – okno kontekstowe. Duży system składający się z 100 000+ plików, kilku usług, złożonych przepływów danych oraz pełnego zestawu testów nie mieści się w kontekście jednego agenta. Agent musi zdecydować, co włączyć, a te decyzje powodują „ślepe plamy”.
Idea orkiestracji wielu agentów polega na naśladowaniu sposobu pracy silnego zespołu ludzkiego, w którym istnieją określone role, uporządkowane przekazywanie zadań oraz jedna specyfikacja, którą wszyscy traktują jako prawdę.
Trzy role
Koordynator. Ten agent pełni rolę menedżera projektu i architekta. Posiada pełny obraz sytuacji, czyli kompletną specyfikację, listę zadań oraz ograniczenia architektoniczne. Dzieli specyfikację na podspecyfikacje, przekazuje je osobom realizującym zadania, monitoruje konflikty pomiędzy równoległymi procesami pracy i upewnia się, że ukończenie jednego zadania nie podważy całości architektury.
Osoba realizująca zadanie. Osoby te są specjalistami. Każda z nich otrzymuje podspecyfikację obejmującą jedno zadanie lub małą grupę powiązanych ze sobą zadań i pracuje w izolowanym drzewie projektu Git, dzięki czemu nie dochodzi do konfliktów na poziomie plików z innymi osobami realizującymi zadania równolegle. Nie wie nic o pracach poza swoim zadaniem i nie jest za nie odpowiedzialna. Ta izolacja nie jest ograniczeniem – to ona sprawia, że wynik jest deterministyczny, poddawalny testom i możliwy do sprawdzenia.
Weryfikator. Weryfikator ma odwrotny cel. Podczas gdy implementator stara się ukończyć zadanie, weryfikator próbuje znaleźć miejsce, w którym wynik nie spełnia specyfikacji. To podejście inspirowane jest formalną weryfikacją i badaniami bezpieczeństwa i należy do najskuteczniejszych mechanizmów kontroli jakości oferowanych przez SDD. Weryfikator sprawdza wynik w odniesieniu do kryteriów przyjęcia i szuka braków funkcjonalnych, naruszeń zasad bezpieczeństwa, wykroczeń przeciwko ograniczeniom wydajności oraz odchyleń od specyfikacji. Po znalezieniu niezgodności nie naprawia kodu. Zamiast tego przekazuje informacje koordynatorowi w postaci ustrukturyzowanego opisu, który łączy tę niezgodność z konkretnym wymogiem.
Dla systemów produkcyjnych taki weryfikator przeciwnikowy nie powinien być opcjonalny. Agent, który pisze i sprawdza swój własny kod, niemal zawsze uzna jego pracę za akceptowalną, a wartość weryfikatora polega na tym, że jest niezależny od implementatora i stoi w opozycji do niego.
Wykonywanie równoległe z drzewami roboczymi
Jedną z najcenniejszych cech systemów SDD opartych na wielu agentach jest równoległość: kilku implementatorów pracujących jednocześnie nad różnymi funkcjami lub usługami, każdy w swoim własnym drzewie roboczym. W przypadku dużych projektów z niewieloma zależnościami między zadaniami czas realizacji może znacznie się skrócić.
Drzewa robocze Git umożliwiają to. Każdy agent ma oddzielny katalog roboczy przypisany do tego samego repozytorium, dzięki czemu unikane są konflikty plików, podczas gdy koordynator monitoruje postępy we wszystkich ścieżkach roboczych z jednego miejsca. Po zatwierdzeniu przez weryfikatora koordynator łączy ukończone drzewa robocze i utrzymuje główną gałąź w czystości.
Diagramy jako kod
Dlaczego diagramy powinny być częścią specyfikacji
Diagramy architektury były tradycyjnie tworzone później, jako dokumentacja istniejącego już kodu. W SDD pojawiają się na wczesnym etapie, jako część specyfikacji i planu, przed jakąkolwiek implementacją.
Powodem jest aspekt diagnostyczny. Żądanie od agenta ważnego diagramu Mermaid na podstawie specyfikacji zmusza go do wyraźnego rozważenia przepływu danych, zależności między usługami oraz przejść stanów przed napisaniem kodu. Nieuporządkowany lub niespójny diagram na tym etapie jest pewnym znakiem, że specyfikacja jest niejednoznaczna lub ma błędy strukturalne, a naprawa takich problemów w diagramie kosztuje znacznie mniej niż ich naprawa w wdrożonym kodzie.
Formaty
Formaty oparte na tekście, szczególnie Mermaid i D2, przewyższają obrazy binarne do tego celu. Można je wersjonować i porównywać, a agenty mogą je czytać bezpośrednio. Mogą być również aktualizowane w miarę rozwoju specyfikacji, co zapewnia zgodność dokumentacji strukturalnej z implementacją.
Trzy poziomy dojrzałości
Praktycy ustalili trzy poziomy SDD. Nie stanowią one drabiny, którą każdy zespół musi pokonać w określonej kolejności. Są to różne profile kompromisów dla różnych kontekstów, a wiedza o tym, który pasuje do danej sytuacji, jest kluczowa przed jakimkolwiek wdrożeniem.
Poziom 1, specyfikacja na pierwszym miejscu. Dla jednego zadania przygotowuje się szczegółową specyfikację. Gdy implementacja zostanie ukończona i zweryfikowana, specyfikacja traktowana jest jako tymczasowa – może być przechowywana dla referencji, ale nie jest dalej utrzymywana. Nadaje się do izolowanych funkcjonalności, jednorazowych migracji oraz eksperymentów, w których konieczność utrzymania specyfikacji na poziomie 2 nie jest uzasadniona. Zwolennicy twierdzą, że ten poziom zapewnia około 60% wartości SDD przy znacznie niższych kosztach, co czyni go rozsądnym punktem wyjścia dla początkujących. Należy go stosować do nowych funkcjonalności o określonych granicach, z jasnymi kryteriami przyjęcia, bez zależności między usługami, a czas realizacji mierzony w dniach.
Poziom 2, oparty na specyfikacji (zalecana wartość domyślna). Specyfikacja pełni rolę równorzędnego partnera kodowi przez cały okres życia projektu, przy czym oba elementy są regularnie aktualizowane. Gdy zmieniają się wymagania, najpierw zmienia się specyfikacja, a gdy implementacja odbiega od planu, specyfikacja jest natychmiast aktualizowana, aby odzwierciedlać rzeczywiste zachowanie i uzasadnienie tych zmian. Może to wydawać się podwójną koniecznością utrzymania, ale w praktyce obniża całkowite koszty: zapobiega utracie kontekstu pomiędzy sesjami, umożliwia nowym członkom zespołu (ludziom i sztucznej inteligencji) skuteczne włączenie się do pracy oraz sprawia, że późniejsze zmiany wspomagane przez sztuczną inteligencję są znacznie bardziej niezawodne. Jest to standard dla systemów produkcyjnych, projektów zespołowych oraz wszystkiego, co ma się rozwijać.
Poziom 3, spec-as-source (eksperymentalny). Specyfikacja jest jedynym głównym produktem. Kod jest traktowany jak wygenerowany wynik kompilacji, odtwarzany na żądanie i nigdy nie edytowany ręcznie. Jest to teoretyczny cel SDD, w którym inżynierowie zajmują się utrzymywaniem specyfikacji, a sztuczna inteligencja – implementacjami. Istnieje w nim nierozwiązany problem: determinizm. Identyczne specyfikacje mogą w różnych sesjach generować kod o różnej strukturze składniowej, choć funkcjonalnie równoważny, co utrudnia tworzenie różnic, debugowanie i przeglądanie kodu. Traktuj to jako rozwiązanie eksperymentalne. Może być odpowiednie dla projektów od zera z bardzo kompletnymi specyfikacjami, silną kontrolą ze strony sztucznej inteligencji oraz tolerancją na niedojrzałe narzędzia, ale nie zaleca się go do krytycznych systemów produkcyjnych w 2026 roku.
Przewodniki według roli
Inżynierowie i architekci
Główną umiejętnością inżyniera staje się inżynieria kontekstu. Pisanie poprawnej składni to coś, co agenci robią z prędkością maszyn, więc wartość inżyniera polega na definiowaniu precyzyjnego kontekstu architektonicznego, dobieraniu tego, co agent może zobaczyć, oraz sprawdzaniu, czy jego wynik odpowiada strukturalnym celom systemu. Obejmuje to tworzenie dobrych plików AGENTS.md i SPEC.md, ustalanie zasad zarządzania bibliotekami (wyraźnej listy dozwolonych i zabronionych zależności), określanie wymagań bezpieczeństwa i zgodności w formie czytelnej dla maszyn oraz strukturyzowanie zadań tak, aby różne aspekty pozostawały oddzielone.
Podstawowa rutyna dla inżynierów:
- Przed wdrożeniem jakiejkolwiek funkcji wspomaganej przez AI, utwórz lub zaktualizuj plik SPEC.md, aby zawierał sześć wcześniej opisanych elementów.
- Przejrzyj plik AGENTS.md i upewnij się, że polecenia budowania, wzory testów, zasady nazywania oraz hierarchia powagi nadal odzwierciedlają rzeczywistość.
Blok z ograniczeniami to przydatny szablon, który można dodać do każdej specyfikacji. Zawiera on listę stacku technologicznego (wszystkie wymagane technologie), zakazanych bibliotek (wraz z ich opisem), wymagań bezpieczeństwa (sposób autoryzacji użytkowników, wymagana szyfrowanie, sposób obsługi danych), ograniczeń wydajnościowych (celowe opóźnienie i przepustowość), wymagań dotyczących testowania (progi pokrycia i wymagane rodzaje testów) oraz wzorców architektonicznych (te wymagane i te, których należy unikać).
Menedżerowie produktów technicznych
Od dokumentów wymagań produktu do krótkich opisów zachowań. Klasyczny dokument wymagań produktu zakłada istnienie ludzkich inżynierów, którzy go przeczytają, będą się nad nim kłócić i wdrożą go, korzystając ze swojego osądu. W podejściu SDD wynik pracy TPM musi mieć postać krótkiego opisu zachowań: maszynowo czytelnego opisu tego, jak produkt powinien reagować na konkretne potrzeby użytkowników, z precyzyjnym określeniem wymagań dotyczących działania agenta.
Różnica wykracza poza kwestię stylu. Dokument wymagań produktu może stwierdzić „poprawić doświadczenie zakupowe”. Krótki opis zachowań musi natomiast określić, co robi obecny proces zakupowy, jakie problemy użytkowników on powoduje, które zmiany w zachowaniu uznaje się za poprawę, jak mierzy się sukces, jakie przypadki krawędziowe należy rozwiązać oraz co system absolutnie nie powinien robić.
Pętla prototypowania. SDD umożliwia TPM skrócenie zwykłego procesu przenoszenia projektu z etapu projektowego do inżynieryjnego. Zamiast czekać na mockupy stworzone przez projektanta, a następnie aż inżynier je zrealizuje, TPM może generować interaktywne prototypy bezpośrednio na podstawie opisu zachowania, oceniając funkcjonowanie systemu, a nie tylko statyczne ekrany. Jeśli prototyp nie odpowiada założeniom, specyfikacja jest aktualizowana, a system ponownie generuje implementację, dzięki czemu pętla zwrotna działa na podstawie specyfikacji, a nie kodu. To eliminuje kilka etapów przekładu (PRD, przeniesienie projektu, przeniesienie do inżynierii), w których intencje często ulegają zniekształceniu.
CTO i kierownicy zespołów inżynieryjnych
Zarządzanie. Priorytetem CTO w organizacji opartej na agentach jest ramy zarządzania, które umożliwiają sztucznej inteligencji przyspieszenie procesów realizacji bez narażania jakości, bezpieczeństwa czy zgodności z regulacjami. SDD dostarcza warstwę kontroli, ale tylko przy zachowaniu dyscypliny organizacyjnej. W skali dużych projektów istotne są trzy mechanizmy:
- Kontrola wersji specyfikacji. PLIKY SPEC.md, PLAN.md i AGENTS.md znajdują się w tym samym repozytorium co kod i przechodzą przez ten sam proces przeglądania i zatwierdzania.
- Ślady audytowe. Każda zmiana stworzona przez sztuczną inteligencję powinna być powiązana z konkretnym wymogiem specyfikacji, co nie jest opcjonalne w branżach podlegających regulacjom.
- Ludzka kontrola na każdym etapie przejścia. Nic nie może zostać przesunięte samodzielnie od etapu określenia specyfikacji, przez planowanie, aż po realizację bez zatwierdzenia na każdym kroku.
Kierownicy techniczni powinni również oceniać narzędzia do programowania z wykorzystaniem AI według tego frameworku, sprawdzając, w jakim stopniu każde z nich wspiera trwałe pliki z regułami, mechanizmy weryfikacji, możliwość śledzenia oraz procesy pracy z udziałem wielu agentów.
Mierzenie zwrotu z inwestycji. Organizacje przyjmujące podejście SDD często donoszą, że rozwój oprogramowania wydaje się wolniejszy w pierwsze dwa do czterech tygodni, ponieważ inżynierowie poświęcają czas na opracowywanie specyfikacji zamiast od razu zajmować się kodem. To spostrzeżenie jest słuszne, ale jego interpretacja jest myląca. Praca nad specyfikacjami nie stanowi nowego obciążenia – to praca, która wcześniej była wykonywana nieformalnie, niespójnie i dopiero po implementacji, gdy kosztowała najwięcej. Wskaźniki pokazujące rzeczywisty zwrot znajdują się później w procesie:
- czas od sformułowania wymagań do gotowego do użycia kodu, czyli kodu sprawdzonego, przejrzanego i wdrożonego, a nie tylko napisanego,
- procent przeróbek – udział ukończonych funkcji, które muszą zostać ponownie wykonane z powodu błędnego zrozumienia wymagań,
- czas odzyskania kontekstu – ile czasu potrzebuje programista lub agent, aby znów być produktywnym przy kodzie niezmienianym od 30 dni, oraz
- wskaźnik umykania defektów – udział defektów wykrytych podczas przeglądu specyfikacji w porównaniu z tymi po wdrożeniu.
Zgodnie z doniesieniami zespoły stosujące zaawansowane praktyki SDD odnotowują spadek przeróbek o 40–60%, a czas odzyskania kontekstu znacznie się skraca, ponieważ specyfikacja dostarcza informacji niezbędnych, bez których badanie kodu zajęłoby godziny. Te dane pochodzą z raportów praktyków, a nie z kontrolowanych badań, więc warto zmierzyć własny poziom wyjściowy.
Odchylenie intencji
Co to jest
Drift intencji to powolna luka, która powstaje pomiędzy pierwotnymi wymaganiami biznesu a zachowaniem kodu w środowisku produkcyjnym. Nie jest to zjawisko nowe w pracy z wykorzystaniem sztucznej inteligencji i należy do najstarszych problemów inżynierii oprogramowania, jednak agenci kodujący stanowią niebezpieczny czynnik przyspieszający ten proces. Optymalizują one kod pod kątem wiarygodności i przejścia testów, a nie zgodności z wymaganiami biznesowymi. Jeśli poprosimy je o stworzenie systemu do przetwarzania płatności, napiszą kod, który przejdzie wszystkie testy i obejmie każdy określony przypadek. Jeśli specyfikacja jest niekompletna lub przestarzała, agent wypełnia braki statystycznie prawdopodobnymi standardami z danych treningowych. Takie rozwiązania są przydatne w systemach ogólnych, ale mogą okazać się katastrofalne dla specyficznych zasad biznesowych danego przedsiębiorstwa. Najgorszy rodzaj driftu to taki, który zostaje zauważony dopiero wtedy, gdy powoduje straty dla klienta, audyt zgodności lub incydent w produkcji, ponieważ agenci doskonale potrafią tworzyć kod, który wygląda poprawnie, choć w rzeczywistości ma subtelne błędy.
Obrony
- Żywa specyfikacja. Pierwszą obroną jest specyfikacja aktualizowana w czasie rzeczywistym w miarę podejmowania decyzji. Każde odstępstwo od SPEC.md, bez względu na to, jak małe czy dobrze uzasadnione, jest natychmiast rejestrowane, dzięki czemu plik zawsze opisuje aktualne zachowanie, a nie pierwotne intencje.
- Weryfikacja adwersarialna. Mechanizm weryfikacji służy jednocześnie do wykrywania odchyleń. Porównywanie wyników z specyfikacją przy każdym zadaniu pozwala wykryć odchylenia na najmniejszym możliwym poziomie, zanim się one nasilą w trakcie kilku cykli implementacji.
- Śledzenie zakresu pokrycia specyfikacji. Bardziej zaawansowane rozwiązania śledzą udział wymagań, które mają zautomatyzowane, weryfikowalne testy. Wymaganie bez testu może pozostać niezauważone, a dążenie do pełnego pokrycia stanowi zastosowanie podejścia test-driven development na poziomie wymagań.
Minimalny AGENTS.md
Gotowy do użycia plik AGENTS.md może być krótki. Musi przynajmniej zawierać jednoparagrafowy opis projektu, dokładne polecenia do budowania, testowania i sprawdzania kodu, zasady nadawania nazw oraz układu katalogów, listy „zawsze”, „najpierw zapytaj” i „nigdy”, odnośniki do plików SPEC.md i PLAN.md oraz zasady zarządzania bibliotekami. Każdą część należy dostosować do używanych narzędzi oraz wymagań organizacji.
Gdzie to was stawia
Rozwój oparty na specyfikacjach nie jest przejściowym trendem ani niewielką poprawką istniejących praktyk. Zmienia to to, z czego składa się praca inżynierska. Dzięki agentom programistycznym wąskim gardłem w procesie realizacji nie jest już szybkość tworzenia składni, lecz dokładność określenia intencji. Specyfikacja jest produktem, kod jest tym, co ją implementuje, a w budowie oprogramowania z użyciem agentów specyfikacja stanowi najważniejszy wynik pracy inżyniera.
Podobne materiały
- Notatki praktyczne: Uruchamiam agenta do programowania AI lokalnie i jego wydajność jest prawie dwukrotnie wyższa — Szczegółowy przewodnik po notatkach praktycznych: Uruchamiam agenta do programowania AI lokalnie i jego wydajność jest prawie dwukrotnie wyższa: umowy, sprawdzania oraz miejsca na kod dostępne dla zespołów wdrażających ten model.
- Inżynieria agentowa w pięciu warstwach: od specyfikacji i agentów równoległych po zasady i nadzór — Karpathy opisał przejście poza model programowania opartego wyłącznie na specyfikacjach. Zapoznaj się z pięcioma warstwami inżynierii agentowej: specyfikacja, orkiestracja, skodyfikowane zasady, ludzka weryfikacja i możliwość obserwacji, a także plan działania na tydzień.