Karkaso inžinerija: „Codex“ panaudojimas agentų pirmumo pasaulyje

Per pastaruosius penkis mėnesius mūsų komanda vykdė eksperimentą: kūrė ir išleido vidinę programinės įrangos produkto beta versiją su 0 ranka rašyto kodo eilučių.

Produktas turi vidinių kasdienių naudotojų ir išorinių „alpha“ testuotojų. Jis pristatomas, diegiamas, sugenda ir yra sutaisomas. Skirtumas tas, kad kiekviena kodo eilutė—programos logika, testai, CI konfigūracija, dokumentacija, stebimumas ir vidiniai įrankiai—buvo parašyta „Codex“. Mes apskaičiavome, kad tai sukūrėme maždaug per dešimtadalį laiko, kurio būtų prireikę kodą rašyti rankomis.

Žmonės valdo. Agentai vykdo.

Šį apribojimą sąmoningai pasirinkome tam, kad sukurtume tai, kas būtina, ir padidintume inžinerijos spartą keliais kartais. Turėjome kelias savaites išsiųsti tai, kas galiausiai tapo milijonu kodo eilučių. Kad tai padarytume, turėjome suprasti, kas keičiasi, kai programinės įrangos inžinerijos komandos pagrindinis darbas nebėra rašyti kodą, o kurti aplinkas, nustatyti ketinimus ir kurti grįžtamojo ryšio ciklus, leidžiančius „Codex“ agentams patikimai atlikti darbą.

Šis įrašas yra apie tai, ko išmokome kurdami visiškai naują produktą su agentų komanda – kas sugedo, kas susikaupė ir kaip maksimaliai išnaudoti vienintelį tikrai ribotą mūsų išteklių: žmogaus laiką ir dėmesį.

Pirmasis įrašas į tuščią saugyklą buvo atliktas 2025 m. rugpjūčio pabaigoje.

Pradinis karkasas—saugyklos struktūra, CI konfigūracija, formatavimo taisyklės, paketų tvarkyklės sąranka ir programos karkasas—buvo sugeneruotas „Codex CLI“ naudojant GPT‑5, vadovaujantis nedideliu esamų šablonų rinkiniu. Net pradinis AGENTS.md failas, kuris nurodo agentams, kaip dirbti saugykloje, buvo parašytas pačio „Codex“.

Nebuvo jokio iš anksto egzistavusio žmonių parašyto kodo, kuriuo būtų galima pagrįsti sistemą. Nuo pat pradžių saugyklą formavo agentas.

Po penkių mėnesių saugykloje yra apie milijoną kodo eilučių, apimančių programos logiką, infrastruktūrą, įrankius, dokumentaciją ir vidines kūrėjų priemones. Per tą laikotarpį buvo atidaryta ir sulieta maždaug 1 500 pull request, o „Codex“ kūrimą nedidelėje komandoje vykdė vos trys inžinieriai. Tai reiškia, kad vidutinis pralaidumas yra 3,5 PRs vienam inžinieriui per dieną, ir stebėtina, kad pralaidumas padidėjo, kai komanda išaugo iki septynių inžinierių. Svarbu tai, kad tai nebuvo išvestis vien dėl išvesties: produktą viduje naudojo šimtai naudotojų, įskaitant kasdienius vidinius aktyvius naudotojus.

Per visą kūrimo procesą žmonės niekada tiesiogiai neprisidėjo prie kodo kūrimo. Tai tapo pagrindine komandos filosofija: jokio ranka rašyto kodo.

Praktinio žmogaus atliekamo programavimo trūkumas pristatė kitokio pobūdžio inžinerinį darbą, orientuotą į sistemas, struktūras ir svertus.

Ankstyva pažanga buvo lėtesnė, nei tikėjomės, ne dėl to, kad „Codex“ buvo nepajėgus, bet dėl to, kad aplinka buvo nepakankamai apibrėžta. Agentui trūko įrankių, abstrakcijų ir vidinės struktūros, reikalingų siekti aukšto lygio tikslų. Pagrindinė mūsų inžinerijos komandos užduotis tapo suteikti agentams galimybę atlikti naudingą darbą.

