Codex keretrendszer: a Codex használata ügynök-központú világban

Az elmúlt öt hónapban a csapatunk elvégzett egy kísérletet: egy szoftvertermék belső bétáját építettük és szállítottuk 0 sor kézzel írt kóddal.

A terméknek belső napi felhasználói és külső alfa tesztelői vannak. Kiszállítják, telepítik, elromlik, és megjavítják. A különbség az, hogy a kód minden sorát—az alkalmazáslogikát, a teszteket, a CI-konfigurációt, a dokumentációt, a megfigyelhetőséget és a belső eszközöket—a Codex írta. Becslésünk szerint körülbelül tizedannyi idő alatt készítettük el, mint amennyi időbe telt volna a kódot kézzel megírni.

Az emberek irányítanak. Az ügynökök végrehajtanak.

Szándékosan ezt a megszorítást választottuk, hogy azt építsük meg, amire szükség volt a fejlesztési sebesség nagyságrendi növeléséhez. Hetek álltak rendelkezésünkre, hogy leszállítsuk azt, ami végül egymillió sor kóddá vált. Ehhez meg kellett értenünk, mi változik, amikor egy szoftverfejlesztő csapat elsődleges feladata már nem a kódírás, hanem a környezet megtervezése, a szándék meghatározása, és olyan visszacsatolási hurok létrehozása, amely lehetővé teszi, hogy a Codex ügynökök megbízható munkát végezzenek.

Ez a bejegyzés arról szól, mit tanultunk egy vadonatúj termék ügynökcsapattal történő létrehozásakor—mi nem működött, mi adódott össze, és hogyan maximalizálhatjuk az egyetlen igazán szűkös erőforrásunkat: az emberi időt és figyelmet.

Az üres adattárba az első commit 2025. augusztus végén érkezett.

A kezdeti váz—az adattár struktúrája, a CI-konfiguráció, a formázási szabályok, a csomagkezelő beállítása és az alkalmazás-keretrendszer—a Codex CLI által, a GPT‑5 használatával készült, néhány meglévő sablon irányításával. Még az induló AGENTS.md fájlt is, amely útmutatást ad az ügynököknek arról, hogyan dolgozzanak az adattárban, maga a Codex írta.

Nem létezett előre megírt, emberi kéz által készített kód, amelyhez a rendszert rögzítettük. Az adattárat kezdettől fogva az ügynök alakította.

Öt hónappal később az adattár körülbelül egymillió sornyi nagyságrendben tartalmaz kódot az alkalmazáslogika, az infrastruktúra, az eszközök, a dokumentáció és a belső fejlesztői segédprogramok terén. Ebben az időszakban körülbelül 1 500 pull requestet nyitottak meg és egyesítettek, és mindezt egy mindössze három mérnökből álló kis csapat hajtotta végre, akik a Codexet irányították. Ez napi átlagban 3,5 PRs-t jelent mérnökönként, és meglepő módon az adatátviteli egység növekedett, ahogy a csapat bővült, és már hét mérnökből áll. Fontos, hogy ez nem öncélú volt a kimenet: a terméket belsőleg több száz felhasználó használta, köztük napi szinten belső haladó felhasználók.

A fejlesztési folyamat során emberek soha nem írtak közvetlenül kódot. Ez lett a csapat alapvető filozófiája: nincs kézzel írt kód.

A gyakorlati, emberi kódolás hiánya egy másfajta mérnöki munkát eredményezett, amely a rendszerekre, a struktúrára és a kihasználtságra összpontosít.

A kezdeti előrehaladás a vártnál lassabb volt, nem azért, mert a Codex nem volt képes dolgozni, hanem mert a környezet nem volt kellően meghatározva. Az ügynökből hiányoztak azok az eszközök, absztrakciók és belső struktúrák, amelyek a magas szintű célok eléréséhez kellettek. A mérnöki csapatunk fő feladata az lett, hogy képessé tegye az ügynököket hasznos munkavégzésre

