Inseneritöö: Codexi kasutamine agent-esmase maailma kontekstis

Viimase viie kuu jooksul on meie meeskond läbi viinud eksperimendi: ehitanud ja lansseerinud tarkvaratoote sisemise beetaversiooni 0 käsitsi kirjutatud koodireaga.

Tootel on sisemised igapäevased kasutajad ja välised alfatestijad. See tarnitakse, juurutatakse, läheb katki ja saab parandatud. Erinevus seisneb selles, et iga koodirida—rakendusloogika, testid, CI konfiguratsioon, dokumentatsioon, jälgitavus ja sisemised tööriistad—on Codexi poolt kirjutatud. Meie hinnangul ehitasime selle umbes 1/10 ajaga, mis oleks kulunud koodi käsitsi kirjutamiseks.

Inimesed juhivad. Agendid täidavad käske.

Me valisime selle piirangu teadlikult, et ehitada seda, mis oli vajalik inseneritöö suurusjärkude võrra kiiremaks muutmiseks. Meil oli nädalaid aega, et tarnida see, mis lõpuks osutus miljoniks reaks koodiks. Selleks pidime mõistma, mis muutub siis, kui tarkvarainseneride meeskonna peamine ülesanne ei ole enam koodi kirjutamine, vaid keskkondade kujundamine, kavatsuse täpsustamine ja tagasisideahelate loomine, mis võimaldavad Codexi agentidel töökindlalt töötada.

See postitus käsitleb seda, mida me õppisime, kui lõime täiesti uue toote agentide meeskonnaga—mis läks katki, mis kuhjus ja kuidas maksimeerida meie ainsat tõeliselt nappi ressurssi: inimese aega ja tähelepanu

Esimene muudatus tühja varamusse sai tehtud 2025. aasta augusti lõpus.

Esialgne karkass—varamu struktuur, CI konfiguratsioon, vormindusreeglid, paketihalduri seadistus ja rakendusraamistik—genereeriti Codex CLI abil GPT‑5 kasutades, tuginedes väikesele hulgale olemasolevatele mallidele. Isegi esialgne AGENTS.md fail, mis juhendab agente, kuidas varamus töötada, oli Codexi enda kirjutatud.

Süsteemi ankurdamiseks puudus eelnev inimeste loodud kood. Algusest peale kujundas varamu agent.

Viis kuud hiljem sisaldab varamu umbes miljonit rida koodi, mis hõlmab rakendusloogikat, taristut, tööriistu, dokumentatsiooni ja sisemisi arendaja utiliite. Selle perioodi jooksul on avatud ja liidetud ligikaudu 1500 pull request'i ning Codexit vedas väike, vaid kolmest insenerist koosnev meeskond. See tähendab keskmiselt 3,5 PR-i inseneri kohta päevas, ja üllataval kombel on läbilase suurenenud, kui meeskond on kasvanud nüüd seitsme insenerini. Oluline on, et see ei olnud väljund väljundi pärast: toodet on sisemiselt kasutanud sajad kasutajad, sealhulgas igapäevased sisemised võimsad kasutajad.

Kogu arendusprotsessi vältel ei panustanud inimesed kunagi otseselt ühtegi koodirida. Sellest sai meeskonna jaoks põhifilosoofia: ei mingit käsitsi kirjutatud koodi.

Praktilise inimliku kodeerimise puudumine tõi kaasa teistsuguse inseneritöö, mis keskendus süsteemidele, tugistruktuuridele ja võimendusele.

Varajane edasiminek oli aeglasem, kui me ootasime, mitte seetõttu, et Codex oli võimetu, vaid seetõttu, et keskkond oli määratlemata. Agendil puudusid tööriistad, abstraktsioonid ja sisemine struktuur, mis olid vajalikud liikumaks edasi kõrgetasemeliste eesmärkide suunas. Meie inseneride meeskonna peamiseks ülesandeks sai agentide kasuliku töö võimaldamine.

