Markus Eisele tapasztalata szerint ma, amikor ügynökök (agents) nagyon gyorsan tudnak kódot előállítani, a csapatok gyakran egy különálló, elavuló dokumentációt találnak a repository mellett: követelmények, kutatási jegyzetek, magas szintű és alacsony szintű tervek, feladatlisták, review-jelentések és egyre növekvő Markdown-állományok. Gyakran előfordul, hogy a kód kedden megváltozott, de a dokumentáció hetek óta nem frissült.
Eisele szerint a probléma nem új: a kód és a dokumentáció párhuzamos evolúciója mindig is megvolt. Az ügynökök gyors kódgenerálása azonban felerősíti a jelenséget: a csapatok úgy próbálják csökkenteni a driftet, hogy több gondolkodást helyeznek az implementáció elé, és a Markdown-alapú követelményeket, döntési nyilvántartásokat és elfogadási kritériumokat a munkafolyamat mozgatórugójává teszik.
A természetes nyelv korlátai
Egy nagy, természetes nyelvű specifikáció könnyen kitöltheti a modern ügynökök kontextusablakának jelentős részét, mielőtt bármilyen releváns forráskód bekerülne. Natural-language spec gyenge rendszer az ügynökök számára, hogy szinkronban tartsák a kódbázist; figyelem nélkül az ügynökök hamar a kód erősebb jeleihez igazodnak, és elfelejtik frissíteni a specifikációt.
Eisele nem a one-shot prompting vagy a "vibe coding" pártján áll: továbbra is szükség van valamilyen specifikációra a sikeres szoftverépítéshez. A hibás megközelítés az, ha a specifikációt állandó, teljes természetes nyelvi másolatnak tekintjük. Egy hasznos specifikáció a következő változtatást írja le, dokumentálja a döntéseket, határokat állít fel és elegendő verifikációs felületet ad – de a változtatás megszállítása után a legtöbb része el kell hogy tűnjön.
A „change brief” — a rövid változtatási leírás
Eisele rövid, célirányos dokumentumot javasol, amelyet ő „change brief”-nek hív, nem „specification”-nek. A change brief célja a delta — az aktuális és a kívánt állapot közötti különbség — leírása. Ami szerepeljen benne:
- A kívánt eredmény és szükség esetén a nem-célok
- Ismert ismeretlenek és olyan döntések, amelyek emberi megítélést igényelnek
- Érintett rendszerhatárok és hiteles interfész-objektumok
- Funkcionális és nem-funkcionális korlátok, amelyek eltérnek a mai állapottól
- Elfogadási kritériumok / tesztscenáriók a kockázatos útvonalak lefedésére
A change briefnek ideiglenesnek kell maradnia: az implementáció után a tartós információnak a kódba, séma-definíciókba, tesztekbe, policy-kbe és operációs jelekbe kell vándorolnia.
A kód mint tény
A kód a tényleges viselkedés: ha kódot élesbe tesznek, felhasználók és rendszerek attól függnek. A futásidejű viselkedés jogilag és gyakorlati szempontból elsőbbséget élvez: gyakran egy hibából három év alatt „szerződés” lesz, mert így viselkedett. Ezért Eisele szerint a vizsgálatot a tényleges, éles kódnál kell kezdeni; a természetes nyelv nem ad pontos képet az éles viselkedésről.
Ugyanakkor a termelési kód nem tud előrevezetni jövőbeli politika-változásokat, jogszabályi követelményeket vagy ügyfélspecifikus kivételeket. Ezeket a kontextusokat rövid, célzott leírásokból kell adni — nem egy teljes irodalmi másolatból.
Felfedezés munka közben
A prompt, ticket vagy change brief rögzíti, amit azelőtt tudunk, hogy a munka elkezdődik. A kódbázis, a futáskori információk, a konfigurációk és az évek alatt a kódba ragadt döntések adják a többit. Ahogy az ügynökök dolgoznak, feltáródnak az ismeretlenek: váratlan függőségek, prototípusok, amelyek feltárják a rossz UX-et, tesztek, amelyek edge-case-eket hoznak elő, vagy a production-adatok, amelyek ellentmondanak a feltételezéseknek.
A felfedezés három szakaszban zajlik: a megvalósítás előtt (rendszeráttekintés, olcsó prototípus), a megvalósítás alatt (az eltérések lejegyzése, újraértékelés) és a megvalósítás után (kód olvasása, ellenőrzések futtatása, összevetés a céllal). A change brief végig része a ciklusnak, de csak a kitartó korlátokat kell előléptetni.
A tartós tények natív formája
Eisele hangsúlyozza, hogy a döntéseket és tényeket nem minden esetben kell Markdown formában tartósítani. Sok tartós információ jobb helyen van mérhető, géppel értelmezhető, fenntartható formában:
- API-k OpenAPI/AsyncAPI séma, protokollsémák, típusok és kompatibilitási tesztek
- Adat-invariánsok típusokban, adatbázis-korlátozásokban, validációkban és migrációs ellenőrzésekben
- Biztonsági szabályok hozzáférési policy-kben, statikus analízisben és futásidejű érvényesítésben
- Architektúra-határok modulstruktúrában, függőségi szabályokban és fókuszált architektúra-tesztekben
- Megbízhatósági igények terhelés-tesztben, SLO-kban, telemetriában és riasztásokban
A természetes nyelvnek továbbra is helye van: üzleti szabályok, kompromisszumok és architektúrális indoklások rövid, a magyarázott dologhoz közel tartott dokumentumai (például néhány Architecture Decision Record) hasznosak lehetnek, de nem szabad túl sok helyi döntést rögzíteni, mert elrejtik a valóban fontosakat.
Megítélés a munkafolyamatokban
A régi, mindenre kiterjedő specifikációs módszerek a minőséget úgy próbálták szabályozni, hogy előírták az útvonalat — minden változtatás ugyanazokat a dokumentumokat és review-kat követte. Ez túl sok figyelmet kötött le alacsony kockázatú munkán, miközben a valódi, mély műszaki megítélést elkerülte.
Simon Willison megközelítését idézve Eisele azt javasolja, hogy adjuk meg az eredményt az ügynöknek, és hagyjuk, hogy eldöntse, mennyi folyamat szükséges. A csapat határozza meg a célokat, biztonsági korlátokat, tulajdonjogot és elfogadási jogosultságot; az ügynök taktikát választ a határok között, és felszólal, ha bizonytalanság olyan következményekkel jár, amelyek meghaladják a jogosultságát.
A munkafolyamatnak a kockázat szerint kell tükröződnie: kis, ismert változtatásoknál rövid briefből implementáció és review; ismeretlen kódnál kutatás és tényfeltárás; UX-kérdéseknél prototípus és esetleg felhasználói kutatás; architekturális változásnál emberi egyeztetés; magas következményű változtatásoknál erősebb független bizonyíték és jóváhagyás.
Kontextus, mint mérnöki költségvetés
Nagy specifikációk nem csupán az írás és karbantartás idejébe kerülnek: versenyeznek azokkal az információkkal is, amelyekre az ügynöknek szüksége van. Minden extra anyag a korlátozott munkakontekstuális ablak egy részét elfoglalja, ami elveszett figyelmet eredményez. Progressive disclosure jobb megközelítés: kis térképet, néhány stabil szabályt és hivatkozásokat adjunk mélyebb anyagokra. Egy rövid AGENTS.md hasznos lehet build-parancsok, repository-layout és architektúra-határok leírására, de nem magyarázza el minden osztályt.
Tapasztalatok a Research-Plan-Implement megközelítéssel azt mutatják, hogy a hatalmas kontextusok (száz vagy akár ezer soros tervek) gyakran azt eredményezik, hogy a végrehajtás eltér a leellenőrzött tervtől, így később a döntést a kódból kell újra felépíteni. Ez különösen rossz brownfield rendszerekben.
Modernizáció és brownfield szemlélet
Érett alkalmazásokban többféle viselkedés él együtt: tartós üzleti logika, platform-korlátokból adódó kód, eseménykorrekciók és túlélő hibák. A modernizáció megítélést követel: mi marad, mi építhető át, mi törölhető.
Eisele ajánlása brownfield változtatásoknál: először osztályozás és megfigyelés. Célok:
- Tartós üzleti invariánsok és külső elvárások megőrzése
- Az aktívnak látszó, de bizonytalan ownership-del rendelkező viselkedés verifikálása
- Régi architekturális korlátokhoz kötődő logika újratervezése
- Halott utak, duplikált logika és megerősített hibák eltávolítása
Statikus analízis és tesztek mellett javasolja a mutation testing (például PIT) használatát rejtett feltételezések és hibajelenségek felfedésére, illetve a kódlefedettség újbóli értékelését. Operációs kontextus és telemetria szintén létfontosságú a meglévő viselkedés megítéléséhez.
Kis specifikációk is igényelnek bizonyítékot
Rövid specifikáció nem jelenti azt, hogy laza promptokkal és reménybeli review-val térünk vissza. Az ügynök képes lehet koherens implementációt létrehozni olyan döntések nélkül, amelyek később fontosak lennének — az eredmény belső konzisztenciája megtévesztő lehet. Ezt alátámasztják kutatások: az ambiguitások direkt modellekhez intézett megkérdezése gyakran inkonzisztens vagy irreleváns eredményhez vezet. Koncentrált javítási és független ellenőrzési megközelítés javította az eredményeket (például ~31% javulás bizonyos vizsgálatoknál).
A SWT-Bench kimutatta, hogy a generált tesztek képesek szűrni a javasolt javításokat és megduplázni a szoftaverés ügynök pontosságát: egy ügynök javasolt változtatást generált, egy másik pedig bizonyítékot adott arra, hogy elutasítsa azt. Formális specifikációk automatikus generálása sem hozott meggyőzően jó eredményt: egy v. tanulmány 30 modellből a legjobb eredmény 27% szintaktikai és 9% szemantikai helyességet hozott TLA+ fordításnál.
Ezek az eredmények a céltudatos tisztázás és a független ellenőrzés szükségességét támasztják alá. A bizonyíték erejét és függetlenségét a tévedés következményéhez kell igazítani: kis belső refaktorhoz elegendőek a megszokott tesztek és code review; biztonsági, pénzügyi vagy szabályozott adatok érintésekor erősebb szeparációra, adversariális review-ra és explicit emberi jóváhagyásra van szükség.
Egy könnyedebb működési modell
Gyakorlatban Eisele egy egyszerű, öt lépéses munkafolyamatot javasol, amely világosan magyarázható:
- Kezdjünk a kóddal és az operációs bizonyítékokkal, amelyek leírják a jelenlegi rendszert
- Határozzuk meg az elvárt deltát, fontos határokat és ismert ismeretleneket
- Adjuk hozzá a kutatást, prototípusokat, tervezési összehangolást vagy erősebb verifikációt, ahol a kockázat indokolja
- Olvassuk és review-zzuk az implementációt, ne csak a tervet
- A kiadáskor töröljük a ideiglenes érvelést és őrizzük meg a túlélő tényeket natív, hiteles tárgyakban
Ez elegendő szerkezet ahhoz, hogy vezesse a munkát anélkül, hogy természetes nyelvi replikátumokat építenénk a szoftverből.
Összegzés
Eisele javaslata a fókuszált, ideiglenes change briefek és a kódközpontú munkafolyamatok mellett azt hangsúlyozza, hogy a tartós tudást a kód, sémák, tesztek, policy-k és telemetria őrizze meg. Csak azokat a részleteket rögzítsük prose formában, amelyek nem férnek be semmilyen végrehajtható vagy géppel ellenőrizhető artefaktumba. A cél: specifikálni, ami döntést igényel; felfedezni, amit a rendszer meg tud válaszolni; verifikálni, ami kockázatot hordoz; és engedni, hogy az ideiglenes tervek lejárjanak a kiadás után.
Hivatkozott források (válogatás)
- A Field Guide to Finding Your Unknowns, Thariq Shihipar, 2026
- Judgement, Simon Willison, 2026
- Can LLMs Write Correct TLA+ Specifications?, Bisharat et al., 2026
- Automated Repair of Ambiguous Natural Language Requirements, Jia et al., 2025
- SWT-Bench: Testing and Validating Real-World Bug-Fixes with Code Agents, Mündler et al., 2024
- Everything We Got Wrong About Research-Plan-Implement, Dexter Horthy, 2026
- Usage, Effects and Requirements for AI Coding Assistants in the Enterprise, IBM Research, 2026
- From AI Governance to AI Assurance, IBM, 2026
(Ügynökök: az eredeti cikk Markus Eisele átdolgozását és újraközlését ismerteti.)