Praktikoje tai reiškė darbą gilyn: didesnių tikslų skaidymą į mažesnius kūrimo blokus (dizainas, kodas, peržiūra, testavimas ir kt.), agento paraginimą sukurti tuos blokus ir jų naudojimą sudėtingesnėms užduotims atlikti. Kai kas nors nepavykdavo, sprendimas beveik niekada nebūdavo „pabandykite labiau pasistengti.“ Kadangi vienintelis būdas pasiekti pažangą buvo priversti Codex atlikti darbą, inžinieriai visada įsitraukdavo į užduotį ir klausdavo: „kokios galimybės trūksta ir kaip padaryti jas suprantamas ir įgyvendinamas agentui?“

Žmonės su sistema beveik visiškai sąveikauja per užklausas: inžinierius aprašo užduotį, paleidžia agentą ir leidžia jam atidaryti „pull request“. Kad PR būtų užbaigtas, nurodome „Codex“ peržiūrėti savo pakeitimus lokaliai, paprašyti papildomų konkrečių agentų peržiūrų tiek lokaliai, tiek debesyje, atsakyti į bet kokį žmogaus ar agento pateiktą grįžtamąjį ryšį ir kartoti ciklą, kol visi agentų peržiūrėtojai bus patenkinti (iš esmės tai yra Ralph Wiggum Loop⁠(atsidaro naujame lange)). Codex tiesiogiai naudoja mūsų standartinius kūrimo įrankius (gh, vietinius scenarijus ir saugykloje įdiegtus įgūdžius), kad surinktų kontekstą, nereikalaujant, kad žmonės kopijuotų ir įklijuotų į CLI.

Žmonės gali peržiūrėti pull request, bet neprivalo to daryti. Laikui bėgant, beveik visas peržiūros pastangas nukreipėme į tai, kad jos būtų tvarkomos agentų tarpusavyje.

Didėjant kodo pralaidumui, mūsų kliūtimi tapo žmogiškieji QA pajėgumai. Kadangi pagrindinis apribojimas buvo žmogaus laikas ir dėmesys, mes stengėmės suteikti agentui daugiau galimybių, padarydami tokius elementus kaip programos sąsaja, žurnalai ir programos metrikos tiesiogiai suprantamus „Codex“.

Pavyzdžiui, padarėme programą paleidžiamą kiekvienam „git worktree“, kad „Codex“ galėtų paleisti ir valdyti po vieną egzempliorių kiekvienam pakeitimui. Taip pat integravome „Chrome DevTools Protocol“ į agento vykdymo aplinką ir sukūrėme funkcijas darbui su DOM momentinėmis nuotraukomis, ekrano nuotraukomis ir naršymu. Tai leido „Codex“ atkurti klaidas, patvirtinti pataisymus ir tiesiogiai analizuoti UI elgseną.

Tą patį padarėme ir stebėjimo įrankiams. Žurnalai, metrikos ir pėdsakai „Codex“ pasiekiami per vietinį stebimumo rinkinį, kuris yra laikinas kiekvienam darbo medžiui. „Codex“ veikia su visiškai izoliuota tos programos versija, įskaitant jos žurnalus ir metrikas, kurie panaikinami, kai užduotis užbaigiama. Agentai gali pateikti užklausas žurnalams naudodami LogQL ir metrikoms naudodami PromQL. Turint šį kontekstą, tokios užklausos kaip „užtikrinkite, kad paslaugos paleidimas būtų užbaigtas per mažiau nei 800 ms“ arba „joks intervalas šiose keturiose kritinėse naudotojo kelionėse neviršija dviejų sekundžių“ tampa įgyvendinamos.

Reguliariai matome, kaip vienas „Codex“ paleidimas dirba su viena užduotimi daugiau nei šešias valandas (dažnai tuo metu, kai žmonės miega).

Konteksto valdymas yra vienas iš didžiausių iššūkių, siekiant, kad agentai būtų veiksmingi vykdant dideles ir sudėtingas užduotis. Viena iš ankstyviausių pamokų, kurias išmokome, buvo paprasta: duokite „Codex“ žemėlapį, o ne 1 000 puslapių instrukcijų vadovą.

Mes išbandėme „vieną didelį AGENTS.md⁠(atsidaro naujame lange)“. požiūris. Tai nepavyko numatomais būdais:

• Kontekstas yra trūkstamas išteklius. Milžiniškas instrukcijų failas užgožia užduotį, kodą ir susijusią dokumentaciją—todėl agentas arba praleidžia svarbius apribojimus, arba pradeda optimizuoti netinkamus.
• Per daug gairių tampa nebegairėmis. Kai viskas yra „svarbu“, niekas nėra svarbu. Agentai galiausiai vietoje tikslingo naršymo ima lokaliai atpažinti dėsningumus.
• Jis akimirksniu pūva. Monolitinis vadovas tampa pasenusių taisyklių kapinynu. Agentai nebegali pasakyti, kas vis dar yra tiesa, žmonės nustoja tai prižiūrėti, ir failas tyliai tampa patrauklia problema.
• Sunku patikrinti. Vienas vientisas „blobas“ nėra tinkamas mechaninėms patikroms (apimtis, šviežumas, nuosavybė, kryžminės nuorodos), todėl nuokrypis yra neišvengiamas.

Taigi, užuot traktavę AGENTS.md kaip enciklopediją, traktuojame jį kaip turinio sąrašą.

Saugyklos žinių bazė yra struktūrizuotame docs/ kataloge, kuris laikomas oficialiu informacijos šaltiniu. Trumpas AGENTS.md (apie 100 eilučių) įterpiamas į kontekstą ir pirmiausia veikia kaip žemėlapis, nukreipiantis į gilesnius patikimus šaltinius kitur.

Dizaino dokumentacija yra kataloguojama ir indeksuojama, įskaitant patikros būseną ir pagrindinių įsitikinimų rinkinį, apibrėžiantį agento pirmumo veiklos principus. Architektūros dokumentacija⁠(atsidaro naujame lange) pateikia aukščiausio lygio domenų ir paketų sluoksniavimo žemėlapį. Kokybės dokumentas vertina kiekvieną produkto sritį ir architektūrinį sluoksnį, stebėdamas spragas laikui bėgant.

Planai laikomi aukščiausios klasės artefaktais. Efemeriški lengvi planai naudojami nedideliems pakeitimams, o sudėtingas darbas fiksuojamas vykdymo planuose⁠(atsidaro naujame lange) su pažangos ir sprendimų žurnalais, kurie įtraukiami į saugyklą. Aktyvūs planai, užbaigti planai ir žinoma techninė skola yra versijuojami ir laikomi kartu, leidžiant agentams veikti be išorinio konteksto.

Tai leidžia laipsnišką informacijos atskleidimą: agentai pradeda nuo mažo, stabilaus pradinio taško ir yra mokomi, kur ieškoti toliau, užuot iš karto buvę priblokšti.

Mes tai įgyvendiname mechaniškai. Specialūs linteriai ir CI užduotys patikrina, ar žinių bazė yra atnaujinta, susieta tarpusavyje ir tinkamai struktūrizuota. Pasikartojantis „doc-gardening“ agentas tikrina, ar nėra pasenusios ar nebeaktualios dokumentacijos, kuri neatspindi tikrosios kodo elgsenos, ir atidaro taisomuosius pull request'us.

Kai kodų bazė tobulėjo, „Codex“ dizaino sprendimų sistema taip pat turėjo tobulėti.

Kadangi saugykla yra visiškai agento sugeneruota, ji pirmiausia optimizuota Codex skaitymui. Panašiai kaip komandos siekia pagerinti savo kodo naršomumą naujai priimtiems inžinieriams, mūsų inžinierių tikslas buvo sudaryti galimybę agentui samprotauti apie visą verslo sritį tiesiogiai iš saugyklos.

Agento požiūriu, viskas, ko jis negali pasiekti kontekste vykdymo metu, iš esmės neegzistuoja. Žinios, esančios „Google Docs“, pokalbių gijose arba žmonių galvose, nėra prieinamos sistemai. Saugyklos vietiniai, versijuojami artefaktai (pvz., kodas, „Markdown“, schemos, vykdomieji planai) yra viskas, ką jis gali matyti.

Supratome, kad laikui bėgant turėjome į saugyklą įtraukti vis daugiau konteksto. Ta „Slack“ diskusija, kuri suvienijo komandą dėl architektūrinio modelio? Jei agentas negali to aptikti, tai yra neįskaitoma taip pat, kaip būtų nežinoma naujam darbuotojui, prisijungusiam po trijų mėnesių.

