Skillek, nem promptok: így viszik a kódoló ügynökeim a hibát a bejelentéstől a pull requestig

Egy ideig újra és újra ugyanazt magyaráztam el a kódoló ügynökeimnek. Előbb reprodukáld a hibát. Hozd létre a jegyet, mielőtt a kódhoz nyúlsz. Ne ugord át a bukó tesztet. Ne mondd, hogy zöld a CI, ha meg sem nézted. Minden új munkamenet nulláról indult.

Úgyhogy abbahagytam a promptok írását, és skilleket kezdtem írni. Mára nagyjából húsz van belőlük, és a „javítsd ki ezt a hibát” kérésből megismételhető folyamatot csinálnak, ami egy átnézett pull requesttel zárul. Ez a cikk arról szól, hogyan vannak szervezve, hogyan néz ki a fő folyamat, és milyen szabályoktól lesz megbízható az eredmény.

Mi az a skill, és hol vannak az enyéim

A skill egy Markdown-fájl: van neve, egy rövid leírása arról, mikor kell használni, benne vannak a lépések és a megszeghetetlen szabályok. Az ügynök elolvassa a leírásokat, és betölti a skillt, ha a feladat illik hozzá – ahogy egy fejlesztő is előveszi az ellenőrzőlistát.

Az enyéim egy központi mappában vannak, a ~/.agents/skills alatt. Innen szinkronizálódnak a Claude Code-ba és az opencode-ba, és a Codex is ezeket használja. Egy példányt szerkesztek, és három ügynök ugyanúgy viselkedik.

A legértékesebb rész nem a lépések, hanem a tanulságok. Ha valami elromlik, a megoldás bekerül a skillbe, hogy soha többé ne romoljon el. Két példa:

• A Jira API bizonyos mezőkben magyarázat nélkül, egy puszta HTTP 400-zal utasítja el a wiki-jelölést. A jegykezelő skill most azt mondja: ADF-ben (az Atlassian dokumentumformátumában) küldd a tartalmat, aztán kereséssel ellenőrizd a jegyet.
• A többsoros commitüzenetek elromlottak zsh-ban, és a fő ágra nyitott PR-eken nem futott CI. Mindkettő le van írva, így az ügynök megkerüli őket ahelyett, hogy újra felfedezné.

A fő folyamat: a hibabejelentéstől a pull requestig

A legfontosabb skill egy PHP-s B2B webshop éles hibáját viszi végig az első bejelentéstől a megnyitott pull requestig. Fázisokban halad, és az ügynök minden fázis után frissít egy teendőlistát, hogy lássam, hol tart.

1. Reprodukálás valós adatokkal. Duplikátumok keresése a jegykezelőben, a projekt ügynököknek szóló jegyzeteinek elolvasása, és a hiba reprodukálása helyben, az adatok szinkronizált másolatán. Belépés az érintett felhasználóként, és az oldal vizsgálata egy valódi böngészőben. A fázis egy bizonyítéktáblázattal és egy egymondatos kiváltó okkal zárul – mielőtt bármilyen kód megváltozna.
2. Először a jegy. A Jira-jegy létrehozása a csapat formátumában, és végigléptetése a munkafolyamaton, hogy a munka az elejétől látható legyen.
3. Ág. Jegyenként egy hotfix ág, a jegyről elnevezve.
4. A lehető legkisebb javítás a kiváltó oknál, unit tesztekkel a normál esetre, a hibakezelésre és a szélsőséges esetekre (hiányzó termék, üres lekérdezés).
5. Egy end-to-end regressziós teszt, aminek a javítás nélkül el kell buknia. A Playwright-teszt a javítással zöld. Aztán az ügynök csak a javítást vonja vissza, és a tesztnek el kell buknia, megmutatva a hibás adatot. Aztán a javítás visszakerül, és a teszt újra zöld. Az a teszt, ami így is, úgy is átmegy, semmit sem bizonyít.
6. A kapu: minden commit előtt lefut a teljes unit teszt csomag és a statikus elemzés (PHPUnit és PHPStan). Utána commit, push és a PR megnyitása.
7. Jelentés: a PR linkje és a bizonyítékok kommentként a jegyre kerülnek, végül egy összefoglaló nekem.

Bizonyítsd adatokkal a kiváltó okot, mielőtt megírod a javítást. Bizonyítsd egy visszavonással a tesztet, mielőtt megbízol benne.

Kis skillek, amelyek összeépülnek

A fő folyamat nem mindent maga csinál. Kisebb skilleket hív meg, amelyek önmagukban is működnek:

• Jegy létrehozása: a csapat kétnyelvű formátuma, az elfogadási feltételek a megfelelő mezőben, utólag ellenőrizve.
• Böngészős építőkockák: belépés az admin felületre, belépés egy webshop-felhasználó nevében, termék kosárba tétele, a pénztár végigjárása. Mindegyik rögzíti a megírásakor talált csapdákat: két egyforma űrlap közül melyik a jó, és melyik osztályváltozás jelenti azt, hogy „a gomb kész”.
• Commit előtti kapu: a tesztadatbázisok előkészítése, a teljes csomag és a statikus elemzés futtatása, és pontos számok jelentése.
• Pull request létrehozása: fix sablon (jegy link, leírás, tesztelés, hogyan teszteld, telepítési megjegyzések), csak git és gh használatával. Jegyszám nélkül nincs PR.

A PR után: a review-kör

Egy második folyamat veszi át, amikor a reviewerek kommenteltek:

1. A PR összes review-kommentjének összegyűjtése a GitHub API-n keresztül.
2. Javítás, majd minden szál ellenőrzése és megjelölése: javítva, részben, nyitott vagy nem releváns.
3. A tesztek és a statikus elemzés újrafuttatása, és ismétlés.
4. Három eredménytelen kör után leállás, és átadás egy embernek, ahelyett hogy körbe-körbe járna.
5. Commit, push, és a CI-ellenőrzések figyelése, amíg zöldek nem lesznek.
6. Válasz minden szálra, megnevezve a commitot, amelyik megoldotta.

Mielőtt bármi commitolásra vagy posztolásra kerül, az ügynök e-mail-címeket és más személyes adatokat keres benne.

A hibajavításon túl

• Műszaki tervezés: egy GitHub issue-ból backend megvalósítási terv készül, mielőtt bárki kódolna. A szabály: soha ne egyetlen megoldást javasolj. Az ügynök két-három lehetőséget kínál előnyökkel és hátrányokkal, a fejlesztő dönt, és az eredmény egy tervfájl. Semmi sem kerül commitra.
• Teljesítményprofilozás: egy backend útvonal mérése több futáson át (p50/p95/p99 futásidő, CPU, csúcsmemória, SQL-lekérdezések száma és ideje). Aztán egy változtatás, újramérés, visszavonás. Egyszerre mindig csak egy változtatás, és a benchmark szkriptek soha nem kerülnek commitra. A végén egy előtte-utána táblázat áll.
• Kódreview: a helyi változtatások átnézése push előtt, vagy valaki más PR-jáé, egy ellenőrzőlista alapján: helyesség, biztonság, konvenciók, teljesítmény, tesztek és dokumentáció.

A szabályok, amelyek mindenhol visszatérnek

Az összes skillt végignézve ugyanazok a szabályok jönnek elő. Ezek fontosabbak bármelyik lépésnél:

• Soha ne találj ki tényeket. Nincsenek kitalált CI-eredmények, tesztfutások, jegyállapotok vagy telepítések. Ha valami nem futott le, a jelentésben az áll, hogy „nem futott”, és hogy miért. Attól, hogy van PR, még nincs telepítve semmi.
• A teszteket soha nem ugorjuk át, nem gyengítjük és nem töröljük. A már meglévő hibákat bizonyítékokkal választjuk el az újaktól. Egy blokkolt vagy részleges futás nem zöld futás.
• Mindent, ami nyilvános vagy visszafordíthatatlan, ember hagy jóvá. Ugyanez a határ a munkán kívül is: a hirdetésfeladó böngészős skilljeim kitöltik az űrlapot, aztán megállnak, és rákérdeznek, mielőtt a „Közzététel” gombra nyomnának.
• A hitelesítő adatok csak a környezetből jönnek (például gh auth). Hitelesítő fájlokat soha nem olvasunk, tokent soha nem írunk ki.

Az eszközök alatta

• Egy saját írású Jira MCP szerver 20 eszközzel: jegyek keresése, létrehozása, módosítása és léptetése, kommentek, csatolmányok, epicek, valamint tesztesetek és tesztfutások.
• Playwright MCP, ami egy valódi böngészőt vezérel a hibák reprodukálásához és a folyamatok végigjárásához.
• Egyszerű parancssori eszközök, főleg git és gh, és a projekt saját teszteszközei.

Ha el akarod kezdeni

1. Azzal a folyamattal kezdd, amit a leggyakrabban magyarázol el. Az lesz az első skilled.
2. A szabályokat szabályként írd le, ne reményként. A „soha ne ugord át a teszteket” a fájlba való, nem a fejedbe.
3. Az ügynök bizonyítson. Bizonyítéktáblázatok, pontos tesztszámok, egy teszt, ami a javítás nélkül elbukik.
4. Minden meglepetésből egy sor lesz egy skillben. Így lesz jobb a folyamat, nem csak hosszabb.
5. Tarts egy központi példányt, és szinkronizáld minden ügynökbe, amit használsz.

Ha valami hasonlón dolgozol, vagy szeretnéd, hogy a csapatodban is így működjön, nézd meg az AI fejlesztés és MCP szerverek oldalt. Ha pedig inkább azt látnád, mit építek szórakozásból, az oldalon van egy cikk a többjátékos vitorlázós játékról is.