Praktikas tähendas see süvatöötamist: suuremate eesmärkide jaotamist väiksemateks ehitusplokkideks (kujundus, kood, ülevaatus, testimine jne), agendi suunamist nende plokkide koostamisele ning nende kasutamist keerukamate ülesannete avamiseks. Kui miski ebaõnnestus, siis lahendus polnud peaaegu kunagi “pinguta rohkem.” Kuna ainus viis edusamme teha oli panna Codex tööd ära tegema, astusid iniminsenerid alati ülesande tegemisele vahele ja küsisid: “milline võimekus on puudu ja kuidas teeme selle agendi jaoks nii arusaadavaks kui ka jõustatavaks?”

Inimesed suhtlevad süsteemiga peaaegu täielikult viipade kaudu: insener kirjeldab ülesannet, käivitab agendi ja lubab sellel avada pull request'i. PR-i lõpuleviimiseks juhendame Codexit, et Codex vaataks oma muudatusi kohapeal üle, taotleks täiendavaid konkreetseid agentide ülevaatusi nii kohapeal kui ka pilves, vastaks igasugusele inimese või agendi antud tagasisidele ning itereeriks tsüklit, kuni kõik agentidest ülevaatajad on rahul (sisuliselt on see Ralph Wiggum Loop⁠(avaneb uues aknas)). Codex kasutab meie standardseid arendustööriistu (gh, kohalikud skriptid ja varamusse manustatud oskused) otse konteksti kogumiseks, ilma et inimesed peaksid CLI-sse kopeerima ja kleepima.

Inimesed võivad, aga ei pea pull request'e üle vaatama. Aja jooksul oleme suunanud peaaegu kogu ülevaatamise pingutuse agendilt agendile käsitlemisele.

Kuna koodi läbilase suurenes, sai meie pudelikaelaks inimeste kvaliteedikontrolli võimekus. Kuna fikseeritud piiranguks on olnud inimeste aeg ja tähelepanu, oleme töötanud selle nimel, et lisada agendile rohkem võimekusi, muutes rakenduse kasutajaliidese, logid ja rakenduse mõõdikud Codexi jaoks otse loetavaks.

Näiteks tegime rakenduse käivitatavaks iga git worktree jaoks, et Codex saaks käivitada ja juhtida üht eksemplari iga muudatuse kohta. Me ühendasime ka Chrome DevTools Protocoli agendi käitusajaga ja lõime oskused DOM-i hetktõmmiste, kuvatõmmiste ja navigeerimisega töötamiseks. See võimaldas Codexil vigu taastoota, parandusi valideerida ja otse kasutajaliidese käitumise üle arutleda.

Tegime sama ka jälgitavuse tööriistade jaoks. Logid, mõõdikud ja jäljed on Codexile kättesaadavad kohaliku vaadeldavuse virna kaudu, mis on iga tööpuu jaoks ajutine. Codex töötab selle rakenduse täielikult isoleeritud versioonis—sealhulgas selle logid ja mõõdikud, mis eemaldatakse, kui see ülesanne on lõpule viidud. Agendid saavad logisid LogQL-i ja mõõdikuid PromQL-i abil pärida. Kui see kontekst on kättesaadav, muutuvad viibad nagu „taga, et teenuse käivitumine lõpeb vähem kui 800 ms-ga“ või „ükski span nendes neljas kriitilises kasutajateekonnas ei ületa kahte sekundit“ teostatavaks.

Me näeme regulaarselt, et üksikud Codexi käivitused töötavad ühe ülesande kallal üle kuue tunni (sageli samal ajal, kui inimesed magavad).

Konteksti haldamine on üks suurimaid väljakutseid agentide tõhususe tagamisel, kui täita suuri ja keerukatid ülesandeid. Üks varasemaid õppetunde, mille me saime, oli lihtne: anna Codexile kaart, mitte 1000-leheküljeline kasutusjuhend.

Proovisime "ühe suure AGENTS.md⁠(avaneb uues aknas)” lähenemist. See ebaõnnestus etteaimataval viisil:

