Iskoristiti inženjering: moć Codexa u svijetu uz agente br. 1.

Tijekom proteklih pet mjeseci naš je tim provodio eksperiment: izgradnja i isporuka interne beta verzije softverskog proizvoda s 0 linija ručno napisanog koda.

Proizvod ima unutarnje svakodnevne korisnike i vanjske alfa testere. Isporučuje se, implementira, kvari i popravlja. Ono što je drugačije jest da je svaka linija koda — logika primjene, testovi, CI konfiguracija, dokumentacija, nadzor i interni alati — sve to napisao je Codex. Procjenjujemo da smo ovo izradili za otprilike desetinu vremena koje bi bilo potrebno da se kôd pisao ručno.

Ljudi upravljaju. Agenti izvršavaju.

Namjerno smo odabrali to ograničenje kako bismo izgradili ono što je bilo potrebno za povećanje inženjerske brzine za redove veličine. Imali smo tjedne da isporučimo ono što je na kraju bilo milijun linija koda. Da bismo to postigli, morali smo razumjeti što se mijenja kada primarni zadatak softverskog inženjerskog tima više nije pisanje koda, već dizajniranje okruženja, specificiranje namjera i izgradnja povratnih petlji koje Codex agentima omogućuju pouzdan rad.

Ova objava govori o tome što smo naučili gradeći potpuno novi proizvod s timom agenata — što se pokvarilo, što se nagomilalo i kako maksimalno iskoristiti naš jedini doista oskudan resurs: ljudsko vrijeme i pažnja.

Prva promjena u praznom repozitoriju izvršena je krajem kolovoza 2025.

Početni kostur — struktura repozitorija, CI konfiguracija, pravila formatiranja, postavljanje upravitelja paketa i aplikacijski okvir — generiran je pomoću Codex CLI-a koristeći GPT‑5, vođen malim skupom postojećih predložaka. Čak je i početnu datoteku AGENTS.md, koja agentima daje upute kako raditi u repozitoriju, napisao Codex.

Nije postojao prethodno ljudski napisani kod kojim bi se usidrio sustav. Od samog početka, repozitorij je oblikovao agent.

Pet mjeseci kasnije, repozitorij sadrži otprilike milijun redaka koda u logici aplikacije, infrastrukturi, alatima, dokumentaciji i internim razvojnim alatima. Tijekom tog razdoblja otvoreno je i spojeno otprilike 1 500 pull requestova, a mali tim od samo tri inženjera upravljao je Codexom. To se prevodi u prosječnu propusnost od 3,5 PRs po inženjeru dnevno, i iznenađujuće, propusnost se povećala otkako je tim narastao na sada sedam inženjera. Važno je naglasiti da to nije bio rezultat radi rezultata: proizvod su interno upotrebljavale stotine korisnika, uključujući i svakodnevni interni napredni korisnici.

Tijekom cijelog razvojnog procesa ljudi nikada nisu izravno doprinijeli bilo kakav kod. To je postalo temeljna filozofija za tim: bez ručno pisanog koda.

Nedostatak praktičnog ljudskog kodiranja uveo je drugačiju vrstu inženjerskog rada, usmjerenog na sustave, potporu i iskorištavanje resursa.

Rani napredak bio je sporiji nego što smo očekivali, ne zato što Codex nije bio sposoban, već zato što je okruženje bilo nedovoljno definirano. Agentu su nedostajali alati, apstrakcije i unutarnja struktura potrebni za napredak prema ciljevima visoke razine. Glavni zadatak našeg inženjerskog tima postao je omogućiti agentima da obavljaju koristan rad.

U praksi je to značilo prvo raditi dubinski: raščlanjivati veće ciljeve na manje građevne blokove (dizajn, kod, pregled, testiranje, itd.), poticati agenta da izgradi te blokove i koristiti ih za otključavanje složenijih zadataka. Kad nešto ne bi uspjelo, rješenje gotovo nikad nije bilo „pokušaj bolje”. Budući da je jedini način za postizanje napretka bio natjerati Codex da obavi posao, ljudski inženjeri uvijek su se uključivali u zadatak i pitali: „Koja sposobnost nedostaje i kako je učiniti čitljivom i provedivom za agenta?”

