Metoda CIV: jak tworzymy oprogramowanie z SI, nie tracąc kontroli
Od dwóch lat budujemy ShephERP z użyciem sztucznej inteligencji, która pisze większość kodu. Po drodze przekonaliśmy się, że wąskim gardłem nigdy nie był model. Były nim wszystkie pozostałe rzeczy. Ten sposób pracy nazwaliśmy: metodą CIV.
Problem, o którym nikt nie mówi
Obietnica SI w programowaniu jest prawdziwa: agent napisze w dwadzieścia minut to, na co wcześniej trzeba było dwóch dni. Prawie nikt nie mówi jednak o tym, co dzieje się w szóstym tygodniu.
Model językowy to wykonawca zdumiewająco szybki i zdumiewająco dosłowny. Bez kontekstu wymyśla: jeśli nie powiedziałeś mu, że członkowie z przeterminowaną składką tracą zniżkę, zastosuje zniżkę, bo wydaje się to najrozsądniejsze. A bez ograniczeń psuje: naprawi błąd, o który go poprosiłeś, a przy okazji zmieni cztery inne rzeczy, o które nikt go nie prosił.
Efekt jest taki, że projekt rusza z zawrotną prędkością, a po dwóch miesiącach grzęźnie: są w nim tysiące linii, których nikt nie przejrzał, i zespół, który nie odważa się już czegokolwiek ruszać. Przyspieszanie pisania kodu bez zwiększania zdolności jego weryfikacji nie jest produktywnością, tylko długiem zaciąganym z prędkością maszyny.
Nie rozwija się szybciej dzięki lepszym promptom, lecz dzięki lepszemu kontekstowi i lepszym ograniczeniom.
Trzy filary: Kontekst, Iteracja, Weryfikacja
CIV to trzy rzeczy, które trzeba postawić wokół agenta. Nie są to fazy przechodzone jedna po drugiej: działają zawsze równocześnie, a jeśli usuniesz jedną, system się wali.
C — Kontekst: dokumentacja jest kodem źródłowym
W projekcie CIV folder docs/ powstaje przed kodem. Znajduje się w nim wszystko: biznes klienta, jego dokładne słownictwo, reguły ponumerowane jedna po drugiej, decyzje techniczne z datą i odrzuconymi alternatywami oraz protokół każdego spotkania, spisany tego samego dnia.
Nie dokumentujemy po to, żeby przeprowadzać audyt albo żeby dobrze wypaść. Dokumentujemy, bo to dosłownie wejście dla wykonawcy. Protokół ze spotkania to najcenniejszy zasób, jaki może mieć SI, ponieważ zawiera to, czego żadne repozytorium nie jest w stanie wywnioskować: intencję. Kod mówi, co robi system; tylko protokół mówi, dlaczego zrobiono to tak i co się zepsuje, jeśli to zmienisz.
Stąd wynika nasza pierwsza zasada, która jest też najbardziej niewygodna: jeśli nie jest zapisane, nie istnieje. Decyzja, która żyje tylko w jednej rozmowie, nie jest decyzją, tylko plotką, której agent nie może przestrzegać.
I — Iteracja: zgłoszenie to prompt
Praca schodzi na trzy poziomy — epik (kwartał), kamień milowy (to, co można pokazać w ciągu dwóch tygodni) i zadanie (to, co mieści się w jednej sesji) — i ląduje w zgłoszeniach napisanych dla kogoś, kto nie uczestniczył w rozmowie, niczego nie pamięta i nie będzie pytał.
To całkowicie zmienia sposób pisania zgłoszenia. Żadnego „napraw filtr”. Kroki z prawdziwymi danymi, dokładny adres URL, zrzut ekranu opatrzony strzałką wskazującą, co jest źle, wklejone żądanie i odpowiedź, oczekiwany wynik, kryteria akceptacji w formie listy kontrolnej i — linijka, która oszczędza najwięcej pieniędzy — czego NIE wolno ruszać.
Nazywamy to Definition of Ready dla SI i obowiązuje w tym złota zasada: jeśli agent musi o coś zapytać, żeby zacząć, zgłoszenie było źle napisane i wraca do osoby, która je sporządziła. To nie biurokracja. Niekompletne zgłoszenie się nie zatrzymuje: uzupełnia się samo, najbardziej prawdopodobnym założeniem modelu. A najbardziej prawdopodobne założenie prawie nigdy nie jest regułą biznesową twojego klienta.
Każde zadanie przechodzi potem przez sześć zawsze takich samych kroków: czytać, planować, ogradzać, wykonywać, weryfikować i oddawać. Najważniejszy jest drugi: plan zatwierdza się przed napisaniem pierwszej linii kodu. Poprawienie planu kosztuje minutę; poprawienie źle wykonanej pracy kosztuje cały popołudniowy wysiłek.
V — Weryfikacja: najpierw ogrodzenie, potem swoboda
Warto tu rozwiać bardzo częste nieporozumienie, bo od niego zależy wszystko inne. Wiele osób mówi o „testach jednostkowych, e2e i Cypress”, jakby to były trzy rzeczy tego samego rodzaju. Nie są: myli się tu dwie różne osie. Jedna to poziom — ile prawdziwego systemu ćwiczysz — a druga to narzędzie, którym to ćwiczysz. Cypress nie jest poziomem: to narzędzie na poziomie testów end-to-end interfejsu. A „end-to-end” też nie jest jednolite: przetestowanie pełnego API i przetestowanie aplicacji w przeglądarce to co innego, o innym koszcie i innej użyteczności.
W CIV jest sześć poziomów, od najtańszego do najdroższego: typy i styl, jednostkowe, integracyjne, end-to-end API, end-to-end interfejsu oraz testy dymne na produkcji. Pytanie, które zawsze decyduje o tym, gdzie trafia każdy test, brzmi tak samo: jaki jest najmniejszy fragment, w którym tę usterkę da się wykryć? Źle wyliczona zniżka to test jednostkowy, nawet jeśli odkryjesz ją, kupując w sklepie.
Ponad to: pokrycie testami powyżej 95% i zasada, która je utrzymuje: zasada zapadki. Progi tylko rosną. Nigdy nie maleją, nigdy nie obniża się ich „tymczasowo”. Dług, który już istniał, zamraża się z linią bazową i spłaca stopniowo; nowy dług blokuje się tego samego dnia. I żaden błąd nie zostaje zamknięty, dopóki nie zostawi po sobie testu, który by go wykrył: żaden błąd nie umiera bez świadka.
Dlaczego to się samo zwraca
Zwykły projekt się degraduje: każdego miesiąca dotknięcie go kosztuje więcej. Projekt CIV dąży do czegoś odwrotnego, a przyczyna jest konkretna. Kontekst rośnie, więc każde nowe zadanie trafia na teren, na którym wiele już zostało rozwiązane. Ogrodzenie rośnie, więc każda zmiana jest mniej ryzykowna niż poprzednia. A koszt wdrożenia kogoś — albo innego agenta — spada, bo wdrożenie to przeczytanie folderu po kolei.
Mierzymy siedem rzeczy, ale jest jedna, której prawie nikt nie mierzy, a która mówi wszystko: wskaźnik czystych zgłoszeń, czyli odsetek zgłoszeń, które agent rozwiązuje bez konieczności dopytywania. Jeśli ta liczba spada, problem nie tkwi w modelu, którego używasz. Tkwi w twoim kontekście i w tym, jak piszesz zgłoszenia.
Czym CIV nie jest
To nie jest vibe coding. To nie jest pokrycie na pokaz — testy, które dużo uruchamiają i niczego nie sprawdzają. To nie są ceremonialne dokumenty, których nikt nie aktualizuje; przy SI są gorsze niż ich brak, bo agent je czyta i w nie wierzy. To nie są skróty, które od sześciu miesięcy są już na stałe. I przede wszystkim nie jest to puszczenie agenta bez smyczy i nazywanie tego autonomią.
CIV nie powstało przy tablicy: wyrosło z budowy pełnego ERP przy pomocy SI, z naszych pomyłek i z zapisywania, dlaczego do nich doszło. To robimy każdego dnia.
Kontekst. Iteracja. Weryfikacja. Odejmij jeden z trzech i nie ma CIV, jest tylko szczęście.