Ugrás a tartalomra

Két ügynök, egy repó, és egy GitHub issue-tábla, ami összetartja az egészet

Hogyan futtattam több kódoló ügynököt párhuzamosan ugyanazon a kódbázison merge-konfliktusok és félbehagyott branchek nélkül, a GitHub Issues munkatáblaként, egy egyszerű fájltulajdonlási szabállyal és egy emberrel a merge-kapunál.

Aierizer Samuel6 perc olvasás
Illusztráció egy issue-tábláról teendő, folyamatban, átnézés alatt és blokkolt oszlopokkal; minden feladaton a prioritása és a hozzárendelt AI-modell címkéje

Volt egy webalkalmazásom egy listányi problémával. A kódellenőrzések a szokásos vegyes képet mutatták: néhány biztonsági rés, pár lassú lekérdezés, egy rakás következetlen elnevezés és az a fajta holt kód, amit mindenki kerülget. Semmi különös. Csak több annál, mint amit kézzel akartam végigcsinálni, és pont az a fajta munka, amit könnyű elkezdeni és nehéz befejezni.

Rá akartam engedni pár ügynököt. Az aggodalom kézenfekvő volt: ha néhány ügynököt ráengedsz ugyanarra a kódbázisra, konfliktusok, félbehagyott branchek lesznek, és több bot magabiztosan írja át ugyanazt a fájlt ellentétes irányokba. Pont az a „azt hittem, több AI megoldja a problémát” helyzet, amiből később csak több gond lesz. Ezért mielőtt egy sor kódot írtam volna, egy délutánt arra szántam, amit általában kihagynak: hogyan hangoljuk össze a munkát, az egész folyamatot, nem arra, hogyan végezzük el.

Leírom, hogyan raktam össze. Nem keretrendszer, de elég jól működött ahhoz, hogy érdemes legyen leírni.

A munkatábla egyszerűen a GitHub Issues

Elsőként úgy döntöttem, hogy nem építek orchesztrátort. Csábító megírni egy ütemezőt, ami feladatokat oszt ki, állapotot követ és ügynököket indít. Egy behatárolt rendbetételnél ez önálló projekt, és tovább tartott volna, mint amennyit ért volna.

Ehelyett az igazság forrása a GitHub Issues. Egy issue munkaegységenként. Egy kis címkekészlet végzi az összehangolást:

  • prioritás (p0-tól p3-ig): mi a tényleg sürgős
  • állapot (todo, wip, review, blocked): a folyamat melyik szakaszában jár
  • modell (opus, sonnet, glm): melyik ügynök vegye fel
  • sáv (fix, feature): mennyire nehéz folyamat kell hozzá

Egy feladat akkor vehető fel, ha todo állapotban van, a függőségei le vannak zárva, és egyetlen nyitott pull request sem érinti a fájljait. Ennyi a szabály. Nincs szerver, ami figyeli a táblát és kiosztja a feladatokat, mert nincs is rá szükség.

A munka statikus térképe (melyik egység melyik fájlt birtokolja, mi mitől függ) egy egyszerű markdown fájlban él a repóban. Az aktuális állapot a GitHubon van. Ez a két dolog szétválasztása többet számított, mint gondoltam. A térkép nem változik munka közben; a tábla igen.

Az egyetlen szabály, ami biztonságossá teszi a párhuzamosságot

Minden más egyetlen szabályon múlik: minden forrásfájlt egyszerre legfeljebb egy nyitott pull request birtokol.

Ha két ügynök sosem nyúl ugyanahhoz a fájlhoz, nem tudnak konfliktusba kerülni, és tetszőleges sorrendben átnézhetem a PR-jeiket. Így az előzetes munka az volt, hogy a problémalistát olyan egységekre vágtam, amelyek nem fednek át fájlokban. A tömeges törlés controllereinek biztonsági javítása egy egység. Az események jogosultságkezelése egy másik. A keresőszolgáltatás egy harmadik. Mindegyik megnevezi a pontos fájlokat, amelyekhez hozzányúlhat, és ellenőriztem, hogy ezek a halmazok ne metsszék egymást, mielőtt bármit párhuzamosan futtattam volna.

Az eredmény egy függőségi gráf. Egy átnevezést elsőként kellett integrálni, mert olyan metódusneveket változtatott meg, amelyeket a kódbázis fele hívott, így minden más mögötte várt. Ezután egy sereg egymástól független javítás egyszerre futhatott. A gráf megrajzolása talán húsz percbe telt, és megmentett minden „miért van tele konfliktussal ez a branch“ beszélgetéstől.

Persze, ennek is vannak korlátai, de engem többnyire nem zavartak. Ha úgy látod, hogy nem lesz belőle nagy káosz, a szabályoktól is el lehet térni. Nem érdemes felesleges szabályokkal felduzzasztani a munkát; csak azokat tartsd be, amelyek segítenek.

Én a Claude Code-ot és az OpenCode-ot használtam

A két eszköz sosem beszél egymással, és ez szándékos.

A Claude Code-ot ott használtam, ahol drága tévedni: a jogosultsági rések és az adatvesztéses hibák javítására. Az OpenCode-ot a kis tétű csiszolásra: néhány keresési joker karakter escape-elésére, halott cache-kód törlésére, időbélyegek egységesítésére. Az útválasztás csak egy címke az issue-n. Claude nem tud OpenCode-ot indítani, OpenCode sem tud Claude-ot, és nem is akartam, hogy tudjanak. Mindkettő ugyanazokat az issue-kat olvassa, ugyanazt az életciklust követi, és ugyanabba a repóba nyit pull requestet.