A gyakorlatban ez azt jelentette, hogy először mélyre ástunk: a nagyobb célokat kisebb építőelemekre bontottuk (tervezés, kódolás, felülvizsgálat, tesztelés stb.), az ügynököt arra ösztönöztük, hogy felépítse ezeket az elemeket, és ezek segítségével összetettebb feladatokat oldottunk meg. Amikor valami nem sikerült, a megoldás szinte soha nem az volt, hogy „igyekezz jobban.” Mivel az egyetlen módja annak, hogy előrehaladjunk, az volt, hogy a Codex végezze el a munkát, az emberi mérnökök mindig bekapcsolódtak a feladatba, és megkérdezték: „milyen képesség hiányzik, és hogyan tehetjük azt egyszerre érthetővé és érvényesíthetővé az ügynök számára?”

Az emberek a rendszerrel szinte teljes egészében promptokon keresztül lépnek kapcsolatba: egy mérnök megad egy feladatot, elindítja az ügynököt, és hagyja, hogy az nyisson egy pull requestet. Egy PR befejezéséhez arra utasítjuk a Codexet, hogy helyben ellenőrizze a saját módosításait, kérjen további, konkrét ügynök-ellenőrzéseket mind helyben, mind a felhőben, reagáljon minden emberi vagy ügynök által adott visszajelzésre, és egy ciklusban iteráljon addig, amíg az összes ügynök-ellenőr elégedett nem lesz (gyakorlatilag ez egy Ralph Wiggum hurok⁠(új ablakban nyílik meg)). A Codex közvetlenül használja a szabványos fejlesztői eszközeinket (gh, helyi szkriptek és adattárba ágyazott képességek) a kontextus összegyűjtésére anélkül, hogy az embereknek kézzel kellene kimásolniuk és beilleszteniük azt a parancssorba.

Az emberek átnézhetik a pull requesteket, de ez nem kötelező. Idővel szinte az összes felülvizsgálati erőfeszítést úgy irányítottuk, hogy ügynökök kezeljék egymás között.

Ahogy a kód adatátviteli egysége nőtt, a szűk keresztmetszetünk a humán QA kapacitás lett. Mivel az emberi idő és figyelem fix korlátot jelent, azon dolgoztunk, hogy az ügynök több képességet kapjon azáltal, hogy az alkalmazás felhasználói felületét, a naplókat és az alkalmazásmetrikákat közvetlenül olvashatóvá tettük a Codex számára.

Például a git worktree-nként indíthatóvá tettük az alkalmazást, így a Codex el tudott indítani és vezérelni egy példányt minden egyes változtatáshoz. A Chrome DevTools Protokollt is beépítettük az ügynök futtatókörnyezetébe, és készségeket hoztunk létre a DOM-pillanatképek, képernyőképek és navigáció kezelésére. Ez lehetővé tette a Codex számára a hibák reprodukálását, a javítások validálását, valamint a felhasználói felület viselkedésének közvetlen értelmezését.

Ugyanezt tettük a megfigyelhetőségi eszközökkel. A naplók, metrikák és trace‑ek egy helyi megfigyelhetőségi rétegen keresztül válnak elérhetővé a Codex számára, amely minden egyes munkafávához ideiglenesen jön létre. A Codex az alkalmazás egy teljesen izolált verzióján dolgozik—beleértve a naplókat és a metrikákat is, amelyeket a feladat befejezése után lebontanak. Az ügynökök LogQL-lel lekérdezhetik a naplókat, és PromQL-lel a metrikákat. Ezzel a rendelkezésre álló kontextussal olyan utasítások is kezelhetővé válnak, mint például: „biztosítsd, hogy a szolgáltatás indulása 800 ms alatt befejeződjön” vagy „egyik négy kritikus felhasználói folyamatban se legyen a span hosszabb két másodpercnél”.

Rendszeresen látjuk, hogy egyetlen Codex futtatás egy feladaton akár hat órán keresztül dolgozik (gyakran akkor, amíg az emberek alszanak).

A kontextuskezelés az egyik legnagyobb kihívás abban, hogy az ügynökök hatékonyan tudjanak működni nagy és összetett feladatok során. Az egyik legkorábbi tanulság, amit levontunk, egyszerű volt: a Codexnek egy térképet adj, ne egy 1000 oldalas használati utasítást.

Kipróbáltuk az „egy nagy AGENTS.md⁠(új ablakban nyílik meg)” fájl megközelítés. Kiszámítható módon kudarcot vallott:

