A szándékadósság: miért kell leírni a „miért”-et az AI-ügynökök korában

Addy Osmani cikke eredetileg az Addy Osmani blogján jelent meg, és az szerző engedélyével kerül itt újraközlésre. Osmani Margaret-Anne Storey Triple Debt Modeljére hivatkozva tárgyalja a szoftveregészség háromféle adósságát: a technikai, a kognitív és a szándékadósságot.

A három adósságfajta röviden

• Technikai adósság: a forráskódban lakik. Implementációs döntések felhalmozódása teszi a rendszert később nehezebben módosíthatóvá — például összegabalyodott modulok, határidő miatti kompromisszumok, vagy átszivárgó absztrakciók. Ezt a típusú adósságot a fejlesztők régóta ismerik: lassú build, törékeny tesztek és egy-egy rettegett fájl jelezheti.

• Kognitív adósság: emberekben lakik. Ez a közös megértés eróziója, a különbség a létező kód mennyisége és az, amit egy ember ténylegesen ért. Osmani ezt korábban „comprehension debt”-nek nevezte: kialakul, amikor a rendszer gyorsabban nő, mint ahogy a csapat mentális modellje követni tudná.

• Szándékadósság (intent debt): artefaktumokban lakik. Ez azoknak a külsőleg rögzített indokoknak, céloknak és megszorításoknak a hiánya vagy elhalványulása, amelyek megmagyarázzák, miért olyan a rendszer, amilyen. A kulcsszó az „externalizált”: a szándékot le kell írni egy olyan helyre, ahol egy csapattárs, egy jövőbeli önmagad vagy egy ügynök el tudja olvasni — nem elég, ha csak fejedben létezik. Ha magas a szándékadósság, a rendszer eltávolodik attól, amit eredetileg céloztak, és senki nem tudja megmondani, mikor vagy miért történt a változás.

E három adósság egymástól függetlenül létezik: alacsony technikai adósság mellett is lehet magas szándékadósság; teljes kognitív megértés mellett is lehet, hogy a miért csak a fejben létezik.

Miért ez az egyetlen adósság, amit az ügynökök nem tudnak visszafizetni

AI már gyorsabban generál kódot, ami a technikai adósság felvételét és visszafizetését is olcsóbbá teszi. Hasonlóképpen a kognitív adósság egy része is visszanyerhető: ha nem értesz egy kódrészt, megkérheted az ügynököt, hogy magyarázza el, így újraépítheted a mentális modellt.

A szándék más. Egy ügynök nem tudja megalkotni a szándékot — az egyetlen bemenet, amelynek emberi eredetűnek kell lennie. A modell feltételezhet egy ésszerű indokot a kód alapján, ugyanúgy, ahogy te is találgathatsz egy korábbi mérnök döntésének okáról. Egy találgatás azonban nem egyenlő a tényleges szándékkal. A modell magabiztosan kitalálhat egy okot — például hogy egy 300 ms-es debounce UX-döntés volt, teljesítményeredmény vagy egyszerűen elfelejtett szám —, és ez rosszabb lehet, mint ha bevallaná, hogy nem tudja.

Az ügynök megírhatja a kódot és helyreállíthatja az érthetőséget. A „miért” azonban az, amit csak te adhatsz meg; ez az egyetlen dolog, amelyet az ügynök csak fabrikálni tud.

Az ügynökök miért gyorsítják fel az íratlan költségek felhalmozódását

Korábban a magas szándékadósság részben működött, mert sok szándék a fejünkben vagy régi dokumentumokban élt. Amikor új ember csatlakozott, az idővel felvette ezeket a hallgatólagos ismereteket: folyosói beszélgetések, kódáttekintések, „nem így csináljuk a 2023-as incidens miatt” megjegyzések. Az a fejlesztő, aki négy éve ott volt, maga volt a szándékdokumentáció — drága és veszteséges, de működött.

Az ügynökök ezt a modellt megbontják. Ügynökök bevonásakor a csapat mérete egyik pillanatról a másikra duplázódhat olyan junior entitásokkal, amelyeknek nincs hosszú távú memóriája. Egy ügynök a legtöbb munkamenetet hideg indítással kezdi: nem visz magával tacit szándékot. Amit nem externalizáltál olyan artefaktumba, amit el tud olvasni, az számára nem létezik.

Ez megváltoztatja a „nem leírni” gazdaságát. Az externalizálatlan szándék korábban alkalmankénti költség volt (onboardingkor vagy személyváltáskor). Most minden munkamenetben újra fizetsz érte, minden futtatott ügynökönként.

Képzeld el a 20 ügynököt, amelyeket párhuzamosan futtatsz: mindegyik egy olyan csapattárs, aki sosem találkozott veled, nem olvassa a gondolataidat, és bármilyen hiányt meggyőzően pótol egy kitalált indokkal. Az általam korábban említett orkesztrációs többletköltség részben ennek az intent-adósságnak a számlája; sok munkát az tesz kimerítővé, hogy újra kell szolgáltatni a le nem írt szándékot.

A kognitív adósság-érv másik fele

