Izkoristimo prednosti inženiringa: uporaba Codexa v svetu agentov

V zadnjih petih mesecih je naša ekipa izvajala eksperiment: zgraditi in lansirati interno beta različico programskega produkta z 0 vrsticami ročno napisane kode.

Produkt ima interne dnevne uporabnike in zunanje alfa preizkuševalce. Le-ta se lansira, uvaja, se pokvari in se popravi. Razlika je v tem, da je Codex napisal vsako vrstico kode, torej aplikacijsko logiko, teste, konfiguracijo CI, dokumentacijo, opazljivost in notranja orodja. Ocenjujemo, da smo to zgradili v približno 1/10 časa, kolikor bi ga potrebovali za ročno pisanje kode.

Ljudje usmerjajo. Agenti izvajajo.

To omejitev smo namenoma izbrali, da bi zgradili tisto, kar je bilo potrebno za povečanje razvojne hitrosti za več velikostnih razredov. Za lansiranje smo imeli na voljo le nekaj tednov, končni rezultat pa je obsegal milijon vrstic kode. Da bi to dosegli, smo morali razumeti, kaj se spremeni, ko primarna naloga ekipe za programsko inženirstvo ni več pisanje kode, temveč načrtovanje okolij, določanje namena in gradnja povratnih zank, ki agentom Codex omogočajo zanesljivo delo.

Ta prispevek govori o tem, kaj smo se naučili pri gradnji povsem novega produkta z ekipo agentov, in sicer kaj se je pokvarilo, kaj se je kumulativno stopnjevalo ter kako čim bolje izkoristiti naš edini resnično redek vir: človeški čas in pozornost.

Prvi commit v prazen repozitorij je bil izveden konec avgusta 2025.

Začetno ogrodje, ki vključuje strukturo repozitorija, konfiguracijo CI, pravila formatiranja, nastavitev upravljalnika paketov in ogrodje aplikacije, je ustvaril Codex CLI z uporabo GPT‑5 na podlagi manjšega nabora obstoječih predlog. Tudi začetno datoteko AGENTS.md, ki agentom določa način dela v repozitoriju, je napisal Codex.

Ni bilo nobene že obstoječe kode, ki bi jo napisali ljudje in ki bi sistemu služila kot izhodišče. Že od začetka je repozitorij oblikoval agent.

Pet mesecev pozneje repozitorij vsebuje približno milijon vrstic kode, ki zajemajo aplikacijsko logiko, infrastrukturo, orodja, dokumentacijo in notranja orodja za razvijalce. V tem obdobju je bilo odprtih in združenih približno 1.500 pull requestov, pri čemer je majhna ekipa treh inženirjev usmerjala Codex. To pomeni povprečno prepustnost 3,5 PR zahtev za združitev sprememb na inženirja na dan, pri čemer se je prepustnost presenetljivo povečala, ko se je ekipa razširila na sedem inženirjev. Pomembno je poudariti, da ne gre za količino izhodov zaradi samih izhodov, saj je produkt interno uporabljalo več sto uporabnikov, vključno z dnevnimi naprednimi internimi uporabniki.

V celotnem procesu razvoja ljudje niso neposredno prispevali nobene kode. To je postalo osrednje vodilo ekipe: brez ročno napisane kode.

Odsotnost neposrednega človeškega kodiranja je prinesla drugačno vrsto inženirskega dela, osredotočenega na sisteme, vzpostavitev ogrodja in ustvarjanje pogojev za večji učinek.

Začetni napredek je bil počasnejši, kot smo pričakovali, ne zato, ker Codex tega ne bi zmogel, temveč zato, ker okolje ni bilo dovolj jasno opredeljeno. Agentu so manjkala orodja, abstrakcije in notranja struktura, potrebni za napredovanje proti ciljem na visoki ravni. Poglavitna naloga naše inženirske ekipe je postala omogočiti agentom opravljanje koristnega dela.