• A kontextus ritka erőforrás. Egy hatalmas utasításfájl eltakarja a feladatot, a kódot és a releváns dokumentációt—így az ügynök vagy kihagyja a kulcsfontosságú megszorításokat, vagy a rossz célok optimalizálásába kezd.
• A túl sok útmutatás nem-útmutatás lesz. Amikor minden „fontos”, semmi sem az. Az ügynökök végül helyben mintákat illesztenek, ahelyett hogy szándékosan navigálnának.
• Azonnal megrohad. Egy monolitikus kézikönyv az elavult szabályok temetőjévé válik. Az ügynökök nem tudják megítélni, mi az, ami még igaz, az emberek abbahagyják a karbantartást, és a fájl csendben vonzó, de problémás akadállyá válik
• Nehéz ellenőrizni. Egyetlen blob nem alkalmas mechanikus ellenőrzésre (fedettség, frissesség, tulajdonjog, kereszthivatkozások), így a drift elkerülhetetlen.

Tehát ahelyett, hogy az AGENTS.md-re enciklopédiaként tekintenénk, tartalomjegyzékként kezeljük.

Az adattár tudásbázisa egy strukturált docs/ könyvtárban található, amelyet a rendszer nyilvántartási alapjaként kezelnek. Egy rövid AGENTS.md (körülbelül 100 sor) kerül beillesztésre a kontextusba, és leginkább útmutatóként szolgál, amely másutt mélyebb igazságforrásokra mutat.

A tervezési dokumentáció katalogizálva és indexelve van, beleértve az ellenőrzési státuszt és az alapvető meggyőződések készletét, amelyek meghatározzák az ügynök-első működési alapelveket. Az architektúra dokumentációja⁠(új ablakban nyílik meg) a domainek és a csomagrétegezés legfelső szintű térképét nyújtja. Egy minőségi dokumentum minden termékterületet és architekturális réteget értékel, nyomon követve az időbeli hiányosságokat.

A terveket elsőrangú objektumként kezeljük. Az átmeneti, könnyű tervek kisebb változtatásokhoz használatosak, míg az összetett munkát végrehajtási tervekben⁠(új ablakban nyílik meg) rögzítik, a haladási és döntési naplókkal együtt, amelyek az adattárba kerülnek. Az aktív tervek, a befejezett tervek és a jól ismert műszaki adósság mind verziózottan és együtt tárolódnak, lehetővé téve, hogy az ügynökök külső kontextusra támaszkodás nélkül működhessenek.

Ez lehetővé teszi a fokozatos információfeltárást: az ügynökök egy kicsi, stabil belépési ponttal kezdik, és megtanítják nekik, hol keressenek tovább, ahelyett, hogy rögtön túlterhelődnének.

Ezt mechanikusan érvényesítjük. Dedikált lintelők és CI-feladatok ellenőrzik, hogy a tudásbázis naprakész, keresztlinkelt és helyesen strukturált. Egy ismétlődő „doc-gardening” ügynök átvizsgálja az elavult vagy idejétmúlt dokumentációt, amely nem tükrözi a kód tényleges viselkedését, és javító pull requesteket nyit meg.

Ahogy a kódbázis fejlődött, a Codex keretrendszerének a tervezési döntésekhez is fejlődnie kellett.

Mivel az adattár teljes mértékben ügynök által generált, elsősorban a Codex olvashatóságára van optimalizálva. Ugyanúgy, ahogyan a csapatok arra törekednek, hogy új mérnökhöz érkező kollégák számára könnyebben navigálható legyen a kód, az emberi mérnökeink célja az volt, hogy az ügynök közvetlenül a tárolóból tudjon következtetni az egész üzleti domainre.

Az ügynök szemszögéből minden, amihez futás közben nem fér hozzá a kontextusban, tulajdonképpen nem létezik. A Google Docsban, csevegési szálakban vagy az emberek fejében lévő tudás nem érhető el a rendszer számára. Az adattárban található, verziózott artefaktumok (pl. kód, markdown, sémák, futtatható tervek) az, amiket lát.

Rájöttünk, hogy idővel egyre több és több kontextust kell a repóba integrálnunk. Az a Slack-beszélgetés, amely összehangolta a csapatot egy architektúra mintájában? Ha az ügynök számára nem felfedezhető, ugyanolyan módon olvashatatlan, mintha egy új munkatárs számára ismeretlen lenne, aki három hónap múlva csatlakozik.