• Kontekst on piiratud ressurss. Hiiglaslik juhisefail surub ülesande, koodi ja asjakohased dokumendid tagaplaanile—nii et agent kas jätab olulised piirangud märkamata või hakkab optimeerima valedele.
• Liiga palju juhiseid muutub mittejuhisteks. Kui kõik on “oluline”, siis ei ole miski oluline. Agendid hakkavad lõpuks kohapeal mustreid sobitama, selle asemel et teadlikult navigeerida.
• See laguneb koheselt. Monoliitne käsiraamat muutub vananenud reeglite surnuaiaks. Agendid ei suuda aru saada, mis on endiselt tõsi, inimesed lõpetavad selle hooldamise ja failist saab vaikselt ahvatlev probleem.
• Seda on raske kontrollida. Üksik blob ei sobi mehaanilisteks kontrollideks (katvus, ajakohasus, omandiõigus, ristviited), seega on triiv vältimatu.

See tähendab, et selle asemel, et käsitleda AGENTS.md-d entsüklopeediana, käsitleme seda kui sisukorda.

Varamu teadmistebaas asub struktureeritud docs/ kataloogis, mida käsitletakse süsteemi registrina. Lühike AGENTS.md (umbes 100 rida) lisatakse konteksti ja toimib peamiselt kaardina, viidates mujal asuvatele sügavamatele tõeallikatele.

Disainidokumentatsioon on kataloogitud ja indekseeritud, sealhulgas verifitseerimise olek ja põhiveendumuste kogum, mis määratleb agent-esimesena tegutsemispõhimõtted. Arhitektuuri dokumentatsioon⁠(avaneb uues aknas) annab ülevaate domeenide ja pakettide kihistuse kõrgtaseme kaardist. Kvaliteedidokument hindab iga tootevaldkonda ja arhitektuurikihti, jälgides ajas esinevaid puudujääke.

Plaane käsitletakse esmaklassiliste artefaktidena. Ajutisi kergekaalulisi plaane kasutatakse väikeste muudatuste jaoks, samas kui keeruline töö jäädvustatakse teostusplaanidesse⁠(avaneb uues aknas) koos edenemise ja otsustuslogidega, mis lisatakse varamusse. Aktiivsed plaanid, lõpetatud plaanid ja teadaolev tehniline võlg on kõik versioonitud ja koos paigutatud, võimaldades agentidel tegutseda ilma välisele kontekstile tuginemata.

See võimaldab järk-järgulist avalikustamist: agendid alustavad väikese, stabiilse sisenemispunktiga ja neile õpetatakse, kuhu järgmisena vaadata, selle asemel et neid kohe alguses üle koormata.

Me rakendame seda mehaaniliselt. Eraldi linterid ja CI-tööd kontrollivad, et teadmistebaas on ajakohane, ristviidatud ja õigesti struktureeritud. Korduv “doc-gardening” agent otsib aegunud või vananenud dokumentatsiooni, mis ei kajasta koodi tegelikku käitumist, ja avab paranduste pull request’e.

Kuna koodibaas arenes, pidi arenema ka Codexi raamistikk disainiotsuste tegemiseks.u

Kuna varamu on täielikult agendi poolt genereeritud, on see esmalt optimeeritud Codexi loetavuse jaoks. Samamoodi nagu meeskonnad püüavad parandada oma koodi navigeeritavust uutele inseneritööle asujatele, oli meie iniminseneride eesmärk võimaldada agendil kogu äridomeeni üle arutleda otse varamu enda kaudu.

Agendi vaatenurgast ei eksisteeri midagi, millele ta töötamise ajal kontekstis ligi ei pääse. Teadmised, mis asuvad Google Docsis, vestluslõimedes või inimeste peas, ei ole süsteemile kättesaadavad. Varamu-lokaalsed, versioonitud artefaktid (nt kood, markdown, skeemid, käivitatavad plaanid) on kõik, mida see näeb.