V praksi je to pomenilo, da smo se najprej poglobili v posamezne probleme: večje cilje smo razčlenili na manjše gradnike (načrtovanje, koda, pregled, testiranje itd.), agenta usmerili k izgradnji teh gradnikov ter jih nato uporabili za izvedbo zahtevnejših nalog. Ko je nekaj spodletelo, rešitev skoraj nikoli ni bila zgolj nadaljevati na enak način. Ker je bil edini način napredka ta, da delo opravi Codex, so človeški inženirji vedno vstopili v nalogo in se vprašali: »Katera zmožnost manjka in kako jo narediti formalno berljivo in izvršljivo za agenta?

Ljudje s sistemom skoraj v celoti komunicirajo prek pozivov: inženir opiše nalogo, zažene agenta in mu omogoči, da odpre pull request. Da bi PR pripeljali do zaključka, Codexu naročimo, naj svoje spremembe pregleda lokalno, zahteva dodatne specifične preglede agentov tako lokalno kot v oblaku, se odzove na povratne informacije ljudi ali agentov ter iterira v zanki, dokler vsi agentski ocenjevalniki niso zadovoljni (v praksi to pomeni zanko Ralph Wiggum⁠(odpre se v novem oknu)). Codex neposredno uporablja naša standardna razvojna orodja, kot so gh, lokalni skripti in veščine, vdelane v repozitorij, za zbiranje konteksta brez tega, da bi ljudje kopirali in lepili vsebino v vmesnik z ukazno vrstico (CLI).

Ljudje lahko pregledajo pull requeste, vendar to ni obvezno. Sčasoma smo skoraj ves napor pri pregledih preusmerili na to, da ga obravnavajo agenti med seboj.

Ko se je prepustnost kode povečala, je ozko grlo postala človeška zmogljivost zagotavljanja kakovosti. Ker je stalna omejitev človeški čas in pozornost, smo agentu dodajali nove zmožnosti tako, da smo elemente, kot so uporabniški vmesnik aplikacije, dnevniki in metrike aplikacije, naredili neposredno berljive za Codex.

Aplikacijo smo, na primer, omogočili zagnati ločeno za vsak git worktree, tako da je Codex lahko za vsako spremembo zagnal in upravljal eno instanco. V izvajalno okolje agenta smo vključili tudi Chrome DevTools Protocol ter ustvarili veščine za delo s posnetki DOM, zajemi zaslona in navigacijo. To je Codexu omogočilo reproducirati hrošče, validirati popravke in neposredno sklepati o obnašanju uporabniškega vmesnika.

Enak pristop smo uporabili pri orodjih za opazljivost. Dnevniki, metrike in sledi so Codexu na voljo prek lokalnega sklada za opazljivost, ki je za posamezen worktree začasen. Codex deluje na popolnoma izolirani različici aplikacije, vključno z njenimi dnevniki in metrikami, ki se po zaključku naloge odstranijo. Agenti lahko poizvedujejo po dnevnikih z LogQL in po metrikah s PromQL. V takšnem kontekstu postanejo pozivi, kot sta »zagotovite, da se zagon storitve zaključi v manj kot 800 ms« ali »noben razpon v teh štirih kritičnih uporabniških poteh ne preseže dveh sekund«, izvedljivi.

Redno opažamo, da posamezen zagon Codexa dela na eni nalogi več kot šest ur (pogosto medtem ko ljudje spijo).

Upravljanje konteksta je eden največjih izzivov pri zagotavljanju učinkovitosti agentov pri velikih in kompleksnih nalogah. Ena prvih lekcij, ki smo se jih naučili, je bila preprosta: Codexu je treba zagotoviti zemljevid, ne navodilnika na 1.000 straneh.

Pristop AGENTS.md⁠(odpre se v novem oknu) smo stestirali. Neuspeh je bil predvidljiv:

