Jak uruchamiać agentów kodujących równolegle na git worktrees

TL;DR: Jedna gigantyczna sesja agenta, która buduje całą funkcję, dryfuje. Kontekst zapełnia się niedokończonymi wątkami, model gubi fabułę, a drugą połowę sesji spędzasz na ponownym tłumaczeniu pierwszej. Alternatywa, przy której zostałem, to wzorzec orkiestratora. Jedna sesja planuje i dzieli funkcję na trzy do pięciu równoległych podzadań o niskim ryzyku konfliktu, z kontraktami między nimi ustalonymi z góry. Każde podzadanie działa w osobnym git worktree: odizolowane, z fizycznie wyłączonym pushem i bez dostępu do bazy danych. Na koniec sesja integracyjna scala branche w jedną działającą funkcję i przepuszcza ją przez testy end-to-end. Całość stoi albo pada na jakości podziału.

Pętla

Schemat to najpierw rozproszenie (fan-out), potem scalenie (fan-in), i tak funkcja po funkcji.

Podział. Sesja orkiestratora, za moją zgodą, rozbija funkcję na N równoległych podzadań i definiuje styki między nimi, zanim powstanie jakakolwiek linijka kodu. To krok, który decyduje o wszystkim, i jeszcze do niego wrócę, bo od jego jakości zależy, czy dalej będzie łatwo, czy boleśnie.

Fan-out. Każde podzadanie trafia do osobnej, odizolowanej sesji na osobnym worktree i pracuje do końca, bez zatrzymywania się na pytania. Sesje działają równolegle. Żadna nie może zrobić pusha i żadna nie ma dostępu do prawdziwej bazy danych.

Fan-in. Kiedy wszystkie podzadania są gotowe, osobna sesja integracyjna scala branche w jedną działającą funkcję: łączy styki, skleja UI i uruchamia testy end-to-end, gdy już ręcznie postawię aplikacje.

Powtórka. Scal jedną falę w całości, zanim wyślesz następną. Nakładające się fale to prosta droga z powrotem do piekła merge'ów, którego chciałeś uniknąć.

Prawdziwą umiejętnością jest podział

Wszystko, co dobre w tym wzorcu, bierze się z rozłącznej pracy z jasnymi kontraktami. Wszystko, co złe, bierze się z nakładania. Dwa podzadania edytujące te same pliki to piekło merge'ów. Dwa podzadania piszące tę samą schemę to gwarantowany konflikt. Dlatego zanim cokolwiek wyślę, orkiestrator rysuje mapę konfliktów: które repozytorium, które pliki i co jest wspólne (teksty tłumaczeń, schema, wspólne typy).

Trzy zasady trzymają tę mapę w porządku. Zdefiniuj kontrakt z góry. Styk pozwala później spotkać się kawałkom budowanym niezależnie. Zależny kawałek buduje się na uzgodnionym kontrakcie plus mocku, a prawdziwe połączenie powstaje dopiero przy integracji. Panel admina buduje się na kształcie endpointu, którego jeszcze nie ma, i oba spotykają się dopiero w fazie fan-in. Wspólny zasób ma dokładnie jednego właściciela. Schema bazy, wspólne typy: należą do jednego podzadania, a wszyscy inni budują na kontrakcie. Nigdy dwa podzadania nie piszą tej samej schemy. Trzy do pięciu kawałków to optimum. Powyżej tej liczby dług przy scalaniu i wysiłek potrzebny, żeby trzymać całość w głowie, zjadają zyski. Jeśli funkcja chce ośmiu kawałków, to znaczy, że chce dwóch fal po cztery.

Dobrze zrobiony podział sprawia, że integracja staje się lekka. Lekkiej integracji nie osiągasz sprytem w momencie scalania. Kupujesz ją, ograniczając nakładanie się zadań już przy podziale. Praca przesuwa się wcześniej, tam, gdzie jest tania.

Izolacja jako gwarancja, a nie obietnica