Ljudi komuniciraju sa sustavom gotovo u potpunosti putem upita: inženjer opisuje zadatak, pokreće agenta i dopušta mu da otvori pull request. Kako bismo dovršili PR, dajemo Codexu uputu da lokalno pregleda vlastite promjene, zatraži dodatne specifične recenzije od agenata, kako lokalno tako i u oblaku, odgovori na sve povratne informacije koje daju ljudi ili agenti te ponavlja postupak u petlji dok svi agenti recenzenti ne budu zadovoljni (u biti, to je Ralph Wiggum Loop⁠(otvara se u novom prozoru)). Codex izravno koristi naše standardne razvojne alate (gh, lokalne skripte i vještine ugrađene u repozitorij) za prikupljanje konteksta bez potrebe da ljudi kopiraju i lijepe u CLI.

Ljudi mogu pregledavati pull requestove, ali nisu obavezni to učiniti. S vremenom smo gotovo sav napor oko pregleda usmjerili na to da se njime upravlja od agenta do agenta.

Kako je propusnost kôda rasla, naš najveći tjesnac postao je kapacitet ljudske kontrole kvalitete. Budući da su ljudsko vrijeme i pažnja bili fiksno ograničenje, radili smo na dodavanju više mogućnosti agentu tako što smo učinili da su elementi poput korisničkog sučelja aplikacije, logova i metrika aplikacije izravno čitljivi za Codex.

Na primjer, učinili smo aplikaciju pokretljivom po git radnom stablu, tako da je Codex mogao pokrenuti i upravljati jednom instancom po svakoj promjeni. Također smo integrirali Chrome DevTools Protocol u radno okruženje agenta i razvili vještine za rad s DOM snimkama, snimkama zaslona i navigacijom. To je omogućilo Codexu da reproducira pogreške, provjeri ispravke i izravno analizira ponašanje korisničkog sučelja.

Isto smo učinili i za alate za nadzor. Zapisnici, metrike i tragovi dostupni su Codexu putem lokalnog sustava za promatranje koji je privremen za bilo koje dano radno stablo. Codex radi na potpuno izoliranoj verziji te aplikacije — uključujući njezine zapisnike i metrike, koji se brišu nakon što se taj zadatak završi. Agenti mogu postavljati upite u zapisnicima pomoću LogQL-a i u metrikama pomoću PromQL-a. S tim dostupnim kontekstom, upiti poput „osigurajte da se pokretanje usluge dovrši za manje od 800 ms“ ili „nijedan raspon u ova četiri kritična korisnička putovanja ne prelazi dvije sekunde“ postaju izvedivi.

Redovito primjećujemo da pojedinačna izvođenja Codexa rade na jednom zadatku više od šest sati (često dok ljudi spavaju).

Upravljanje kontekstom jedan je od najvećih izazova za postizanje učinkovitosti agenata u velikim i složenim zadacima. Jedna od najranijih lekcija koje smo naučili bila je jednostavna: dajte Codexu kartu, a ne priručnik od 1 000 stranica.

Pokušali smo s „jednim velikim AGENTS.md⁠(otvara se u novom prozoru)” pristupom. Nije uspjelo na predvidljive načine:

• Kontekst je rijedak resurs. Golema datoteka s uputama potiskuje zadatak, kod i relevantnu dokumentaciju — tako da agent ili propusti ključna ograničenja ili počne optimizirati za pogrešna.
• Previše smjernica postaje ne-smjernica. Kada je sve „važno”, ništa nije. Agenti na kraju lokalno prepoznaju uzorke umjesto da upravljaju s namjerom.
• Odmah trune. Monolitni priručnik pretvara se u groblje zastarjelih pravila. Agenti ne mogu razaznati što je još uvijek istinito, ljudi prestanu održavati datoteku, a ona tiho postane privlačna smetnja.
• Teško je provjeriti. Jedan jedini blob ne omogućuje mehaničke provjere (pokrivenost, ažurnost, vlasništvo, unakrsne poveznice), stoga je odstupanje neizbježno.

Dakle, umjesto da AGENTS.md tretiramo kao enciklopediju, tretiramo ga kao tablicu sadržaja.

Baza znanja repozitorija nalazi se u strukturiranoj mapi docs/ koja se tretira kao sustav evidencije. Kratka datoteka AGENTS.md (otprilike 100 redaka) umeće se u kontekst i prvenstveno služi kao karta, s pokazivačima na dublje izvore informacija koji se nalaze negdje drugdje.

Dokumentacija dizajna se katalogizira i indeksira, uključujući status provjere i skup temeljnih uvjerenja koja definiraju operativna načela s agentom na prvom mjestu. Arhitektonska dokumentacija⁠(otvara se u novom prozoru) pruža pregled domena i slojeva paketa na najvišoj razini. Dokument o kvaliteti ocjenjuje svaku domenu proizvoda i arhitektonski sloj te prati nedostatke tijekom vremena.

