Theo Valmis korábbi Radar-cikke, „Architectural Guardrails for AI-Generated Code”, azzal érvelt, hogy az AI-alapú kódgenerátoroknak szükségük van egy olyan rétegre, amely strukturált formában tartja az architektúrális döntéseket, előhozhatja a relevánsakat, beemeli az ügynök kontextusába kódírás előtt, és reprodukálható ellenőrzésekkel kikényszeríthet explicit megszorításokat. A tesztelés során két különbség vált világossá, amelyek korábban egybe voltak tömörítve: relevancia vs. hatáskör (authority), valamint irányelv (guidance) vs. kikényszerítés (enforcement).
Relevancia ≠ hatáskör
Valmis beszámolója szerint egy kontrollált tárolóban végzett feladatnál a projekt jelenlegi fázisában lokális JSON-alapú perzisztencia volt használatban, és egy aktív architekturális döntés kizárta a PostgreSQL-t, az ORM-eket és az adatbázis-migrációt a parancssori alkalmazásra. A kódügynöknek a tárolómodult kellett módosítania, így ez a döntés nem csupán általánosan releváns volt a perzisztencia témájában, hanem konkrét hatáskörrel bírt a módosítandó részen. A rekordot előhívták és a modell kontextusába helyezték mégis az ügynök PostgreSQL-t, ORM-et és migrációs útvonalat javasolt.
Ez nem retrieval-hiba volt: a döntés megtalálható és aktuális volt, de hiányzott egy alkalmazhatósági (applicability) jelzés, amely megmondta volna, hogy ez a döntés kifejezetten a szerkesztett komponensre vonatkozik, és nem csak egy további, releváns dokumentum a kontextusban.
Miért fontos a scope (hatáskör) és az autoritás megőrzése
A lekérdezés (retrieval) jó eszköz arra, hogy felszínre hozza azokat a döntési dokumentumokat, amelyek relevánsak lehetnek. Ma már sok megközelítés létezik: indexelt tárak, kapcsolt dokumentációk, döntési rekordok, szolgáltatáskatalógusok, szemantikus keresés és projektmemória. Ezek segítenek, de nem válaszolják meg automatikusan a kérdést: melyik dokumentumnak van tényleges hatásköre az adott kódmódosításra?
Egy repóban lehet például két perzisztencia-döntés: az egyik előírja a PostgreSQL használatát egy analytics-szolgáltatásnál, a másik lokális fájl-alapú tárolást rendel egy parancssori eszközhöz. Ha az ügynök a parancssori eszköz storage modulját szerkeszti, mindkét döntés magas ranket kaphat egy „persistence” lekérdezésre, de csak a lokális tárolásról szóló döntés alkalmazandó. Annak megállapításához, hogy melyik döntés kormányozza a változást, szükség van a scope, lifecycle, precedence és a korábbi döntéseket felülíró rekordok egyértelmű jelölésére.
Az architekturális információ gyakran szétszórt különböző dokumentumok között (régi design note, README, elfogadott ADR, platformstandard). Az emberek különbséget tudnak tenni közöttük autoritás szerint; a modellek csak akkor, ha a rendszer fenntartja ezt a hierarchiát. Ha ezeket a forrásokat egyetlen kontextusablakban egyesítik, az autoritás-signal elhalványulhat — azaz authority flattening történik.
Tudományos eredmények és párhuzamok
Egy 2026-os tanulmány, amelyet Su és munkatársai végeztek 109 open source repó 980 ADR-jét vizsgálva, hasonló határvonalra mutatott rá: a modellek erősek, ha a döntések explicitak és kódból kikövetkeztethetők, gyengébbek, ha a megfelelés a deployment konfigurációtól vagy szervezeti tudástól függ. A tanulmány a kód írása utáni megsértéseket értékelte, de az alapvető korlát hasonló: a megfelelő dokumentum megtalálása önmagában nem garantálja a helyes architekturális választ, ha az alkalmazhatóság vagy az autoritás implicit marad.
Kísérleti eredmények: relevancia vs. alkalmazhatóság
Valmis egy kisméretű kontrollkísérletet végzett hét kódolási feladattal, ugyanazzal az ügynökkel és modellkonfigurációval, két feltétellel ismételve: az egyikben az ügynök az architekturális útmutatás nélkül dolgozott, a másikban a döntési rekordokat megkapta a módosítás előtt. Független értékelők vizsgálták az első próbálkozásokat mind architekturális megfelelés, mind a kért munka tényleges teljesítése szempontjából.
Az eredmény: a guidance javította a viselkedést az architektúra-érzékeny feladatoknál — az első próbálkozásra történő megfelelés 6/15-ről 10/15-re nőtt, míg a feladatok sikeres teljesítése lényegében nem változott. Ugyanakkor a vezetett (guided) feltételben is voltak hibák: több autentikációs feladatnál az ügynök olyan további perzisztencia-munkákat valósított meg, amelyeket a feladat nem kért. Itt a döntés releváns volt és megtalálták, de nem volt elég információ arról, hogy a döntés hatásköre pontosan hol érvényes — az alkalmazhatóság hiánya lehetővé tette a feladat kiterjesztését.
Irányelv vs. blokk: mi könnyebb és mi szükséges
A korábbi modell determinisztikus kikényszerítést hangsúlyozta: ha a csapat explicit döntést hozott és a megsértés megítélhető megfigyelhető bizonyíték alapján, akkor a blokkoló döntést reprodukálható szabályból kell kiadni, nem a modell szubjektív ítéletéből. Valmis továbbra is ezt tartja helyesnek, de kiegészíti, hogy csak egy részhalmaza az architekturális döntéseknek alkalmas ilyen kezelhetőségre anélkül, hogy tévesen determinisztikusnak mutatná a megítélést.
Példák:
- "Do not introduce SQLAlchemy into this component" — viszonylag könnyen kifejezhető szabályként, egyszerű ellenőrizni és blokkolni.
- "Use the existing persistence abstraction correctly" — elsősorban architekturális jelentésű; a helyes implementáció a használt absztrakciótól, annak helyi alkalmazásától és a környező megszorításoktól függ. Ez inkább útmutatás, hacsak a csapat nem teszi konkréttá a bizonyítékot és a határokat.
Ha egy guardrail-réteg kizárólag blokkolásra épül, nagyon jó lesz abban, hogy „nem”-et mondjon. Hasznos architekturális irányításnak azonban mindkettőt kell tudnia: blokkolni a pontos megsértéseket és pozitív irányt adni olyan, értelmezést igénylő döntésekhez, amelyek nagyobb része az architektúrának.
Amikor az ítélet lesz az autoritás
A modellek szerepe értelmező jellegű: képesek értelmezni homályos útmutatást, felszínre hozni döntéseket, amelyek hatással lehetnek a változtatásra, megmagyarázni a határvonal-sértés következményeit és javaslatot tenni a visszaalakításra. A determinisztikus logika viszont akkor jobb, ha a csapat már döntött és a döntést olyan formában ki lehet fejezni, hogy egy ellenőrzés reprodukálhatóan ítélkezzen.
Ha egy rendszer blokkoló döntést ad, akkor az elvárás változik: egy mérnöknek meg kell tudnia kérdezni, melyik döntés alkalmazódott, miért arra a részre, milyen bizonyíték váltotta ki a választ, és hogy egy másik fejlesztő ugyanazt a checket futtatva ugyanarra az eredményre jutna-e. Ez nem követeli meg minden architekturális elem formalizálását, viszont világos határokat igen: hol engedünk meg bizonytalanságot, és hol kívánunk determinisztikus választ.
Több eszköz, közös forrás
Különösen fontos ez akkor, ha a csapat több kódolóeszközt használ egyidejűleg (Claude Code, Codex, Cursor, automata ügynökök stb.). A modellek és a retrieval-mechanizmusok különbözhetnek, de a csapat architektúrájának nem szabad eszközönként változnia. Egy megosztott döntéshalmaz szolgálhat autoritásforrásként, miközben az egyes eszközök saját módjukon fogyasztják az útmutatást, és a kikényszeríthető rész halmazát következetesen ellenőrzik.
Javasolt kiegészítés a korábbi modellhez
Valmis most módosítaná az eredeti négy-képességű modellt két ponton:
- A retrieval adja vissza a jelölt döntéseket, míg az applicability határozza meg, hogy ezek közül melyek kormányozzák ténylegesen az aktuális artefaktumot vagy műveletet (scope + lifecycle + precedence segítségével).
- Az útmutatás (guidance) és a kikényszerítés (enforcement) külön kimenetek maradnak: egyes alkalmazható döntések elég pontosak determinisztikus ellenőrzéshez, mások viszont implementációs iránymutatásként szolgálnak, és nem szabad automatikus blokkká alakítani őket.
Ennek az elkülönítésnek az az előnye, hogy az ügynököt szabadon hagyja gondolkodni ott, ahol az architektúra nyitott, miközben megőrzi az autoritást ott, ahol a csapat már döntött. Elkerüli azt a túlkompenzációt is, amikor minden architektúrát megpróbálnak formalizálni — sok architektúrális elv (pl. „tartsd szűken a domain határokat” vagy „preferáld az aszinkron integrációt, ha az azonnali konzisztencia nem szükséges”) hasznos iránymutatás marad.
Összegzés
AI-alapú kódügynököknek több kell, mint a megfelelő dokumentum megtalálása: a rendszernek tudnia kell, hogy egy döntés aktuális-e, hol van a hatásköre, és milyen jellegű autoritást szándékozott a csapat adni neki. A cél nem az, hogy minden ügynökválasztást korlátozzunk, hanem hogy a már meglévő, csapat által hozott döntéseket ne alakítsa vissza a rendszer csupán javaslattá. Ez több, mint retrieval: explicit scope, precedence, lifecycle és az alkalmazhatóság kifejezett jelzése szükséges ahhoz, hogy az automatizált és reprodukálható szabályok helyesen működjenek, miközben a modellek értelmező szerepe megmarad.
