Harness engineering: guide-ek és szenzorok a mergeelhető agentikus PR-ekhez

A harness engineering az a munka, amellyel mindent felépítünk a kódoló ügynök modellje köré (utasítások, eszközök, tesztek, linterek, review-k), hogy amit az ügynök előállít, már azelőtt helyes és karbantartható legyen, hogy egy ember megnézze. A modell írja a kódot. A harness dönti el, hogy a kód jó-e, és szól az ügynöknek, ha nem.

Ez a cikk Birgitta Böckeler guide- és szenzorkeretét használja, aztán átmegy a gyakorlatra: melyik ellenőrzést hol futtasd, hogyan működik a piros/zöld TDD ügynökkel, hogyan ellenőrzi a mutációs tesztelés az ügynök által írt teszteket, és miért marad a viselkedés a leggyengébb pont. A végén egy ellenőrzőlista arról, mitől lesz egy ügynök pull requestje mergeelhető.

Mi az a harness engineering?

A harness engineering a modell körüli környezetet tekinti tervezési tárgynak. Böckeler „Harness engineering for coding agent users” cikke (2026. április) így foglalja össze: „Agent = Model + Harness”.

Két harnesszt különböztet meg. Az egyik magával az ügynökkel száll ki – Claude Code, Codex vagy opencode: a system prompt, az eszközhurok, a sandbox. A másik nálad épül fel a saját kódbázisod körül: szabályfájlok, skillek, tesztparancsok, linterek, review lépések. Az elsőnél nem sok mindent tudsz változtatni. A második a tiéd, és innen jön a csapatok közötti minőségkülönbség nagy része.

Nem minden kódbázis fogékony egyformán a harnessre. Böckeler ezt harnessability-nek nevezi: egy „erősen tipizált nyelv természetesen type checkinget tart a szenzorai között”, és a világos modulfeltételek teszik lehetővé az architektúraszabályokat. Teszt és típus nélküli kódbázis nem ad semmit, amivel az ügynök összevethetné magát, így találgatnia kell.

Guide-ek és szenzorok: feedforward és feedback

A guide-ek még azelőtt terelik az ügynököt, hogy cselekedne; a szenzorok utána vizsgálják az eredményt, hogy az ügynök kijavíthassa magát. Mindkettőnek két fajtája van: computational (a CPU futtatja, determinisztikus) és inferential (egy modell futtatja, szemantikus, de valószínűségi).

Böckeler szavával a guide-ek „előre megjósolják az ügynök viselkedését, és arra törekednek, hogy mielőtt cselekedne, eltereljék”, a szenzorok pedig „utána, hogy az ügynök cselekedett, figyelnek, és segítenek neki önellenőrzésre”. A computational kontrollok „determinisztikusak és gyorsak, a CPU futtatja őket”: tesztek, linterek, típusellenőrzők. Az inferential kontrollok szemantikus elemzés és AI kódreview: lassabb, drágább és nem determinisztikus, de ki tudja értékelni azt is, amit egy linter nem.

Böckeler aszerint csoportosítja a harnesszeket, hogy mit védenek. A karbantarthatóság a legkifejlettebb: a computational szenzorok megbízhatóan elkapják a „duplikált kódot, a ciklomatikus komplexitást, a hiányzó tesztlefedettséget, az architektúra elcsúszását”. Az architektúraalkalmasság a teljesítményigényeket és a konvenciókat fedi le, fitness függvényekkel ellenőrizve. A viselkedés, vagyis hogy a szoftver azt teszi, amit kellene, a hézag, és erről szól a következő szakasz.

Hol futtassuk a szenzorokat?

A gyors szenzorok az ügynök hurokjában, minden módosítás után fussanak, a teljes kapu minden commit előtt, a lassúak pedig a CI-ban. Minél korábban szólal meg egy szenzor, annál olcsóbb a javítás: az ügynök ugyanabban a sessionben javítja, mielőtt bármelyik reviewer meglátná.

Böckeler ezt úgy nevezi: a minőséget balra kell tartani. Gyors linterek a commit előtt, szélesebb review utána, drága elemzések, mint a mutációs tesztelés, az integráció után. Egyik folytatásában, „Maintainability sensors for coding agents” (2026. május) az ESLintet, a dependency-cruisert, a Semgrep-et, a coverage-ot, a Strykert és a GitLeakset próbálta ki szenzorként, és megállapította, hogy a számítási eszközök fájlszinten működnek a legjobban, a modellalapú review viszont a modulokon átívelő kérdéseknél. A gyakorlati problémát is megemlíti: „sok, sok alkalommal meg kellett kérdeznem az ügynököket, miért nem futtatták le a szenzorellenőrzést”.