Suteikti „Codex“ daugiau konteksto reiškia organizuoti ir pateikti tinkamą informaciją, kad agentas galėtų ja remdamasis samprotauti, o ne jį užversti atsitiktinėmis instrukcijomis. Lygiai taip pat, kaip supažindintumėte naują komandos narį su produkto principais, inžinerinėmis normomis ir komandos kultūra (įskaitant emoji nuostatas), suteikus agentui šią informaciją, gaunama geriau suderinta išvestis.

Šis įrėminimas paaiškino daugelį kompromisų. Pirmenybę teikėme priklausomybėms ir abstrakcijoms, kurias būtų galima visiškai internalizuoti ir apmąstyti saugykloje. Technologijos, dažnai vadinamos „nuobodžiomis“, agentams paprastai yra lengviau modeliuoti dėl jų komponuojamumo, API stabilumo ir atvaizdavimo mokymo rinkinyje. Kai kuriais atvejais buvo pigiau, kad agentas iš naujo įgyvendintų funkcionalumo poaibius, nei apeiti neaiškią viešųjų bibliotekų elgseną. Pavyzdžiui, užuot naudoję bendrinį p-limitstiliaus paketą, sukūrėme savo map-with-concurrency pagalbinę funkciją: ji glaudžiai integruota su mūsų „OpenTelemetry“ instrumentavimu, turi 100 % testų aprėptį ir veikia būtent taip, kaip tikisi mūsų vykdymo aplinka.

Didesnės sistemos dalies perkėlimas į formą, kurią agentas gali patikrinti, patvirtinti ir tiesiogiai keisti, padidina svertą—ne tik „Codex“, bet ir kitiems agentams (pvz. Aardvark) kurie taip pat dirba su kodo baze.

Vien dokumentacija nepakanka, kad visiškai agento sugeneruota kodo bazė išliktų nuosekli. Užtikrindami invariantus, o ne smulkmeniškai vadovaudami įgyvendinimams, leidžiame agentams greitai pristatyti, nepakirsdami pagrindo. Pavyzdžiui, reikalaujame, kad „Codex“ analizuotų duomenų struktūras ties riba⁠(atsidaro naujame lange), tačiau nenurodome, kaip tiksliai tai turi vykti (atrodo, kad modeliui patinka Zod, bet mes nenurodėme konkrečiai šios bibliotekos).

Agentai yra veiksmingiausi aplinkose, kuriose yra griežtos ribos ir nuspėjama struktūra⁠(atsidaro naujame lange), todėl sukūrėme programą pagal griežtą architektūrinį modelį. Kiekviena verslo sritis yra suskirstyta į fiksuotą sluoksnių rinkinį, kuriame griežtai tikrinamos priklausomybių kryptys ir ribojamas leistinų briaunų skaičius. Šie apribojimai yra mechaniškai užtikrinami naudojant pasirinktinius linters (žinoma, sugeneruotus „Codex“!) ir struktūrinius testus.

Žemiau pateiktoje diagramoje parodyta taisyklė: kiekvienoje verslo srityje (pvz. Programos nustatymai), kodas gali priklausyti tik „į priekį“ per fiksuotą sluoksnių rinkinį (Types → Config → Repo → Service → Runtime → UI). Skersinės sritys (auth, jungtys, telemetrija, funkcijų vėliavėlės) patenka per vieną aiškią sąsają: Teikėjai. Visa kita yra draudžiama ir įgyvendinama mechaniškai.

Tai tokia architektūra, kurią paprastai atidedate, kol turite šimtus inžinierių. Naudojant programavimo agentus, tai yra ankstyvas reikalavimas: apribojimai leidžia išlaikyti greitį be degradacijos ar architektūrinio nuokrypio.

Praktikoje šias taisykles įgyvendiname naudodami pasirinktinius linterius ir struktūrinius testus, taip pat nedidelį „skonio invariantų“ rinkinį. Pavyzdžiui, naudodami pasirinktines lint taisykles, mes statiškai užtikriname struktūruotą žurnalų rašymą, schemų ir tipų pavadinimų konvencijas, failų dydžio limitus ir platformai būdingus patikimumo reikalavimus. Kadangi lintai yra pritaikyti, rašome klaidų pranešimus, kad į agentą kontekstą įterptume taisymo instrukcijas.