Korábbi írásomban azt állítottam, hogy részletes specifikációk önmagukban nem megoldás. Egy specifikáció munkakódra fordítása rengeteg implicit döntést rejt, amelyet egy specifikáció sosem fog teljesen lefedni; a túl részletes specifikáció gyakorlatilag a program lassabb nyelven. Abban továbbra is hiszek.

A szándékadósság ennek a kiegészítése: az, hogy nem tudsz minden szándékot rögzíteni, nem felmentés arra, hogy egyáltalán ne rögzíts semmit. Azok a döntések, amelyeket most az ügynök hoz meg helyetted — és amelyeket a specifikáció sosem sorol fel — azok, amelyek indoklása elpárolog, ha nem jegyzed le a terhelő, megtartandó miérteket. Nem kell mindent leírni, de le kell írnod azokat a miérteket, amelyek drágák lennének rosszul rekonstruálni.

A kognitív adósság figyelmeztet, hogy ne bízz pusztán abban, hogy a kód létezik. A szándékadósság figyelmeztet, hogy ne bízz abban, hogy a miért megmarad, csak mert a kód megmaradt. A kód a válasz; a szándék volt a kérdés, amelyre választ adott. Az AI remek a válaszok előállításában olyan kérdésekre, amelyeket elfelejtettél leírni.

Hogyan néz ki magas szándékadósság a gyakorlatban?

A szándékadósság ritkán nyilvánul meg közvetlen súrlódásként; inkább tehetetlenségként jelenik meg:

• Egy ügynök „javít” egy hibát egy őrző feltétel törlésével, és senki sem tudja megmondani, hogy az őrző feltétel kritikus volt-e vagy maradvány — mert sosem dokumentálták a miértjét.
• Egy refaktor megváltoztat egy viselkedést, amelyre a felhasználók támaszkodnak. A review átment, mert a diff tisztának tűnt és a tesztek zöldek voltak, de a tesztek csak a korábbi viselkedést kódolták, nem a szándékot.
• Megkérdezed, miért két szolgáltatás soron keresztül kommunikál, nem közvetlen hívással, és a válasz: „Egy ügynök javasolta, és úgy tűnt, rendben van.” Ez már kamatozó szándékadósság.

Ha valaha érezted a kognitív feladást, amikor egy döntést nem tudsz rekonstruálni, akkor a szándékadósság a csapatszintű, leírt változata ugyanannak a lyuknak.

Hogyan fizessük vissza: externalizáld a szándékot mint elsőrendű artefaktumot

Osmani javaslatai a gyakorlatban a következők:

• Vidd ki a szándékot a fejedből olyan helyre, ahol egy ügynök el tudja olvasni.
• Írj specifikációt a szándékról, ne az implementációról. Egy jó specifikáció tartalmazza a célokat, a megszorításokat, a nem tárgyalható elemeket és a kész állapot explicit definícióját (például: gyors, elérhető, biztonságos, örömteli, nem csak „funkcionálisan helyes”).
• Kezeld az AGENTS.md fájlt mint szándék-könyvelőt, ne konfigurációs listát. Az auto-generált init fájlok azt írják le, hogy mi a kód; az intent fájl pedig azt, hogy a csapat mit ért alatta: konvenciók, „ezt miért nem úgy csináljuk” indokok, és olyan megszorítások, amelyek egy fájlban láthatatlanok.
• Rögzítsd a döntéseket ott, ahol megszületnek. Könnyűsúlyú döntési naplók (ADRs) hatékonyak: a miért rögzítése a döntés pillanatában alig kerül valamibe, de nyolc hónappal később, amikor az azt tudó személy elment, nagyon drága lenne rekonstruálni.
• Tegyétek úgy, hogy a tanulási ciklus visszaírja a szándékot. Az önjavító ügynökökről szóló javaslatom szerint a munkamenet végén frissülhet egy „learnings” fájl. Minden rögzített hibaok és „próbáltuk X-et, de nem működött Y miatt” olyan intent, amely máskülönben csak a rossz délután emlékében maradt volna.

Ezek nem új eszközök, hanem fegyelem: megakadályozni, hogy a miért csak a fejedben létezzen egy korszakban, amikor a munka nagy részét már nem a fejed végzi.

Hova helyeződött át az érték

Hosszú ideig a szoftverben a ritka és értékes képesség helyes implementáció előállítása volt; a kód volt drága, ezért arra optimalizáltunk. Az AI olcsóvá tette a kód előállítását, a megértés pedig visszanyerhetővé vált. A szándék — a célok, megszorítások és indokok — az egyetlen bemenet, amelynek még mindig emberi eredetűnek kell lennie, és egyben az, amit a legkevésbé externalizálunk, mert évszázadokig elég volt fejben tartani.

Az a megoldás, amely működött, amikor a csapat pár fős volt és évek alatt szívta magába a szándékot, nem működik, ha a csapat fele ügynök, amelyek minden munkamenetben idegenként érkeznek.

Technikai adósság megnehezíti a rendszermódosítást. Kognitív adósság megnehezíti a megértést. Szándékadósság megnehezíti annak megállapítását, hogy a rendszer még mindig azt teszi-e, amit akartál — és ez az egyetlen, amelyet az ügynökök nem tudnak helyrehozni helyetted. Ez a rész rád marad. Írd le a miértet: ez lesz a legértékesebb dolog, amit a repóban hátrahagysz.