Planovi se tretiraju kao prvorazredni artefakti. Efemerni lagani planovi koriste se za male promjene, dok se složen rad bilježi u planovima izvršenja⁠(otvara se u novom prozoru) sa zapisnicima napretka i odluka koji se pohranjuju u repozitorij. Aktivni planovi, dovršeni planovi i poznati tehnički dug verzionirani su i smješteni na istom mjestu, omogućujući agentima rad bez potrebe da se oslanjanjaju na vanjski kontekst.

Time se omogućuje postupno otkrivanje: agenti započinju s malom, stabilnom početnom točkom i uče gdje dalje tražiti, umjesto da budu preplavljeni odmah na početku.

To provodimo mehanički. Namjenski linteri i CI poslovi provjeravaju da je baza znanja ažurirana, međusobno povezana i ispravno strukturirana. Ponavljajući agent za „doc-gardening” skenira zastarjelu ili nevažeću dokumentaciju koja ne odražava stvarno ponašanje koda i otvara pull requestove za ispravke.

Kako se baza koda razvijala, i Codexov okvir za dizajnerske odluke morao se razvijati.

Budući da je repozitorij u potpunosti generiran od strane agenta, optimiziran je prvenstveno za Codexovu čitljivost. Na isti način na koji timovi nastoje poboljšati navigabilnost svojeg koda za nove inženjerske zaposlenike, cilj naših ljudskih inženjera bio je omogućiti agentu da prosuđuje o cijeloj poslovnoj domeni izravno iz repozitorija.

Iz perspektive agenta, sve čemu ne može pristupiti u kontekstu tijekom rada zapravo ne postoji. Znanje koje se nalazi u Google Docsima, razgovorima ili u glavama ljudi nije dostupno sustavu. Lokalni artefakti repozitorija s verzijama (npr., kod, Markdown, sheme, izvršni planovi) su sve što može vidjeti.

S vremenom smo shvatili da trebamo unositi sve više konteksta u repozitorij. Ona rasprava na Slacku koja je uskladila tim oko arhitektonskog uzorka? Ako agent ne može otkriti, to je nečitljivo na isti način kao što bi bilo nepoznato novom zaposleniku koji se pridružuje nekom projektu tri mjeseca kasnije.

Pružanje više konteksta Codexu znači organizirati i izložiti prave informacije kako bi agent mogao razmišljati o njima, umjesto da ga se preoptereti ad-hoc uputama. Na isti način na koji biste uveli novog člana tima u načela proizvoda, inženjerske norme i kulturu tima (uključujući preferencije za emojije), davanje agentu tih informacija dovodi do bolje usklađenog rezultata.

To uokvirivanje razjasnilo je mnoge kompromise. Dali smo prednost ovisnostima i apstrakcijama koje su se mogle u potpunosti internalizirati i o kojima se moglo raspravljati unutar repozitorija. Tehnologije koje se često opisuju kao „dosadne“ agentima je obično lakše modelirati zbog kompozabilnosti, stabilnosti API-ja i zastupljenosti u skupu za obuku. U nekim slučajevima bilo je jeftinije da agent ponovno implementira podskupove funkcionalnosti nego da se zaobilazi neprozirno ponašanje javnih biblioteka. Na primjer, umjesto da koristimo generički paket u stilu p-limit, implementirali smo vlastiti pomoćni alat za mapiranje s istodobnošću: usko je integriran s našom OpenTelemetry instrumentacijom, ima 100 % pokrivenost testovima i ponaša se točno onako kako naš runtime očekuje.

Uvođenje većeg dijela sustava u oblik koji agent može pregledati, provjeriti i izravno mijenjati povećava mogućnosti — ne samo za Codex, nego i za druge agente (npr. Aardvark) koji također rade na bazi koda.

Sama dokumentacija ne održava potpuno agentom generiranu bazu koda koherentnom. Provođenjem invarijanti, umjesto mikroupravljanja implementacijama, omogućujemo agentima brzo isporučivanje bez narušavanja temelja. Primjerice, zahtijevamo da Codex analizira oblike podataka na granici⁠(otvara se u novom prozoru), ali ne propisujemo kako će se to odviti (čini se da model preferira Zod, ali nismo specificirali tu konkretnu biblioteku).