• Kontekst je omejen na vir. Obsežen dokument z navodili izrine nalogo, kodo in relevantno dokumentacijo, zato agent bodisi spregleda ključne omejitve bodisi začne optimizirati napačne.
• Preveč usmerjanja pomeni izgubo jasne usmeritve. Ko je vse »pomembno«, ni pomembno nič. Agenti začnejo prepoznavati vzorce zgolj lokalno, namesto da bi se namerno orientirali.
• Tak dokument hitro zastara. Monolitni priročnik se spremeni v zbirko zastarelih pravil. Agenti ne morejo razločiti, kaj še vedno velja, ljudje ga prenehajo vzdrževati, dokument pa postopoma postane moteč dejavnik.
• Težko ga je preverjati. En sam obsežen dokument ne omogoča mehanskih preverjanj (pokritost, ažurnost, odgovornost, navzkrižne povezave), zato so razhajanja neizogibna.

Torej, namesto da AGENTS.md obravnavamo kot enciklopedijo, ga obravnavamo kot kazalo vsebine.

Baza znanja repozitorija je organizirana v strukturiranem imeniku docs/, ki se obravnava kot sistem evidenc. Kratek dokument AGENTS.md (dolg približno 100 vrstic) se vključi v kontekst in služi predvsem kot zemljevid z napotili na globlje vire resnice drugje.

Dokumentacija zasnove je katalogizirana in indeksirana, vključno s stanjem preverjanja ter naborom temeljnih prepričanj, ki opredeljujejo načela delovanja, usmerjena na agente. Arhitekturna dokumentacija⁠(odpre se v novem oknu) nudi zemljevid domen na najvišji ravni in plastenje paketov. Kakovosten dokument ocenjuje vsako produktno domeno in arhitekturno plast ter spremlja vrzeli skozi čas.

Načrti se obravnavajo kot artefakti prvega razreda. Za majhne spremembe se uporabljajo efemerni lahki načrti, medtem ko se kompleksno delo zajame v izvedbenih načrtih⁠(odpre se v novem oknu) z dnevniki napredka in odločitev, ki se vključijo v repozitorij. Aktivni načrti, dokončani načrti in znani tehnični dolg so vsi verzionirani in skupaj umeščeni, kar agentom omogoča delovanje brez zanašanja na zunanji kontekst.

To omogoča postopno razkrivanje: agenti začnejo z majhno, stabilno vstopno točko in se jih uči, kje naj pogledajo naslednje, namesto da bi bili že na začetku preobremenjeni.

To uveljavljamo mehanično. Namenski linterji in opravila neprekinjene integracije (CI) validirajo, da je baza znanja posodobljena, navzkrižno povezana in pravilno strukturirana. Ponavljajoči se agent za »doc-gardening« pregleduje zastarelo ali obsolete dokumentacijo, ki ne odraža dejanskega vedenja kode, in odpira pull requeste s popravki.

Ko se je kodna baza razvijala, se je moral razvijati tudi Codexov okvir za odločitve o zasnovi.

Ker repozitorij v celoti generirajo agenti, je najprej optimiziran za Codexovo berljivost. Podobno kot ekipe izboljšujejo možnost orientacije v kodi za novozaposlene inženirje, je bil cilj naših človeških inženirjev omogočiti, da agent sklepa o celotni poslovni domeni neposredno iz samega repozitorija.

Z vidika agenta vse, do česar med izvajanjem ne more dostopati v kontekstu, učinkovito ne obstaja. Znanje, ki živi v Google Docs, nizih klepetov ali v glavah ljudi, sistemu ni dostopno. Artefakti, ki so lokalni za repozitorij in verzionirani (npr. koda, markdown, sheme, izvedbeni načrti), so vse, kar lahko vidi.

Naučili smo se, da smo morali sčasoma potiskati vedno več konteksta v repozitorij. Tista razprava v Slacku, ki je ekipo uskladila glede arhitekturnega vzorca? Če je agent ne more odkriti, je neberljiva na enak način, kot bi bila neznana novemu članu ekipe, ki se pridruži tri mesece pozneje.