Ez a mondat már önmagában a kikényszerítésért szól. Egy szabály egy Markdown-fájlban guide: az ügynök követi, vagy nem. A Claude Code memóriadokumentációja ugyanezt mondja a saját szabályfájljairól: a Claude „kontextusként, nem kikényszerített konfigurációként” kezeli őket, és ha egy műveletet a modell döntésétől függetlenül akarsz letiltani, ahhoz hook kell. A saját kapum szándékosan unalmas: minden commit előtt lefut a teljes PHPUnit csomag és a PHPStan, és egy kihagyott vagy részleges futást pontosan így jelzek, soha nem zöldként.

Piros/zöld TDD kódoló ügynökökkel

A piros/zöld TDD azt jelenti, hogy az ügynök megír egy tesztet, lefuttatja, és megnézi, hogyan bukik el, aztán megírja a kódot, és megnézi, hogyan megy át. A bukó futás a lényeg: bizonyítja, hogy a teszt tényleg gyakorolja az új viselkedést.

Simon Willison a saját „Agentic Engineering Patterns” útmutatójában rövid promptként sorolja fel, és megadja az okot: „Use red/green TDD”, mert „ha kihagyod ezt a lépést, már zölden átmenő tesztet építhetsz, így az új implementációdat se gyakorolod, se nem erősíted meg”. A hozzá tartozó „First run the tests” minta arra ösztönzi az ügynököt, hogy egy session elején kiderítse, hogyan fut a csomag, ami sokkal valószínűbbé teszi, hogy később is lefuttassa.

Hibajavításnál szigorúbb változatot használok. A regressziós tesztnek a javítással át kell mennie, el kell buknia, ha csak a javítást vonjuk vissza, és újra át kell mennie, ha visszakerül. A visszavonást maga az ügynök végzi, és mindkét futásról beszámol. Ez kiszűri azokat a teszteket, amelyek a rossz dolgot állítják, és olcsó: két extra tesztfutás. A körülötte futó folyamat leírása a hogyan használom az ügynökskilleket hibajavításra cikkben található.

Az Anthropic „Effective harnesses for long-running agents” cikke ugyanezt az egész projektekre is alkalmazza: egy feature-lista, amelyben minden feature "passes": false értékkel indul, sessionenként egy feature, és a szabály, hogy „elfogadhatatlan a teszteket törölni vagy szerkeszteni”. A piros állapot rögzítve van, mielőtt bármilyen kód létezne.

Mutációs tesztelés: az ügynök által írt tesztek ellenőrzése

A mutációs tesztelés kis változtatásokat eszközöl a termelési kódon, majd újrafuttatja a teszteket. Ha a tesztek továbbra is átmennek, nem vették észre a változást, és gyengébbek annál, mint amit a lefedettségi számuk sugall.

A Stryker így írja le: a mutánsok „automatikusan bekerülnek a termelési kódodba. Minden mutánsra lefuttatjuk a teszteket. Ha a teszteid elbuknak, a mutáns meghalt. Ha a teszteid átmentek, a mutáns túlélt.” A Stryker a JavaScriptet és a TypeScriptet, a C#-ot és a Scalát fedi le. PHP-ben az Infection Mutation Score Indicator (MSI) értéket jelent, és egy CI jobot egy küszöb alatt hibásra állíthat.

Ez annál fontosabb, minél több tesztet az ügynökök írnak. Egy ügynök, amelyet arra kértek, hogy „adjon teszteket”, könnyen magas sorlefedettséget ér el; hogy az assertionjei egy valódi hibát elkapnának-e, más kérdés. Böckeler ugyanezt állapítja meg: a lefedettség önmagában elrejti a gyenge teszteket, ezért a mutációs tesztelés akkor lesz fontos, ha a KI írja őket. A mutánsfuttatás egy egész kódbázison lassú, ezért szűkítsük a módosításra:

# CI step: mutate only the lines this PR touched (PHP, Infection)
git fetch --depth=1 origin $GITHUB_BASE_REF
infection --git-diff-lines --git-diff-base=origin/$GITHUB_BASE_REF --min-covered-msi=80
# 80 is an example threshold; start from your current score and raise it

Az életben maradt mutánsok egyben jó input az ügynöknek. Add vissza a listát azzal, hogy „ezek túlélték; egészítsd ki vagy szigorítsd az assertionjeiket, hogy megöljék őket, a termelési kód módosítása nélkül”, és a szenzor visszacsatoló hurká válik, amelyet az ügynök maga zárhat le.

A gyenge pont: viselkedési harnesszek, és mikor ne vigyük túl

A viselkedés az a terület, ahol a harnesszek a leggyengébbek, mert a szokásos viselkedésellenőrzés az a tesztcsomag, amelyet az ügynök írt egy specifikáció alapján, amit az ügynök olvasott. Böckeler ítélete erről: „nagyon sok bizalmat helyez az AI által generált tesztekbe, ami még nem elég”.

Három dolog segít, egyik sem ingyenes:

• Ember tulajdonában lévő elfogadási tesztek. Egy kis end-to-end tesztkészlet, amelyet egy ember írt vagy hagyott jóvá; az ügynök futtathatja, de nem szerkesztheti.
• Tesztek a valódi felületen át. Az Anthropic hosszú futású harnessze a böngészőautomatizálást találta döntőnek, hogy az ügynök „emberi felhasználóként” ellenőrizhesse a feature-öket. Én erre a Playwrightot használom.
• A teszt diffjének külön review-ja. Ha a kód és a tesztek együtt változnak, a reviewer először a teszteket olvassa.

A csere idő és zaj. Minden szenzor megnyújtja a hurkot, az inferential szenzorok pedig tokeneket és téves riasztásokat adnak hozzá. Az a review alügynök, amely PR-enként tíz stílusbeli apróságot jelez, mindenkit – embert és ügynököt – arra tanít, hogy hagyja figyelmen kívül. Ne építs harnesszt egy eldobható szkripthez. Építs olyat, amit karbantartanak, és hagyd, hogy valódi hibákból nőjön: ha egy ügynök-PR-t minden alkalommal egy embernek kell javítani, kérdezd meg, melyik guide vagy szenzor kapta volna el. Böckeler fenntartása is érvényes: az emberek ítélőképességet és felelősséget hoznak egy „implicit harness” formájában, az egy leírt harness pedig „csak egy bizonyos pontig tud elmenni”. Hogyan ne váljon az emberi review szűk keresztmetszetté, arról szól a KI-generált pull requestek review-zása cikk.

Harness engineering ellenőrzőlista

1. Írd meg a guide-eket: build- és tesztparancsok, konvenciók és tiltott minták az AGENTS.md-ben vagy a skillekben.
2. A gyors szenzorok fussanak a hurokban: típusellenőrző, linter és az érintett tesztek minden módosítás után.
3. Kényszerítsd ki a kaput hookokkal vagy CI-vel, ne egy promptbeli mondattal: teljes csomag és statikus elemzés minden commit előtt.
4. Követelj piros/zöldet: az ügynök mutassa meg a bukó futást a sikeres előtt; hibajavításnál a teszt elbukik, ha a javítást visszavonjuk.
5. Adj mutációs tesztelést a diffre, és az életben maradt mutánsokat vissza az ügynöknek.
6. Védd az ember tulajdonában lévő elfogadási teszteket; az ügynök futtathatja, nem szerkesztheti.
7. Tartsd tanácsadónak az inferential reviewt, és hangold be, amíg a kommentjei érdemesek lesznek.
8. Minden emberi javításból legyen guide vagy szenzor, hogy ugyanaz a hiba kétszer ne jusson el a review-ba.

Ha egy csapatnak állítasz be ilyen harnesszt, nézd meg az AI engineering oldalt.

Források

1. Birgitta Böckeler: Harness engineering for coding agent users (2026. április)
2. Birgitta Böckeler: Maintainability sensors for coding agents (2026. május)
3. Simon Willison: Agentic Engineering Patterns
4. Simon Willison: First run the tests
5. Anthropic: Effective harnesses for long-running agents (2025. november)
6. Claude Code dokumentáció: How Claude remembers your project
7. Stryker Mutator dokumentáció
8. Infection: command line options