Agenti su najučinkovitiji u okruženjima sa strogim granicama i predvidljivom strukturom⁠(otvara se u novom prozoru), stoga smo aplikaciju izgradili oko krutog arhitektonskog modela. Svaka poslovna domena podijeljena je u fiksni skup slojeva, s precizno provjerenim smjerovima ovisnosti i ograničenim skupom dopuštenih veza. Ta se ograničenja mehanički provode putem prilagođenih linterskih provjera (naravno, generiranih u Codexu!) i strukturnih testova.

Dijagram u nastavku prikazuje pravilo: unutar svake poslovne domene (npr. Postavke aplikacije), kod može ovisiti samo „unaprijed” kroz fiksni skup slojeva (Vrste→ Konfig → Repo → Usluga→ Runtime → UI). Poprečne brige (autentifikacija, konektori, telemetrija, značajke zastavica) ulaze kroz jedno jedino eksplicitno sučelje: Providers. Sve ostalo je zabranjeno i provodi se automatski.

To je vrsta arhitekture koju obično odgađate dok nemate stotine inženjera. Kod agenata za kodiranje, to je rani preduvjet: ograničenja omogućuju brzinu bez degradacije ili arhitektonskog odstupanja.

U praksi provodimo ta pravila pomoću prilagođenih lintera i strukturnih testova, uz mali skup „nepromjenjivih pravila ukusa“. Na primjer, statički provodimo strukturirano zapisivanje, konvencije imenovanja za sheme i tipove, ograničenja veličine datoteka te zahtjeve pouzdanosti specifične za platformu pomoću prilagođenih lintova. Budući da su lintovi prilagođeni, pišemo poruke o pogreškama kako bismo umetnuli upute za otklanjanje problema u kontekst agenta.

U radnom tijeku usmjerenom na ljude, ta pravila mogu se činiti sitničavim ili ograničavajućim. Uz agente, ona postaju množiteli: jednom kada se kodiraju, primjenjuju se posvuda odjednom.

Istodobno jasno navodimo gdje su ograničenja važna, a gdje nisu. To je slično kao kada vodite velike organizacije inženjerske platforme: središnje postavite granice, a lokalno omogućite autonomiju. Duboko vam je stalo do granica, točnosti i ponovljivosti. Unutar tih granica, timovima — ili agentima — dopuštate značajnu slobodu u izražavanju rješenja.

Rezultirajući kȏd ne mora uvijek odgovarati ljudskim stilskim preferencijama, i to je u redu. Sve dok je izlaz točan, održiv i čitljiv za buduća pokretanja agenta, ispunjava kriterij.

Ljudske preferencije se kontinuirano vraćaju u sustav. Komentari pregleda, refaktoriranje pull requestova i greške vidljive korisnicima bilježe se kao ažuriranja dokumentacije ili se izravno integriraju u alate. Kada dokumentacija nije dovoljna, pravilo pretvaramo u kôd

Kako se Codexova propusnost povećavala, mnoge konvencionalne inženjerske norme postale su kontraproduktivne.

Repozitorij radi s minimalnim blokirajućim preprekama za spajanje. Pull requestovi su kratkotrajni. Nestabilni testovi često se rješavaju ponovnim pokretanjima umjesto da se napredak blokira na neodređeno. U sustavu gdje propusnost agenta znatno nadmašuje ljudsku pažnju, ispravci su jeftini, a čekanje je skupo.

To bi bilo neodgovorno u okruženju s niskom propusnošću. U takvim slučajevima to je često pravi kompromis.

Kada kažemo da su kodnu bazu generirali Codex agenti, mislimo na sve u toj kodnoj bazi.

Agenti proizvode:

• šifre proizvoda i testove
• konfiguracije CI i alate za izdavanje
• interne alate za razvojne inženjere
• povijest dokumentacije i dizajna
• evaluacijske pojaseve
• komentare i odgovore na recenzije
• skripte koje upravljaju repozitorijem
• datoteke definicija produkcijske nadzorne ploče

Ljudi uvijek ostaju uključeni, ali rade na drugačijoj razini apstrakcije nego što smo to prije činili. Dajemo prednost radu, prevodimo povratne informacije korisnika u kriterije prihvaćanja i provjeravamo rezultate. Kada se agent muči, to smatramo signalom: identificiramo što nedostaje — alati, zaštitne ograde, dokumentacija — i vraćamo to u repozitorij, uvijek tako da sam Codex napiše ispravak.

Agenti izravno upotrebljavaju naše standardne razvojne alate. Oni povlače povratne informacije iz pregleda, odgovaraju izravno, guraju ažuriranja i često sami rješavaju i spajaju svoje pull requestove.