Žmonėms pirmiausia skirtoje darbo eigoje šios taisyklės gali atrodyti pedantiškos arba ribojančios. Su agentais jie tampa daugikliais: kartą užkoduoti, jie taikomi visur vienu metu.

Tuo pačiu metu aiškiai nurodome, kur apribojimai yra svarbūs, o kur ne. Tai primena didelės inžinerinės platformos organizacijos valdymą: ribas nustatyti centralizuotai, o vietoje leisti autonomiją. Jums labai rūpi ribos, tikslumas ir atkuriamumas. Šiose ribose jūs suteikiate komandoms arba agentams didelę laisvę, kaip sprendimai yra išreiškiami.

Gautas kodas ne visada atitinka žmogaus stilistinius pageidavimus, ir tai yra gerai. Kol išvestis yra teisinga, lengvai prižiūrima ir įskaitoma būsimiems agento paleidimams, ji atitinka reikalavimus.

Žmogaus skonis nuolat integruojamas atgal į sistemą. Peržiūros komentarai, refaktoringo pull request'ai ir naudotojui matomi klaidos fiksuojami kaip dokumentacijos atnaujinimai arba užkoduojami tiesiogiai į įrankius. Kai dokumentacija nepakankama, taisyklę perkeliame į kodą.

Didėjant „Codex“ pralaidumui, daugelis įprastų inžinerijos normų tapo neproduktyvios.

Saugykla veikia su minimaliais blokuojančiais sujungimo vartais. „Pull request“ užklausos yra trumpalaikės. Testų nestabilumas dažnai sprendžiamas pakartotiniais paleidimais, o ne blokuojant pažangą neribotam laikui. Sistemoje, kurioje agentų pralaidumas gerokai viršija žmogaus dėmesį, pataisymai yra pigūs, o laukimas – brangus.

Tai būtų neatsakinga mažo pralaidumo aplinkoje. Čia dažnai yra tinkamas kompromisas.

Kai sakome, kad kodų bazę sugeneravo „Codex“ agentai, turime omenyje viską, kas yra kodų bazėje.

Agentai generuoja:

• Produkto kodas ir testavimai
• CI konfigūracija ir išleidimo įrankiai
• Vidiniai programuotojų įrankiai
• Dokumentacija ir dizaino istorija
• Vertinimo įrankiai
• Peržiūros komentarai ir atsakymai
• Scenarijai, kurie tvarko pačią saugyklą
• Gamybos ataskaitų srities apibrėžčių failai

Žmonės visada lieka procese, bet dirba kitame abstrakcijos lygmenyje nei anksčiau. Teikiame pirmenybę darbui, naudotojų atsiliepimus paverčiame priėmimo kriterijais ir patikriname rezultatus. Kai agentui nesiseka, tai laikome signalu: nustatome, ko trūksta – įrankių, saugiklių, dokumentacijos – ir grąžiname tai į saugyklą, visada leisdami pačiam „Codex“ parašyti pataisą.

Agentai tiesiogiai naudoja mūsų standartinius kūrimo įrankius. Jie surenka peržiūros atsiliepimus, atsako tiesiogiai tekste, pateikia atnaujinimus ir dažnai patys sutvarko bei sulieja savo pull request'us.

Kadangi vis daugiau kūrimo ciklo elementų buvo užkoduota tiesiogiai sistemoje—testavimas, validavimas, peržiūra, atsiliepimų tvarkymas ir atkūrimas—saugykla neseniai peržengė reikšmingą slenkstį, kai „Codex“ gali nuo pradžios iki galo valdyti naujos funkcijos kūrimą.

Pateikus vieną užklausą, agentas dabar gali:

• Patikrinkite dabartinę kodų bazės būklę
• Atkurkite praneštą klaidą.
• Įrašykite vaizdo įrašą, kuriame pademonstruojamas gedimas
• Įgyvendinkite pataisą
• Patvirtinkite pataisymą vykdydami programą
• Įrašykite antrą vaizdo įrašą, demonstruojantį raišką
• Atidarykite pull request
• Atsakykite į agento ir žmogaus atsiliepimus
• Aptikti ir pašalinti komponavimo klaidas
• Perduokite žmogui tik tada, kai reikalingas sprendimas.
• Sujungti pakeitimą