Dati Codexu več konteksta pomeni organizirati in izpostaviti prave informacije, da lahko agent nad njimi sklepa, namesto da ga preobremenimo z ad hoc navodili. Podobno kot bi novega sodelavca uvajal v produktna načela, inženirske norme in kulturo ekipe (vključno s preferencami glede emojijev), to, da agentu zagotovimo te informacije, vodi do bolje usklajenega izhoda.

Ta okvir je razjasnil številne kompromise. Dali smo prednost odvisnostim in abstrakcijam, ki jih je bilo mogoče v celoti ponotranjiti in o njih sklepati znotraj repozitorija. Tehnologije, ki jih pogosto opisujejo kot »dolgočasne«, so zaradi kompozabilnosti, stabilnosti aplikacijskega programskega vmesnika (API) in zastopanosti v učnem naboru podatkov za agente praviloma lažje modelirati. V nekaterih primerih je bilo ceneje, da je agent ponovno implementiral podmnožice funkcionalnosti, kot pa da bi obšli neprozorno vedenje odvisnosti višje v verigi iz javnih knjižnic. Na primer, namesto da bi vključili generični paket v slogu p-limit, smo implementirali lastni pomožni modul map-with-concurrency: tesno je integriran z našo instrumentacijo OpenTelemetry, ima 100-odstotno pokritost s testi in se obnaša natanko tako, kot to pričakuje naše izvajalno okolje.

Prenos večjega dela sistema v obliko, ki jo lahko agent neposredno pregleduje, validira in spreminja, povečuje vzvodnost tako za Codex kot za druge agente (npr. Aardvark), ki prav tako delajo na kodni bazi.

Sama dokumentacija ne zagotavlja skladnosti kodne baze, ki jo v celoti generirajo agenti. Z uveljavljanjem invariant, ne pa z mikroupravljanjem implementacij, agentom omogočamo hitro lansirati spremembe, ne da bi pri tem spodkopali temelje sistema. Na primer, od Codexa zahtevamo, da na meji sistema razčleni oblike podatkov⁠(odpre se v novem oknu), vendar ne predpisujemo, kako naj se to izvede (modelu je očitno všeč Zod, vendar te konkretne knjižnice nismo določili).

Agenti so najučinkovitejši v okoljih s strogimi mejami in predvidljivo strukturo⁠(odpre se v novem oknu), zato smo aplikacijo zasnovali okoli togega arhitekturnega modela. Vsaka poslovna domena je razdeljena na fiksni nabor plasti, s strogo validiranimi smermi odvisnosti in omejenim naborom dovoljenih povezav. Te omejitve se mehanično uveljavljajo prek prilagojenih linterjev (ki jih je seveda generiral Codex!) in strukturnih testov.

Spodnji diagram prikazuje pravilo: znotraj vsake poslovne domene (npr. App Settings) je koda lahko odvisna le »naprej« skozi fiksni nabor plasti (Types → Config → Repo → Service → Runtime → UI). Horizontalni sistemski vidiki (avtentikacija, povezovalniki, telemetrija, programske zastavice) vstopajo prek enega samega eksplicitnega vmesnika: Providers. Vse drugo je prepovedano in se mehanično uveljavlja.

To je vrsta arhitekture, ki jo običajno odložite, dokler nimate na stotine inženirjev. Pri kodirnih agentih pa je to zgodnji predpogoj: omejitve omogočajo hitrost brez degradacije ali arhitekturnega odnašanja.

V praksi ta pravila uveljavljamo s prilagojenimi linterji in strukturnimi testi ter z majhnim naborom »invariant tehničnega okusa«. Na primer, s prilagojenimi pravili preverjanja statično uveljavljamo strukturirano beleženje, poimenovalne konvencije za sheme in tipe, omejitve velikosti datotek ter zahteve glede zanesljivosti, specifične za platformo. Ker so prilagojena pravila preverjanja, sporočila o napakah oblikujemo tako, da v kontekst agenta vnašajo navodila za odpravo težave.