Minden feladat a saját Git worktree-jében fut, saját tesztadatbázissal. Így két vagy több ügynök egyszerre is futtathatja a teljes tesztkészletet anélkül, hogy kárt tennének egymás tesztadataiban. A worktree-k a Git részei, és nagyon egyszerű velük dolgozni.

Az egyes feladatok életciklusa unalmas, és ez jó, mert kiszámítható. Mindig ugyanazt a folyamatot követjük: felvesszük az issue-t, új branchet nyitunk, elolvassuk a kódot, és írunk egy bukó tesztet, ami a helyes viselkedést ellenőrzi. Aztán javítjuk, refaktorálunk, futtatjuk a lintert és a biztonsági szkennert, helyben lefuttatjuk a teljes CI-t, nyitunk egy pull requestet, az issue-t pedig review állapotba tesszük. Aztán STOP! Az ügynök nem merge-el.

Az emberek mindig hazudnak, néha a tesztek is (HouseMD)

A leghasznosabb elv persze az, hogy attól, hogy minden teszt sikeres, még nem biztos, hogy jó a kód. Főleg, ha a teszteket generálták! Több biztonsági hibának végig zöld tesztjei voltak. Előfordul, hogy a tesztek a hibás viselkedést kódolják, és azt állítják, hogy a törlés sikerült, anélkül, hogy megvizsgálnák, joga volt-e hozzá annak, aki törölt. Ezért az új tesztnek először el kell buknia, mégpedig azért, mert a régi működés volt hibás. Ha nem tudod elérni, hogy elbukjon, még nem érted a hibát.

A folyamat olyan dolgokat is felszínre hozott, amelyeknek semmi közük nem volt a javításokhoz, viszont az infrastruktúrához igen. A lefedettségi kapu be volt állítva, de sosem érvényesítették, így az első rendes futás olyan fájlokon bukott el, amelyeket hónapok óta senki nem tesztelt. A biztonsági szkenner wrapper scriptje kikényszerített egy „ellenőrizd, van-e újabb verzió” kapcsolót, amitől a CI azért bukott el, mert megjelent fent egy javítókiadás, nem azért, mert bármit talált volna.

A végén szeretem én kézben tartani a dolgokat

Minden pull requestet én nézek át és merge-elek. Tesztelem őket, átnézem, mi maradhatott ki, és kijavítom a közben becsúszott hibákat. Ez az egész tudatos felső korlátja. A párhuzamosság azon túl már nem segít, amit át tudok nézni. A végtelen sok ügynök csak hosszabb PR-sort jelent, ami rám vár. Ezért egyszerre inkább két-három ügynököt futtatok, nem tízet. Nincs branch protection abban a felállásban, amit használok, úgyhogy a merge-kapu szó szerint én vagyok: nem merge-elek semmit, ami piros vagy átnézetlen. Kiderült, hogy ez nekem megfelel. A folyamat célja nem az, hogy engem kiváltson, hanem hogy amikor hozzám kerül a munka, már tesztelve, átvizsgálva és olyan fájlokra korlátozva legyen, amelyeket egy ültő helyemben át tudok nézni.

Egy apróság: öt-tíz vagy még több ügynök egyszerre nagyon gyorsan elégetheti a tokenkeretedet. Ha helyben futtatod őket, a RAM-ot is meg fogják izzasztani, főleg ha nagyjából egyszerre jutnak el a CI-ig, és nagy a tesztkészlet. Felhőben is futtathatod őket, de az is pénzbe kerül, szóval helyzettől függ. Nekem ez így pont megfelelt. Ezzel pedig el is jutottunk az utolsó ponthoz.

Mennyibe került

Alig valamibe a modellhívásokon túl. A GitHub Issues, a címkék és a pull requestek ingyenesek. A gh CLI már fent volt. A Git worktree-k a Git részei. A tesztfuttató, a linter és a biztonsági szkenner már be volt drótozva a projektbe. Az egyetlen új költség a tokenek, és az útválasztás a drága modellt arra a munkára tartja, ami megéri, míg az olcsóbb elvégzi a takarítást és az egyszerűbb feladatokat.

Röviden: talán érdemes még a munka előtt eldönteni, melyik fájl melyik pull requesthez tartozik, az állapotot pedig olyan helyen vezetni, amit mi és az ügynökök is elérnek. Maradjunk benne a folyamatban legalább a végéig. Kódot íratni az ügynökökkel könnyű. Megnyitod a projektet, elindítod a választott ügynököt, és már kész is. Az összehangolásuk és az, hogy a munka karbantartható és jó minőségű maradjon, már gondolkodást igényel. És egyelőre még mi végezzük ezt a munkát.

Van egy elmaradása, amire sosem jut idő?

Egy elöregedett kódbázis rendbetétele, egy biztonsági és takarítási lista lezárása, vagy elköltözés egy olyan platformról, ami lassítja. Pontosan ez az a munka, amiben segítek a kis- és középvállalkozásoknak. Őszintén felmérem, végig tájékoztatom, és csak azt vállalom el, amit tényleg jól meg tudok csinálni.

Meséljen a projektjéről