Kako se sve više razvojnog ciklusa izravno kodiralo u sustav — testiranje, validacija, pregled, obrada povratnih informacija i oporavak — repozitorij je nedavno prešao značajan prag na kojem Codex može od početka do kraja upravljati novom značajkom.

Na temelju jednog upita, agent sada može:

• provjeriti trenutačno stanje baze kôda
• ponovno stvoriti prijavljenu pogrešku
• snimiti videozapis koji prikazuje neuspjeh
• implementirati ispravak
• provjerite ispravnost popravka pokretanjem aplikacije
• snimiti drugi videozapis koji prikazuje rješenje
• otvoriti pull request
• odgovoriti na povratne informacije agenta i korisnika
• otkriti i ispraviti pogreške u izgradnji
• prenijeti problem na čovjeka samo kada je potrebna prosudba
• spojiti promjenu

Ovo ponašanje uvelike ovisi o specifičnoj strukturi i alatima ovog repozitorija te se ne bi smjelo pretpostaviti da se može generalizirati bez sličnog ulaganja — barem ne još.

Puna autonomija agenta također donosi nove probleme. Codex replicira obrasce koji već postoje u repozitoriju — čak i one neujednačene ili suboptimalne. S vremenom to neizbježno dovodi do odstupanja.

U početku su ljudi to rješavali ručno. Naš je tim nekad svaki petak (20 % tjedna) provodio čisteći „AI nered“. Nije iznenađujuće da to nije bilo moguće proširiti.

Umjesto toga, počeli smo kodirati ono što nazivamo „zlatnim načelima“ izravno u repozitorij i uspostavili ponavljajući proces čišćenja. Ta su načela stroga, mehanička pravila koja održavaju bazu koda čitljivom i dosljednom za buduće pokretanje agenta. Na primjer: (1) prednost dajemo zajedničkim pomoćnim paketima umjesto ad hoc implementiranim pomoćnim funkcijama kako bi se zajednička pravila i logika održavali centralizirano, i (2) podatke ne ispitujemo „YOLO stilom” – provjeravamo granice ili se oslanjamo na tipizirane SDK-ove kako agent ne bi slučajno gradio rješenja na pretpostavljenim strukturama podataka. U redovitim intervalima imamo skup pozadinskih zadataka Codexa koji pretražuju odstupanja, ažuriraju ocjene kvalitete i otvaraju ciljane pull requestove radi refaktoriranja. Većinu njih možete pregledati za manje od minute i automatski spojiti.

To funkcionira poput prikupljanja smeća. Tehnički dug je poput zajma s visokom kamatom: gotovo je uvijek bolje otplaćivati ga kontinuirano u malim koracima nego dopustiti da se gomila i rješavati ga u naletima. Ljudske preference se jednom zabilježe, a zatim se kontinuirano primjenjuju na svakoj liniji koda. To nam također omogućuje da svakodnevno uočavamo i rješavamo loše obrasce, umjesto da ih pustimo da se šire u bazi koda danima ili tjednima.

Ta se strategija dosad pokazala uspješnom sve do internog pokretanja i usvajanja u OpenAI. Izrada stvarnog proizvoda za stvarne korisnike pomogla je učvrstiti naša ulaganja u stvarnost i usmjeriti nas prema dugoročnoj održivosti.

Ono što još ne znamo jest kako se arhitektonska koherentnost razvija tijekom godina u sustavu potpuno generiranom od agenata. Još uvijek učimo gdje ljudska prosudba donosi najveću prednost i kako tu prosudbu kodificirati da se umnožava. Ne znamo nikako će se taj sustav razvijati dok modeli s vremenom postaju sve sposobniji.

Ono što je postalo jasno: izrada softvera i dalje zahtijeva disciplinu, ali se disciplina više očituje u pomoćnim strukturama nego u samom kôdu. Alati, apstrakcije i povratne petlje koje održavaju koherentnost baze kôda postaju sve važniji.

Naši najteži izazovi sada se odnose na dizajniranje okruženja, povratnih petlji i sustava upravljanja koji agentima pomažu ostvariti naš cilj: izgraditi i održavati složen i pouzdan softver u velikom opsegu.

Kako agenti poput Codexa preuzimaju veće dijelove životnog ciklusa softvera, ta će pitanja postati još važnija. Nadamo se da će vam dijeljenje nekih ranih lekcija pomoći da razmislite o tome u što uložiti svoj trud kako biste mogli jednostavno graditi.