V delovnem toku, ki je primarno usmerjen na človeka, bi se ta pravila lahko zdela pedantna ali omejujoča. Pri agentih pa postanejo multiplikatorji: ko so enkrat zakodirana, se hkrati uveljavljajo povsod.

Hkrati jasno določimo, kje so omejitve pomembne in kje niso. To je podobno vodenju velike inženirske platformne organizacije: meje uveljavljate centralno, avtonomijo pa dopuščate lokalno. Velik pomen pripisujete mejam, pravilnosti in ponovljivosti. Znotraj teh meja ekipam ali agentom dopuščate znatno svobodo pri izražanju rešitev.

Nastala koda se ne ujema vedno s človeškimi slogovnimi preferencami, kar je sprejemljivo. Dokler je izhod pravilen, vzdržljiv in berljiv za prihodnje zagone agenta, izpolnjuje zahtevani standard.

Človeški okus se v sistem neprekinjeno vrača kot povratna informacija. Komentarji pri pregledih, pull requesti za preoblikovanje kode in napake, vidne uporabnikom, se zajemajo kot posodobitve dokumentacije ali se neposredno zakodirajo v orodja. Ko dokumentacija ne zadošča, pravilo povzdignemo v kodo

Ko se je prepustnost Codexa povečala, so številne konvencionalne inženirske norme postale kontraproduktivne.

Repozitorij deluje z minimalnimi blokirnimi kontrolnimi točkami za združevanje. Pull requesti so kratkoživi. Občasne nestabilnosti testov se pogosto obravnavajo z naknadnimi zagoni, namesto da bi napredek nedoločno blokirali. V sistemu, kjer prepustnost agentov daleč presega človeško pozornost, so popravki poceni, čakanje pa drago.

V okolju z nizko prepustnostjo bi bilo to neodgovorno. Tu pa je to pogosto pravi kompromis.

Ko rečemo, da kodno bazo generirajo agenti Codex, mislimo vse v kodni bazi.

Agenti ustvarjajo:

• Kodo izdelka in teste
• Konfiguracijo CI in orodja za izdaje
• Interna orodja za razvijalce
• Dokumentacijo in zgodovino zasnove
• Evalvacijska ogrodja
• Komentarje pri pregledih in odzive nanje
• Skripte za upravljanje repozitorija
• Definicijske datoteke produkcijskih nadzornih plošč

Ljudje vedno ostajajo v zanki, vendar delujejo na drugačni ravni abstrakcije kot prej. Prednostno razvrščamo delo, povratne informacije uporabnikov pretvarjamo v kriterije sprejemljivosti in validiramo rezultate. Ko ima agent težave, to obravnavamo kot signal: ugotovimo, kaj manjka, naj bodo to orodja, varovalni mehanizmi ali dokumentacija, in to vrnemo v repozitorij, vedno tako, da popravek napiše Codex sam.

Agenti neposredno uporabljajo naša standardna razvojna orodja. Prevzemajo povratne informacije pri pregledih, odgovarjajo neposredno v niti, potiskajo posodobitve ter pogosto izvedejo stisnjeno združitev in združitev lastnih pull requestov.

Ker je bilo vse več razvojne zanke neposredno zakodirane v sistem, vključno s testiranjem, validacijo, pregledovanjem, obravnavo povratnih informacij in odpravljanjem, je repozitorij nedavno dosegel pomemben prag, kjer lahko Codex od začetka do konca vodi novo funkcionalnost.

Na podlagi enega samega poziva lahko agent zdaj:

• Validira trenutno stanje kodne baze
• Reproducira prijavljen hrošč
• Posname videoposnetek, ki prikazuje napako
• Implementira popravek
• Validira popravek z upravljanjem aplikacije
• Posname drugi videoposnetek, ki prikazuje odpravo
• Odpre pull request
• Se odzove na povratne informacije agentov in ljudi
• Zazna in odpravi napake pri gradnji
• Zadevo eskalira človeku le, kadar je potrebna presoja
• Združi spremembo