Šis elgesys labai priklauso nuo konkrečios šios saugyklos struktūros ir naudojamų įrankių, todėl nereikėtų manyti, kad jis gali būti apibendrintas be panašių investicijų—bent jau kol kas ne.

Visiška agento autonomija taip pat sukelia naujų problemų. Codex atkartoja šablonus, kurie jau egzistuoja saugykloje – net jei jie yra netolygūs ar neoptimalūs. Laikui bėgant, tai neišvengiamai sukelia nuokrypį.

Iš pradžių žmonės tai spręsdavo rankiniu būdu. Mūsų komanda anksčiau kiekvieną penktadienį (20 % savaitės) skirdavo „DI šlamšto“ tvarkymui. Nieko keisto, tai nebuvo lengvai išplečiama.

Vietoj to, mes pradėjome koduoti tai, ką vadiname „auksiniais principais“, tiesiogiai į saugyklą ir sukūrėme pasikartojantį valymo procesą. Šie principai yra nuomonės pagrindu suformuotos, mechaninės taisyklės, kurios užtikrina, kad kodo bazė išliktų įskaitoma ir nuosekli būsimuose agentų vykdymuose. Pavyzdžiui: (1) teikiame pirmenybę bendriems naudingumo paketams, o ne savadarbiams pagalbiniams įrankiams, kad invariantai būtų centralizuoti, ir (2) netikriname duomenų „YOLO stiliumi“—tikriname ribas arba remiamės tipizuotais SDK, kad agentas netyčia nekurtų remdamasis spėjamomis struktūromis. Nuolat vykdomos foninės „Codex“ užduotys, skirtos ieškoti nuokrypių, atnaujinti kokybės įvertinimus ir teikti tikslines refaktorizavimo išsiuntimo užklausas. Daugumą jų galima peržiūrėti greičiau nei per minutę ir automatiškai sujungti.

Tai veikia kaip atliekų surinkimas. Techninė skola yra kaip didelių palūkanų paskola: beveik visada geriau ją nuolat mažinti mažais žingsniais, nei leisti jai kauptis ir spręsti ją skausmingais protrūkiais. Žmogaus skonis užfiksuojamas vieną kartą, o tada nuolat taikomas kiekvienai kodo eilutei. Tai taip pat leidžia mums kasdien aptikti ir išspręsti blogus modelius, užuot leidus jiems plisti kodo bazėje dienomis ar savaitėmis.

Iki šiol ši strategija gerai veikė per vidinį pristatymą ir diegimą „OpenAI“. Tikro produkto kūrimas tikriems naudotojams padėjo pagrįsti mūsų investicijas realybe ir nukreipti mus ilgalaikio palaikymo link.

Ko dar nežinome, tai kaip architektūrinis nuoseklumas vystosi per metus visiškai agentų sukurtoje sistemoje. Mes vis dar mokomės, kur žmogaus nuovoka suteikia didžiausią poveikį ir kaip tą nuovoką užkoduoti, kad ji augtų. Mes taip pat nežinome, kaip ši sistema vystysis, nes modeliai laikui bėgant tampa vis pajėgesni.

Kas tapo aišku: programinės įrangos kūrimas vis dar reikalauja drausmės, tačiau drausmė labiau pasireiškia pagalbinėje struktūroje, o ne kode. Įrankiai, abstrakcijos ir grįžtamojo ryšio ciklai, kurie padeda išlaikyti kodo bazės rišlumą, tampa vis svarbesni.

Mūsų sudėtingiausi iššūkiai dabar sutelkti į aplinkų, grįžtamojo ryšio kilpų ir valdymo sistemų projektavimą, kurie padeda agentams pasiekti mūsų tikslą: kurti ir prižiūrėti sudėtingą, patikimą programinę įrangą dideliu mastu.

Kadangi tokie agentai kaip „Codex“ perima vis didesnes programinės įrangos gyvavimo ciklo dalis, šie klausimai taps dar svarbesni. Tikimės, kad pasidaliję keliomis ankstyvomis pamokomis padėsime jums apsvarstyti, kur verta investuoti savo pastangas, kad galėtumėte tiesiog kurti dalykus.