A Codex számára több kontextus biztosítása azt jelenti, hogy a megfelelő információkat rendszerezzük és elérhetővé tesszük, hogy az ügynök képes legyen ezek alapján érvelni, ahelyett, hogy ad-hoc utasításokkal túlterhelnénk. Ugyanúgy, ahogy bevezetnél egy új csapattagot a termékelvekbe, mérnöki normákba és csapatkultúrába (beleértve az emojipreferenciákat is), ha ezt az információt megadod az ügynöknek, az jobban összehangolt eredményhez vezet.

Ez a keret sok kompromisszumot tisztázott. Előnyben részesítettük azokat a függőségeket és absztrakciókat, amelyeket teljes mértékben internalizálni lehet és a repón belül végiggondolni. Az „unalmasnak” nevezett technológiákat az ügynökök gyakran könnyebben modellezik a komponálhatóság, az API-stabilitás és a tanító adathalmazban való megjelenítés miatt. Bizonyos esetekben olcsóbb volt, ha az ügynök a funkcionalitás részhalmazait újraimplementálta, mint ha a nyilvános könyvtárak átláthatatlan, felsőbb szintű viselkedésével próbáltak volna dolgozni. Például ahelyett, hogy egy általános p-limit-szerű csomagot használtunk volna, megvalósítottuk a saját map-with-concurrency segédünket: szorosan integrálva van az OpenTelemetry instrumentációval, 100%-os tesztlefedettséggel rendelkezik, és pontosan úgy viselkedik, ahogyan a futtatókörnyezetünk elvárja.”

A rendszer nagyobb részének olyan formába hozása, amelyet az ügynök közvetlenül megvizsgál, érvényesít és módosít, növeli a hatékonyságot—nemcsak a Codex, hanem más ügynökök számára is (pl. Aardvark), akik szintén a kódbázison dolgoznak.

A dokumentáció önmagában nem biztosítja a teljesen az ügynökök által generált kódbázis koherenciáját. Az invariánsok betartatásával, nem pedig a megvalósítások aprólékos irányításával lehetővé tesszük, hogy az ügynökök gyorsan szállítsanak, az alapok aláásása nélkül. Például megköveteljük, hogy a Codex az adatalakzatokat a határfelületen elemezze⁠(új ablakban nyílik meg), de nem írjuk elő ennek mikéntjét (a modell úgy tűnik, kedveli a Zodot, de nem határoztunk meg konkrét könyvtárat).

Az ügynökök a szigorú határokkal és kiszámítható struktúrával⁠(új ablakban nyílik meg) rendelkező környezetekben a leghatékonyabbak, ezért az alkalmazást szigorú architekturális modell köré építettük. Minden üzleti terület fix rétegkészletekre van bontva, a függőségi irányokat szigorúan ellenőrizzük, és csak korlátozott számú kapcsolat megengedett. Ezeket a megkötéseket mechanikusan, egyedi linterekkel (természetesen Codex által generált!) és szerkezeti tesztekkel hajtjuk végre.

Az alábbi diagram a szabályt mutatja: minden üzleti területen belül (pl. Alkalmazásbeállítások), a kód csak „előre” lehet függő egy rögzített rétegkészleten keresztül (Types → Config → Repo → Service → Runtime → UI). A keresztmetszeti szempontok (auth, csatlakozók, telemetria, funkciójelzők) egyetlen explicit felületen keresztül lépnek be: Providers. Minden más tilos, és mechanikusan kerül érvényesítésre.

Ez az a fajta architektúra, amelyet általában addig halogatsz, amíg nincs több száz mérnököd. A kódoló ügynököknél ez egy előfeltétel: a korlátok teszik lehetővé a gyorsaságot romlás vagy architekturális eltérés nélkül.

A gyakorlatban ezeket a szabályokat egyedi linterszabályokkal és strukturális tesztekkel érvényesítjük, kiegészítve egy kis készlet „ízlésállandóval”. Például egyedi lint-szabályokkal statikusan érvényesítjük a strukturált naplózást, a sémák és típusok elnevezési konvencióit, a fájlméret-korlátokat, valamint a platformspecifikus megbízhatósági követelményeket. Mivel a lintek egyediek, a hibaüzeneteket úgy írjuk meg, hogy javítási útmutatót illesszünk az ügynök kontextusába.