Takšno vedenje je močno odvisno od specifične strukture in orodij tega repozitorija in ga ni mogoče privzeti kot posplošitev brez podobne naložbe, vsaj za zdaj ne.

Popolna avtonomija agenta uvaja tudi nove težave. Codex replicira vzorce, ki že obstajajo v repozitoriju, tudi neenakomerne ali suboptimalne. Sčasoma to neizogibno vodi do odklona.

Sprva so to ljudje obravnavali ročno. Naša ekipa je vsak petek (20 % tedna) namenila čiščenju »UI-pomij«. Pričakovano se to ni izkazalo za skalabilno.

Namesto tega smo v repozitorij neposredno zakodirali tako imenovana »zlata načela« in vzpostavili ponavljajoč se postopek čiščenja. Ta načela so narekujoča razvojno strukturo, mehanična pravila, ki ohranjajo kodno zbirko berljivo in dosledno za prihodnje zagone agentov. Na primer: (1) da ohranimo centralizirane invariante, dajemo prednost skupnim paketom pomožnih funkcij pred lastnoročno napisanimi pomočniki, in (2) podatkov ne preverjamo na podlagi ugibanj ali brez validacije mej, temveč validiramo meje ali se zanašamo na tipizirane komplete za razvoj programske opreme (SDK), tako da agent ne more po naključju graditi na domnevnih strukturah podatkov. V rednem ritmu imamo nabor opravil Codex v ozadju, ki pregledujejo odstopanja, posodabljajo ocene kakovosti in odpirajo ciljno usmerjene pull requeste za preoblikovanje kode. Večino teh je mogoče pregledati v manj kot minuti in jih samodejno združiti.

To deluje kot zbiranje smeti. Tehnični dolg je kot posojilo z visoko obrestno mero: skoraj vedno je bolje, da ga neprekinjeno odplačujete v majhnih korakih, kot pa da se kopiči in se ga lotite v bolečih izbruhih. Človeški okus zajamemo enkrat, nato pa se nenehno uveljavlja v vsaki vrstici kode. To nam tudi omogoča, da slabe vzorce zaznamo in odpravimo vsak dan, namesto da jih pustimo, da se širijo po kodni bazi več dni ali tednov.

Ta strategija je za zdaj dobro delovala vse do internega zagona in uvedbe pri OpenAI-ju. Gradnja pravega produkta za prave uporabnike nam je pomagala, da smo naložbe zasidrali v realnosti in nas usmerila k dolgoročni vzdrževalnosti.

Česar še ne vemo, je, kako se arhitekturna skladnost skozi leta razvija v sistemu, ki ga v celoti generirajo agenti. Še vedno se učimo, kje človeška presoja prinaša največji vzvod in kako to presojo zakodirati, da se njen učinek kopiči. Prav tako ne vemo, kako se bo ta sistem razvijal, ko bodo modeli sčasoma še naprej postajali zmogljivejši.

Kar je postalo jasno: gradnja programske opreme še vedno zahteva disciplino, vendar se ta disciplina kaže bolj v ogrodju kot v kodi. Orodja, abstrakcije in povratne zanke, ki ohranjajo kodno bazo skladno, so vse pomembnejši.

Naši najtežji izzivi so zdaj osredotočeni na načrtovanje okolij, povratnih zank in nadzornih sistemov, ki agentom pomagajo doseči naš cilj: zgraditi in vzdrževati kompleksno, zanesljivo programsko opremo v velikem obsegu.

Ko agenti, kot je Codex, prevzemajo večje dele življenjskega cikla programske opreme, bodo ta vprašanja še pomembnejša. Upamo, da vam deljenje nekaterih zgodnjih lekcij pomaga pri sklepanju, kam vložiti svoj trud, da boste lahko samo gradili.