Saime teada, et pidime aja jooksul üha rohkem konteksti repo'sse lisama. See Slacki arutelu, mis viis meeskonna arhitektuurimustri osas ühele meelele? Kui agent ei leia seda üles, on see samamoodi loetamatu, nagu oleks see tundmatu uue töötaja jaoks, kes liitub kolme kuu pärast.

Codexile enama konteksti andmine tähendab õige teabe korraldamist ja esiletoomist, et agent saaks selle põhjal arutleda, selle asemel et oleks juhuslike juhistega üle koormatud. Samamoodi, nagu tutvustaksid uuele meeskonnakaaslasele toote põhimõtteid, inseneritöö norme ja meeskonnakultuuri (sh emoji-eelistusi), viib selle teabe agendile andmine paremini kooskõlastatud väljundini.

See raamistus selgitas paljusid kaalutlusi. Eelistasime sõltuvusi ja abstraktsioone, mida saaks täielikult internaliseerida ja repositooriumisiseselt läbi mõelda. Tehnoloogiaid, mida sageli kirjeldatakse kui “igavaid”, on agentidel lihtsamini mudelit luua tänu kompositsioonilisusele, API stabiilsusele ja esindatusele treeningandmestikus. Mõnel juhul oli odavam lasta agendil funktsionaalsuse alamhulgad uuesti rakendada, kui tegeleda avalike teekide läbipaistmatu ülesvoolu käitumisega. Näiteks, selle asemel et kasutada üldist p-limit-stiilis paketti, rakendasime omaenda kaardistamise-konkurentsi abifunktsiooni: see on tihedalt integreeritud meie OpenTelemetry instrumentatsiooniga, sellel on 100% testkatvus ja see käitub täpselt nii, nagu meie käitusaeg eeldab.

Suurema osa süsteemi toomine vormi, mida agent saab kontrollida, valideerida ja otse muuta, suurendab mõjuvõimu—mitte ainult Codexi, vaid ka teiste agentide jaoks (nt Aardvark) kes töötavad samuti koodibaasi kallal.

Ainuüksi dokumentatsioon ei hoia täielikult agentide genereeritud koodibaasi sidusana. Jõustades invariandid, mitte mikrotasandil teostusi juhtides, võimaldame agentidel kiiresti tarnida, ilma et see õõnestaks alust. Näiteks nõuame, et Codex analüüsiks andmekujusid piiril⁠(avaneb uues aknas), kuid me ei ole ettekirjutuslikud selle osas, kuidas see peaks toimuma (mudelile näib meeldivat Zod, kuid me ei määranud seda konkreetset teeki).

Agendid on kõige tõhusamad keskkondades, kus on ranged piirid ja etteaimatav struktuur⁠(avaneb uues aknas), seetõttu ehitasime rakenduse jäiga arhitektuurse mudeli ümber. Iga ärivaldkond on jaotatud kindlaks kihikomplektiks, millel on rangelt valideeritud sõltuvussuund ja piiratud hulk lubatud servi. Neid piiranguid rakendatakse mehaaniliselt kohandatud linterite (muidugi Codexi loodud!) ja struktuuritestide kaudu.

Allolev diagramm näitab reeglit: iga ärivaldkonna piires (nt rakenduse seaded), kood saab sõltuda ainult „edasi” läbi fikseeritud kihtide komplekti (Tüübid → Konfig → Repo → Teenus → Käitusaeg → Kasutajaliides). Läbilõikelised teemad (autentimine, ühendused, telemeetria, funktsioonide lipud) sisenevad ühe selgesõnalise liidese kaudu: pakkujad. Kõik muu on keelatud ja seda rakendatakse mehaaniliselt.

See on selline arhitektuur, mida tavaliselt edasi lükkad, kuni sul on sadu insenere. Kodeerimisagentidega on see varajane eeltingimus: piirangud on need, mis võimaldavad kiirust ilma lagunemise või arhitektuurilise triivita.

Praktikas rakendame neid reegleid kohandatud linterite ja struktuuritestidega ning väikese hulga „maitseinvariantidega.” Näiteks rakendame me staatiliselt struktureeritud logimist, skeemide ja tüüpide nimetamise reegleid, failisuuruse piiranguid ning platvormipõhiseid töökindlusnõudeid kohandatud lintidega. Kuna lintid on kohandatud, kirjutame veateated, et lisada parandusjuhised agendi konteksti.