Równolegli agenci edytujący kod są bezpieczni tylko wtedy, gdy naprawdę nie mogą wejść sobie w drogę ani dotknąć niczego prawdziwego. Git worktrees dają każdej sesji własną kopię roboczą repo na własnym branchu i to jest fundament:

# każde podzadanie dostaje własną kopię roboczą na własnym branchu
git -C <repo> worktree add ../feat-x -b feat/x develop
cd ../feat-x && npm install   # node_modules nie są współdzielone

# push w tym worktree staje się fizycznie niemożliwy
git -C ../feat-x remote set-url --push origin DISABLED-no-push

Do tego trzy właściwości zamieniają izolację z nadziei w gwarancję. Push jest fizycznie wyłączony, bo URL do pusha wskazuje na martwy adres, więc próba pusha po prostu się nie udaje. Wraca dopiero po zatwierdzeniu merge'a. Plik środowiskowy jest w gitignore, więc nigdy nie trafia do worktree. To znaczy, że agent nie ma żadnych danych dostępowych i nie może dotknąć żadnej bazy. To twarda gwarancja ze strony systemu plików, a nie obietnica zachowania ze strony modelu. I wreszcie osobny katalog to osobny cache buildu, więc równoległa sesja nie depcze serwera deweloperskiego działającego na twojej głównej kopii roboczej.

Bramki, które się nie przesuwają

Automatyzacja jedzie po stałych szynach. Zastosowanie migracji schemy, merge do głównego brancha, push i deploy na produkcję należą do mnie, bez względu na to, jak skonfigurowana jest automatyzacja. Sesja integracyjna scala lokalnie, nie robi pusha i nie stosuje migracji. Kiedy migracja jest potrzebna, wypisuje komendę, którą uruchamiam sam ze swojej maszyny. Najgorszy scenariusz, na jaki pozwala ten projekt, to branch, którego nigdy nie zmerguję. I dokładnie taki najgorszy scenariusz chcesz mieć.

Dlaczego to wygrywa z jedną dużą sesją

Z dwóch powodów, które się sumują. Po pierwsze przepustowość: kilka sprawnych agentów budujących naprawdę niezależne kawałki naraz to poziom równoległości, jakiego samodzielny twórca nigdy nie miał. Przy planie abonamentowym ich jednoczesne uruchomienie nic dodatkowo nie kosztuje. Po drugie, i to mniej oczywiste, każda sesja zostaje chuda. Skupiona sesja nad jednym podzadaniem trzyma czysty kontekst z dużą ilością sygnału, a właśnie w takich warunkach te modele pracują najlepiej. Przeciwieństwem jest jedna rozlana sesja, której kontekst powoli zapełnia się szumem, aż jakość po cichu spada. Wzorzec orkiestratora jest nie tylko szybszy. Sprawia, że każdy uczestnik, łącznie ze mną, pracuje w danym momencie nad jedną, jasno ograniczoną rzeczą.

Co warto przenieść do siebie

• Dziel pod kątem rozłączności, nie równowagi. To małe nakładanie się plików i zasobów sprawia, że równoległa praca czysto się scala. Równy rozmiar kawałków nie ma znaczenia.
• Uzgodnij kontrakty przed wysłaniem zadań. Zależne kawałki budują się na kontrakcie i mocku, a prawdziwe połączenie czeka na integrację.
• Jeden właściciel dla każdego wspólnego zasobu. Dwie sesje piszące tę samą schemę to konflikt, który sam sobie wcześniej zaplanowałeś.
• Niech izolacja będzie fizyczna. Wyłącz push, trzymaj sekrety poza worktree. Gwarancja ze strony systemu plików jest lepsza niż obietnica modelu.
• Nieodwracalne bramki zostają w rękach człowieka. Migracje, merge do głównego brancha i deploye należą do ciebie. Najgorszym scenariuszem staje się branch, którego nigdy nie zmergujesz.
• Scal falę, zanim zaczniesz następną. Nakładające się fale odbudowują piekło merge'ów, przed którym ten wzorzec ma chronić.