Egy emberközpontú munkafolyamatban ezek a szabályok pedánsnak vagy korlátozónak tűnhetnek. Az ügynökökkel szorzókká válnak: egyszer kódolva, egyszerre mindenhol érvényesülnek.

Ugyanakkor világosan megmondjuk, hol fontosak a korlátok, és hol nem. Ez egy nagy mérnöki platform szervezet irányítására hasonlít: központilag érvényesítsd a határokat, helyben pedig biztosíts autonómiát. Fontosak a határok, a helyesség és a reprodukálhatóság. E határokon belül jelentős szabadságot adsz a csapatoknak—vagy az ügynököknek—abban, hogyan fejezik ki a megoldásokat.

Az eredményül kapott kód nem mindig felel meg az emberi stíluspreferenciáknak, és ez rendben van. Amennyiben a kimenet korrekt, karbantartható és a jövőbeli ügynök futtatások számára is olvasható, akkor megfelel az elvárásoknak.

Az emberi ízlést folyamatosan visszacsatolásra kerül a rendszerbe. A felülvizsgálati megjegyzéseket, a pull requestek refaktorálását és a felhasználók számára látható hibákat dokumentációfrissítésekként rögzítik, vagy közvetlenül az eszközökbe kódolják. Amikor a dokumentáció nem elégséges, a szabályt kóddá alakítjuk.

Ahogy a Codex adatátviteli egysége nőtt, sok hagyományos mérnöki norma kontraproduktívvá vált.

Az adattár minimális blokkoló merge kapukkal működik. A pull requestek rövid életűek. A tesztflakykat gyakran utánkövető futtatásokkal kezelik, ahelyett hogy határozatlan ideig blokkolnák a haladást. Egy olyan rendszerben, ahol az ügynökök feldolgozási kapacitása messze meghaladja az emberi figyelmet, a javítás olcsó, míg a várakozás költséges.

Ez felelőtlen lenne egy alacsony adatátviteli egységű környezetben. Itt sokszor ez a helyes kompromisszum.

Amikor azt mondjuk, hogy a kódbázist a Codex ügynökei generálják, akkor az egész kódbázist értjük alatta.

Az ügynökök a következőket hozzák létre:

• Termékkód és tesztek
• CI-konfiguráció és kiadási eszközök
• Belső fejlesztői eszközök
• Dokumentáció és tervezési előzmények
• Értékelési keretrendszerek
• Megjegyzések és válaszok felülvizsgálata
• Az adattárat kezelő szkriptek
• Gyártási irányítópult definíciós fájljai

Az emberek mindig részei maradnak a folyamatnak, de más absztrakciós szinten dolgoznak, mint korábban. Prioritásokat állítunk fel, a felhasználói visszajelzéseket elfogadási kritériumokká alakítjuk, és ellenőrizzük az eredményeket. Amikor az ügynök nehézségekbe ütközik, jelzésként kezeljük: azonosítjuk, mi hiányzik—eszközök, korlátok, dokumentáció—, és visszajuttatjuk az adattárba, mindig úgy, hogy a javítást maga a Codex írja meg.

Az ügynökök közvetlenül használják a szabványos fejlesztőeszközeinket. Lekérik a felülvizsgálati visszajelzéseket, soron belül válaszolnak, frissítéseket küldenek, és gyakran összevonják és egyesítik a saját pull requestjeiket.

Ahogy egyre több fejlesztési lépést—tesztelést, érvényesítést, áttekintést, visszajelzés‑kezelést és helyreállítást—kódoltunk közvetlenül a rendszerbe, a tároló nemrég átlépett egy jelentős küszöböt: most már a Codex képes egy új funkciót végponttól végpontig önállóan végigvinni

Egyetlen utasítás megadásával az ügynök most már képes:

• Ellenőrizni a kódbázis jelenlegi állapotát
• Reprodukálni egy bejelentett hibát
• Videót rögzíteni, mely bemutatja a hibát
• Hibát kijavítani
• Ellenőrizni a javítást az alkalmazás futtatásával
• Második videót rögzíteni, amely bemutatja a felbontást
• Pull requestet nyitni
• Reagálni az ügynök és az emberi visszajelzésekre
• Buildhibákat észlelni és javítani
• Csak akkor eszkalálni emberhez, ha elbírálás szükséges
• Változtatást egyesíteni