Inimesekeskses töövoos võivad need reeglid tunduda pedantsed või piiravad. Agentidega muutuvad need kordajateks: kui need on kodeeritud, rakenduvad need kõikjal korraga.

Samal ajal oleme selgesõnalised selles, kus piirangud on olulised ja kus need ei ole olulised. See sarnaneb suure inseneriplatvormi organisatsiooni juhtimisega: kehtesta piirid tsentraalselt, võimalda autonoomiat lokaalselt. Sa hoolid sügavalt piiridest, korrektsusest ja reprodutseeritavusest. Nende piiride raames annad meeskondadele—või agentidele—märkimisväärse vabaduse selles, kuidas lahendusi väljendatakse.

Tulemuseks olev kood ei vasta alati inimeste stiilieelistustele, ja see on täiesti normaalne. Kui väljund on korrektne, hooldatav ja tulevaste agentide käivituste jaoks loetav, vastab see nõuetele.

Inimeste maitset tagasisidestatakse süsteemile pidevalt. Koodiülevaatuse kommentaarid, refaktoreerimise pull request'id ja kasutajale nähtavad vead talletatakse dokumentatsiooni uuendustena või kodeeritakse otse tööriistadesse. Kui dokumentatsioon jääb puudulikuks, viime reegli koodi.

Kui Codexi läbilase suurenes, muutusid paljud tavapärased insenerinormid kontraproduktiivseks.

Varamu töötab minimaalsete blokeerivate ühendamisväravatega. Pull request'id on lühiajalised. Testihelbeid käsitletakse sageli järelkatsetega, selle asemel, et progress oleks määramata ajaks blokeeritud. Süsteemis, kus agentide läbilase ületab kaugelt inimliku tähelepanu, on parandused odavad ja ootamine kallis.

See oleks madala läbilaskega keskkonnas vastutustundetu. Siin on see sageli õige kompromiss.

Kui me ütleme, et koodibaasi on genereerinud Codexi agendid, peame silmas kõike, mis on koodibaasis.

Agendid loovad:

• tootekoodi ja testid
• CI-konfiguratsiooni ja väljalaske tööriistad
• sisemised arendaja tööriistad
• dokumentatsiooni ja disaini ajaloo
• hindamisrakendused
• kommentaaride ja vastuste ülevaate
• skriptid, mis haldavad varamut ennast
• tootmise juhtpaneeli määratlusfailid

Inimesed jäävad alati protsessi, kuid töötavad teistsugusel abstraktsioonitasandil kui me seda varem tegime. Seame töö prioriteediks, tõlgime kasutajate tagasiside vastuvõtukriteeriumideks ja kinnitame tulemused. Kui agent hätta jääb, käsitleme seda signaalina: tuvastame, mis on puudu—tööriistad, ohjepiirid, dokumentatsioon—ja viime selle tagasi varamusse, alati nii, et Codex ise kirjutab paranduse.

Agendid kasutavad meie standardseid arendustööriistu otse. Nad toovad ülevaatuse tagasiside, vastavad otse kommentaarides, lükkavad uuendused üles ja sageli lõpetavad ja liidavad oma pull request'id.

Kuna üha suurem osa arendustsüklist kodeeriti otse süsteemi—testimine, valideerimine, ülevaatus, tagasiside käsitlemine ja taastamine—, ületas varamu hiljuti tähendusrikka lävendi, kus Codex saab uut funktsiooni otsast lõpuni juhtida.

Ühe viibaga saab agent nüüd.

• Kontrollida koodibaasi praegust seisu
• Taastada teatatud vea
• Salvestada video, mis näitab tõrget
• Rakendada paranduse
• Kontrollida parandust rakendust käivitades
• Salvestada teise video, mis demonstreerib lahendust
• Avada pull request'i
• Vastata agendi ja inimese tagasisidele
• Tuvastada ja parandada ehituse tõrked
• Eskaleerida inimesele ainult siis, kui on vaja otsustusvõimet
• Siduda muudatuse

