Około 150 PR-ów w pięć miesięcy: stopniowa modernizacja Rails z agentami AI.

Część najtrudniejszej pracy inżynierskiej zaczyna się w systemach, których architektury nigdy nie opisano. W tym projekcie modernizacja nie była jednorazowym przepisaniem aplikacji. Polegała na odzyskaniu wiedzy, zbudowaniu powtarzalnego procesu pracy i stopniowym przenoszeniu wybranych obszarów starszego kodu do nowszej architektury.

Uwaga o poufności: klient i produkt zostały zanonimizowane. Opis procesu, narzędzi i podane liczby opierają się na rzeczywistym projekcie; szczegóły identyfikujące zostały pominięte.

Punkt wyjścia: duża aplikacja bez mapy

System był rozwijany przez lata, ale nie miał użytecznego opisu architektury ani sprawdzonej instrukcji uruchomienia. Wiedza o zależnościach i wymaganych usługach była rozproszona pomiędzy kodem i doświadczeniem osób pracujących przy projekcie. Pierwsze uruchomienie środowiska lokalnego zajęło mi około ośmiu godzin, głównie przez stare pakiety i zależności, które trzeba było kolejno rozpoznać.

W takim systemie wąskim gardłem nie jest szybkość pisania kodu, lecz jakość zrozumienia. Dlatego pierwszym celem nie była nowa funkcja. Najpierw trzeba było stworzyć kontekst, na którym mogli polegać zarówno inżynierowie, jak i agenci.

Dokumentacja, którą można wykonać

Kierowałem agentami analizującymi starszą i nowszą część aplikacji. Odtworzyliśmy odpowiedniki usług i struktur danych, wymagane serwery, zależności oraz sposób uruchamiania środowiska lokalnego. Wyniki zapisałem jako dokumentację Markdown w osobnym repozytorium, aby wersjonować ją tak samo jak kod i udostępniać jako wspólny kontekst dla ludzi oraz agentów.

Dokumentacja miała przejść praktyczny test: na jej podstawie agent powinien umieć przeprowadzić inżyniera od pustego środowiska do działającej aplikacji. Kiedy później powtórzyłem konfigurację na innym komputerze, zajęła około 40 minut zamiast ośmiu godzin ręcznego rozpoznawania zależności. Dokumentacja była gotowa dopiero wtedy, gdy proces dało się odtworzyć.

Wspólna pamięć dla programistów i agentów

Proces RPI utrzymywał również wersjonowaną bazę wiedzy w katalogu thoughts/shared powiązanym z repozytorium. Analizy, plany techniczne, notatki i materiały do przekazania pracy przygotowane podczas jednego zadania nie znikały wraz z zakończeniem sesji agenta. Były zapisywane i udostępniane pozostałym programistom.

Zanim agent rozpoczął analizę funkcji od zera, przeszukiwał wspólny kontekst pod kątem wcześniejszych opracowań tego samego obszaru. Jeżeli inny programista opisał już zachowanie systemu, ograniczenia albo plan implementacji, kolejny agent mógł wykorzystać tę pracę i sprawdzić jedynie to, co się zmieniło. Ograniczało to powtarzanie analizy kodu, oszczędzało ograniczony budżet tokenów i dawało zespołowi wspólne źródło historycznego kontekstu.

Komenda implement_plan domykała ten proces. Odczytywała zatwierdzony plan z thoughts/shared/plans, realizowała jego etapy i kryteria sukcesu, zapisywała postęp w tym samym dokumencie oraz zatrzymywała się przed krokami wymagającymi weryfikacji człowieka. Wiedza nie była więc wyłącznie archiwizowana; pozostawała połączona z implementacją i kontrolą rezultatu.

Importer: od plików wejściowych do produkcji w trzy tygodnie

Jednym z pierwszych dużych zadań był importer danych. Dane wyeksportowane z innego systemu trafiały do nas jako pliki CSV i JSON. Trzeba było zrozumieć oba formaty, opisać docelową strukturę i przygotować jawne mapowanie, które można było sprawdzić przed zapisem.

Agenci pomagali analizować pliki oraz przygotowywać mapowanie i logikę importu, ale nie podejmowali decyzji o poprawności rzeczywistych danych. Osoba z odpowiednimi uprawnieniami wykonywała prawdziwy import najpierw na środowisku stagingowym, a następnie na produkcji. Rozdzielenie implementacji od walidacji danych pozwoliło ukończyć produkcyjny importer w trzy tygodnie bez przekazywania agentom ostatecznej odpowiedzialności.

Dwie osobne role: implementacja i adwersaryjna recenzja

Linear był jednym źródłem zadań i priorytetów, które realizowałem po kolei. Proces opierał się na dwóch komendach Claude'a z otwartego pluginu RPI dostępnego w claude-ruby-marketplace: feature i review-pr.

Komenda feature nie zaczynała od pisania kodu. Najpierw pobierała wymagania i kryteria akceptacji, przeszukiwała thoughts/shared pod kątem pracy opisanej wcześniej przez innych programistów, a następnie uzupełniała brakujący kontekst historyczny, podobne implementacje i analizę obszaru zmiany. Dopiero na tej podstawie powstawały plan, kod i testy. Po przejściu kontroli jakości oraz CI uruchamiałem osobny self-review przed przekazaniem PR-a człowiekowi.

Self-review był drugim przebiegiem o innym celu. Sprawdzał zgodność z zadaniem, testy, ryzyka bezpieczeństwa, wydajność i wzorce obecne w aplikacji. W praktyce wykrywał między innymi zapytania N+1, pominięte wymagania oraz rozwiązania odbiegające od istniejącej architektury. Agent zgłaszał problemy, ale to ja oceniałem ich znaczenie i decydowałem, co poprawić przed recenzją człowieka.

Każda nowa funkcja i każdy pull request musiały zapewnić co najmniej 80% pokrycia zmienianego kodu. Próg był częścią instrukcji przekazywanych agentom i jedną z bramek przed recenzją. Od stycznia do maja 2026 przygotowałem i prowadziłem około 150 pull requestów. Agenci wspierali analizę, implementację i kontrolę, ale autorstwo oraz odpowiedzialność za zmiany pozostawały po mojej stronie.

Wyniki

Projekt był zbyt duży, aby zakończyć pełną modernizację w tym okresie. Rozwijałem nowe funkcje, refaktoryzowałem znaczną część starszego kodu i stopniowo przenosiłem wybrane obszary do nowszej architektury. Najważniejszym rezultatem nie była obietnica zakończonego przepisywania, lecz powtarzalny sposób bezpieczniejszej pracy z systemem, którego początkowo trudno było nawet uruchomić.

Co możesz zastosować u siebie

• Dokumentacja na start: zbuduj wspólny, wersjonowany kontekst dla inżynierów i agentów przed wdrożeniem pierwszej zmiany.
• Małe, częste PR-y: utrzymuj PR-y na tyle małe, aby można je było niezależnie przejrzeć i wdrożyć.
• AI jako recenzent: oddziel implementację od self-review i zlecaj agentowi szukanie luk przed przeglądem przez człowieka.
• Pokrycie jako bramka: egzekwuj minimalne pokrycie zmienianego kodu przy każdym PR-ze i oceniaj również jakość testów.
• Jedno źródło priorytetów: trzymaj zadania i kryteria akceptacji w jednym miejscu, aby każda iteracja zaczynała się od uzgodnionego zakresu.