Ez a viselkedés nagymértékben függ ennek az adattárnak a konkrét struktúrájától és eszközkészletétől, és nem szabad azt feltételezni, hogy hasonló ráfordítás nélkül általánosítható—legalábbis egyelőre nem.

A teljeskörű ügynök-autonómia új problémákat is felvet. A Codex olyan mintákat ismétel, amelyek már léteznek az adattárban – még az egyenetlen vagy nem optimális mintákat is. Idővel ez elkerülhetetlenül eltéréshez vezet.

Eleinte az emberek ezt manuálisan kezelték. A csapatunk régebben minden pénteket (a hét 20%-át) „AI-szemét” takarításával töltötte. Nem meglepő módon ez nem volt skálázható.

Ehelyett elkezdtük közvetlenül az adattárba kódolni az általunk „arany alapelveknek” nevezett elveket, és létrehoztunk egy rendszeresen ismételt tisztítási folyamatot. Ezek az alapelvek véleményezett, mechanikus szabályok, amelyek a kódbázist olvashatóvá és következetessé teszik az ügynökök jövőbeli futtatásaihoz. Például: (1) a manuálisan készített segédfüggvények helyett a megosztott segédcsomagokat részesítjük előnyben, hogy az invariánsok központosítva maradjanak, és (2) nem „YOLO-stílusban” vizsgáljuk az adatokat—ellenőrizzük a határokat, vagy típusos SDK-kra támaszkodunk, hogy az ügynök ne tudjon véletlenül feltételezett sémákra építeni. Rendszeres időközönként futtatunk egy háttérben működő Codex-feladatkészletet, amely eltéréseket keres, frissíti a minőségi osztályzatokat, és célzott refaktorálási pull requesteket nyit meg. Ezek többsége kevesebb mint egy perc alatt átnézhető és automatikusan összevonható.

Ez olyan, mint a szemétszedés. A műszaki adósság olyan, mint a magas kamatozású hitel: szinte mindig jobb folyamatosan, kis lépésekben csökkenteni, mint hagyni, hogy felhalmozódjon, és fájdalmas rohamokban próbálni kezelni. Az emberi ízlést egyszer rögzítik, majd folyamatosan érvényesítik minden egyes kódsorban. Ez lehetővé teszi számunkra, hogy napi szinten felismerjük és megoldjuk a hibás mintákat, ahelyett, hogy napokig vagy hetekig hagynánk őket terjedni a kódbázisban.

Ez a stratégia eddig jól működött az OpenAI-nál a belső bevezetés és elfogadás során. Valós felhasználóknak szánt valós termék építése segített abban, hogy befektetéseinket a valóságban tartsuk, és a hosszú távú fenntarthatóság felé irányítson minket.

Még nem tudjuk, hogyan alakul az architekturális koherencia az évek során egy teljesen ügynök által generált rendszerben. Még mindig tanuljuk, hol van a legnagyobb haszna az emberi ítélőképességnek, és hogyan lehet úgy kódolni, hogy ez az érték fokozatosan megsokszorozódjon. Azt szintén nem tudjuk egyenlőre, hogyan fog ez a rendszer fejlődni, ahogy a modellek idővel egyre fejlettebbé válnak.

Ami világossá vált: a szoftverfejlesztés továbbra is fegyelmet követel, de ez a fegyelem inkább a struktúrákban, mintsem a kódban mutatkozik meg. A kódbázis koherenciáját fenntartó eszközök, absztrakciók és visszacsatolási körök egyre fontosabbá válnak.

Legnehezebb kihívásaink most a környezet, visszacsatolási hurok és vezérlőrendszerek megtervezésére összpontosulnak, amelyek segítik az ügynököket célunk elérésében: összetett, megbízható szoftverek nagy léptékű építésében és fenntartásában.

Amint az olyan ügynökök, mint a Codex, a szoftver életciklusának egyre nagyobb részét veszik át, ezek a kérdések úgy válnak még fontosabbá. Reméljük, hogy néhány korai tanulság megosztása segít átgondolni, hová érdemes energiát fektetned, hogy egyszerűen építhess.