See käitumine sõltub tugevalt selle varamu konkreetsest struktuurist ja tööriistadest ning ei tohiks eeldada, et see üldistub ilma sarnase investeeringuta—vähemalt praegu mitte.

Agendi täielik autonoomia toob kaasa ka uusi probleeme. Codex kordab varamus juba olemasolevaid mustreid, isegi kui need on ebaühtlased või mitteoptimaalsed. Aja jooksul viib see paratamatult triivimiseni.

Algselt lahendasid inimesed selle käsitsi. Meie meeskond veetis varem iga reede (20% nädalast) "tehisintellekti solgi" koristamisele. Ei ole üllatav, et see ei skaleerunud.

Selle asemel hakkasime otse varamusse kodeerima seda, mida me nimetame „kuldseteks põhimõteteks“, ja lõime korduva puhastusprotsessi. Need põhimõtted on kindlameelsed, mehaanilised reeglid, mis hoiavad koodibaasi loetava ja järjepidevana tulevaste agentide käivituste jaoks. Näiteks: (1) eelistame jagatud utiliidipakette käsitsi kirjutatud abifunktsioonidele, et hoida invariandid tsentraliseerituna, ja (2) me ei sondeeri andmeid “YOLO-stiilis” – me valideerime piire või tugineme tüübistatud SDK-dele, et agent ei saaks kogemata ehitada oletatud struktuuride peale. Regulaarselt on meil taustal Codexi ülesannete komplekt, mis otsib kõrvalekaldeid, uuendab kvaliteedihindeid ja avab sihitud refaktoreerimise pull request’e. Enamikku neist saab vähem kui minutiga üle vaadata ja automaatselt liita.

See toimib nagu prügikogumine. Tehniline võlg on nagu kõrge intressiga laen: peaaegu alati on parem seda pidevalt väikeste sammudena tagasi maksta, kui lasta sellel kuhjuda ja siis valusate sööstudena sellega tegeleda. Inimese maitse jäädvustatakse üks kord ja seejärel rakendatakse seda pidevalt igal koodireal. See võimaldab meil ka igapäevaselt halbu mustreid tuvastada ja lahendada, selle asemel et lasta neil koodibaasis päevi või nädalaid levida.

See strateegia on seni hästi toiminud kuni sisemise käivitamise ja kasutuselevõtuni OpenAI juures. Päris kasutajatele päris toote loomine aitas meie investeeringud reaalsusesse ankurdada ja suunas meid pikaajalise hooldatavuse poole.

Mida me veel ei tea, on see, kuidas arhitektuurne sidusus areneb aastate jooksul täielikult agendi genereeritud süsteemis. Me õpime endiselt, kus inimlik otsustusvõime annab kõige suurema võimenduse ja kuidas seda otsustusvõimet kodeerida, et see kumuleeruks. Me ei tea ka, kuidas see süsteem aja jooksul areneb, kuna mudelid muutuvad üha võimekamaks.

Mis on selgeks saanud: tarkvara arendamine nõuab endiselt distsipliini, kuid distsipliin avaldub rohkem tugistruktuuris kui koodis. Tööriistad, abstraktsioonid ja tagasisideahelad, mis hoiavad koodibaasi sidusana, muutuvad üha olulisemaks.

Meie kõige keerulisemad väljakutsed keskenduvad nüüd keskkondade, tagasisideahelate ja juhtimissüsteemide kujundamisele, mis aitavad agentidel saavutada meie eesmärki: luua ja hooldada keerukat, usaldusväärset tarkvara suurel skaalal.

Kuna agendid nagu Codex võtavad enda kanda üha suuremaid osi tarkvara elutsüklist, muutuvad need küsimused veelgi olulisemaks. Loodame, et mõne varase õppetunni jagamine aitab sul mõelda, kuhu oma pingutust suunata, et sa saaksid lihtsalt asju luua.