Inženjering harnessa: korišćenje Codex-a u svetu usmerenom na agente

Tokom proteklih pet meseci, naš tim je sprovodio eksperiment: pravljenje i isporuku interne beta verzije softverskog proizvoda sa 0 redova ručno pisanog koda.

Proizvod ima interne svakodnevne korisnike i spoljne alfa testere. Isporučuje se, pušta u rad, kvari se i popravlja. Razlika je u tome što je svaki red koda — logika aplikacije, testovi, CI konfiguracija, dokumentacija, observabilnost i interne alatke — napisao Codex. Procena nam je da smo ovo izgradili za oko 1/10 vremena koje bi bilo potrebno da se kod napiše ručno.

Ljudi usmeravaju. Agenti izvršavaju.

Namerno smo izabrali ovo ograničenje kako bismo napravili ono što je bilo neophodno da se inženjerska brzina poveća za redove veličine. Imali smo nedelje da isporučimo ono što je na kraju postalo milion redova koda. Da bismo to postigli, morali smo da razumemo šta se menja kada primarni posao jednog tima za softverski inženjering više nije pisanje koda, već osmišljavanje okruženja, preciziranje namere i izgradnja povratnih petlji koje omogućavaju Codex agentima da rade pouzdano.

Ovaj tekst je o onome što smo naučili praveći potpuno nov proizvod sa timom agenata — šta se lomilo, šta se nadograđivalo i kako da maksimalno iskoristimo svoj jedini zaista oskudan resurs: ljudsko vreme i pažnju.

Prvi commit u prazan depo stigao je krajem avgusta 2025.

Početni kostur — struktura depoa, CI konfiguracija, pravila formatiranja, podešavanje upravljača paketima i aplikacioni okvir — generisao je Codex CLI koristeći GPT‑5, vođen malim skupom postojećih šablona. Čak je i početni fajl AGENTS.md, koji usmerava agente kako da rade u depou, napisao sam Codex.

Nije postojao prethodno napisani ljudski kod koji bi sistemu služio kao oslonac. Od samog početka, depo je oblikovao agent.

Pet meseci kasnije, depo sadrži oko milion redova koda kroz logiku aplikacije, infrastrukturu, alatke, dokumentaciju i interne alatke za programere. Tokom tog perioda, otvoreno je i spojeno oko 1.500 zahteva za pregled izmena sa malim timom od samo tri inženjera koji upravljaju Codex-om. To se prevodi u prosečnu propusnu moć od 3,5 PR-a po inženjeru dnevno, a iznenađujuće je da se propusna moć povećala kako je tim narastao na sadašnjih sedam inženjera. Važno je da to nije bio rezultat radi samog rezultata: proizvod su interno koristile stotine korisnika, uključujući svakodnevne napredne interne korisnike.

Tokom celog procesa razvoja, ljudi nikada nisu direktno doprinosili kodom. To je postalo osnovna filozofija tima: bez ručno pisanog koda.

Odsustvo neposrednog ljudskog kodiranja uvelo je drugačiju vrstu inženjerskog rada, usmerenu na sisteme, kostur i leverage.

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 specificirano. Agentu su nedostajali alati, apstrakcije i interna struktura potrebni za napredak ka ciljevima visokog nivoa. Primarni posao našeg inženjerskog tima postao je da omogući agentima da obavljaju koristan rad.

U praksi, to je značilo rad po dubini: razlaganje većih ciljeva na manje gradivne blokove (dizajn, kod, pregled, test itd.), davanje instrukcija agentu da te blokove konstruiše i njihovo korišćenje za otključavanje složenijih zadataka. Kada nešto nije uspelo, rešenje gotovo nikada nije bilo „potrudi se više”. Pošto je jedini način da se napreduje bio da Codex obavi posao, ljudski inženjeri su uvek ulazili u zadatak i pitali: „koja mogućnost nedostaje i kako da je učinimo i čitljivom i sprovedivom za agenta?”

Ljudi sa sistemom stupaju u interakciju gotovo isključivo kroz instrukcije: inženjer opiše zadatak, pokrene agenta i dozvoli mu da otvori zahtev za pregled izmena. Da bismo PR doveli do završetka, instruiramo Codex da lokalno pregleda sopstvene izmene, zatraži dodatne specifične preglede drugih agenata i lokalno i u oblaku, odgovori na sve povratne informacije ljudi ili agenata i iterira u petlji dok svi agenti recenzenti ne budu zadovoljni (u suštini, ovo je Ralph Wiggum petlja⁠(отвара се у новом прозору)). Codex direktno koristi naše standardne razvojne alate (gh, lokalne skripte i veštine ugrađene u depo) da prikupi kontekst bez toga da ljudi kopiraju i nalepljuju sadržaj u CLI.

Ljudi mogu da pregledaju zahteve za pregled izmena, ali to nije obavezno. Vremenom smo gotovo sav trud pregleda preusmerili ka tome da se obavlja agent-na-agent.

Kako je propusna moć koda rasla, naše usko grlo postao je ljudski kapacitet za QA. Pošto je fiksno ograničenje bilo ljudsko vreme i pažnja, radili smo na tome da agentu dodamo više sposobnosti tako što smo stvari poput korisničkog interfejsa aplikacije, logova i metričkih podataka same aplikacije učinili direktno čitljivim za Codex.

Na primer, omogućili smo da se aplikacija pokreće po git worktree-u, tako da Codex može da pokrene i upravlja jednom instancom po izmeni. Takođe smo Chrome DevTools Protocol povezali sa izvršnim okruženjem agenta i napravili veštine za rad sa DOM snimcima, snimcima ekrana i navigacijom. To je omogućilo Codex-u da reprodukuje bagove, proverava ispravke i direktno rezonuje o ponašanju korisničkog interfejsa.

Isto smo uradili i za alatke za observabilnost. Logovi, metrike i tragovi izloženi su Codex-u preko lokalnog observability stack-a koji je efemeran za dati worktree. Codex radi na potpuno izolovanoj verziji te aplikacije — uključujući njene logove i metrike, koji se uklanjaju kada se taj zadatak završi. Agenti mogu da upituju logove pomoću LogQL-a, a metrike pomoću PromQL-a. Sa ovim kontekstom na raspolaganju, instrukcije poput „obezbedi da se pokretanje servisa završi za manje od 800 ms” ili „nijedan span u ova četiri kritična korisnička toka ne prelazi dve sekunde” postaju izvodljive.

Redovno viđamo da jedno pokretanje Codex-a radi na jednom zadatku više od šest sati (često dok ljudi spavaju).

Upravljanje kontekstom jedan je od najvećih izazova u tome da agenti budu efikasni pri velikim i složenim zadacima. Jedna od prvih lekcija koje smo naučili bila je jednostavna: dajte Codex-u mapu, a ne priručnik sa 1.000 stranica.

Probali smo pristup „jedan veliki AGENTS.md⁠(отвара се у новом прозору)”. Nije uspeo na predvidive načine:

• Kontekst je oskudan resurs. Ogroman fajl sa uputstvima potiskuje zadatak, kod i relevantnu dokumentaciju — pa agent ili promaši ključna ograničenja ili počne da optimizuje pogrešne stvari.
• Previše smernica postaje odsustvo smernica. Kada je sve „važno”, ništa nije. Agenti na kraju lokalno prepoznaju obrasce umesto da se namerno kreću kroz sistem.
• Odmah zastareva. Monolitan priručnik pretvara se u groblje zastarelih pravila. Agenti ne mogu da razaznaju šta je i dalje tačno, ljudi prestaju da ga održavaju, a fajl tiho postaje privlačna smetnja.
• Teško ga je proveriti. Jedan jedini blok ne pogoduje mehaničkim proverama (pokrivenost, svežina, vlasništvo, unakrsne veze), pa je odstupanje neizbežno.

Zato, umesto da AGENTS.md tretiramo kao enciklopediju, tretiramo ga kao sadržaj.

Baza znanja depoa živi u strukturisanom direktorijumu docs/ koji se tretira kao sistem zapisa. Kratak AGENTS.md (otprilike 100 redova) ubacuje se u kontekst i prvenstveno služi kao mapa, sa pokazivačima na dublje izvore istine na drugim mestima.

Dokumentacija dizajna je katalogizovana i indeksirana, uključujući status verifikacije i skup osnovnih uverenja koja definišu operativne principe usmerene na agente. Dokumentacija arhitekture⁠(отвара се у новом прозору) pruža mapu domena i slojevitosti paketa na najvišem nivou. Dokument o kvalitetu ocenjuje svaki domen proizvoda i svaki arhitektonski sloj, prateći nedostatke tokom vremena.

Planovi se tretiraju kao artefakti prve klase. Efemerni laki planovi koriste se za male izmene, dok se složen rad beleži u planovima izvršavanja⁠(отвара се у новом прозору) sa dnevnicima napretka i odluka koji se prijavljuju u depo. Aktivni planovi, završeni planovi i poznati tehnički dug svi su verzionisani i smešteni zajedno, što agentima omogućava da rade bez oslanjanja na spoljašnji kontekst.

To omogućava postepeno otkrivanje: agenti počinju sa malom, stabilnom ulaznom tačkom i uče se gde dalje da gledaju, umesto da budu zatrpani informacijama unapred.

Ovo sprovodimo mehanički. Namenski linteri i CI poslovi proveravaju da li je baza znanja ažurna, unakrsno povezana i pravilno strukturisana. Ponavljajući agent za „uređivanje dokumentacije” skenira zastarelu ili prevaziđenu dokumentaciju koja ne odražava stvarno ponašanje koda i otvara zahteve za pregled izmena sa ispravkama.

Kako se baza koda razvijala, morao je da se razvija i Codex-ov okvir za odluke o dizajnu.

Zato što je depo u potpunosti generisan od strane agenata, on je prvo optimizovan za Codex-ovu čitljivost. Na isti način na koji timovi nastoje da poboljšaju snalaženje u svom kodu za novozaposlene inženjere, cilj naših ljudskih inženjera bio je da omoguće agentu da rezonuje o celom poslovnom domenu direktno iz samog depoa.

Iz perspektive agenta, sve čemu ne može da pristupi u kontekstu dok radi praktično ne postoji. Znanje koje živi u Google Docs-u, nitima razgovora ili u glavama ljudi nije dostupno sistemu. Lokalni, verzionisani artefakti u depou (npr. kod, markdown, šeme, izvršni planovi) su sve što on može da vidi.

Naučili smo da je vremenom potrebno gurati sve više konteksta u repo. Ona Slack diskusija koja je uskladila tim oko arhitektonskog obrasca? Ako agent ne može da je otkrije, ona je nečitljiva na isti način na koji bi bila nepoznata novom članu tima koji se pridružio tri meseca kasnije.

Dati Codex-u više konteksta znači organizovati i izložiti prave informacije kako bi agent mogao da rezonuje nad njima, umesto da ga zatrpamo ad hoc uputstvima. Na isti način na koji biste novog saigrača uvodili u principe proizvoda, inženjerske norme i kulturu tima (uključujući i preferencije za emodžije), davanje tih informacija agentu dovodi do bolje usklađenog izlaza.

Ovakvo uokvirivanje razjasnilo je mnoge kompromise. Davali smo prednost zavisnostima i apstrakcijama koje mogu biti potpuno internalizovane i o kojima se može rezonovati unutar repoa. Tehnologije koje se često opisuju kao „dosadne” obično je agentima lakše da modeluju zbog kompozabilnosti, stabilnosti API-ja i zastupljenosti u skupu za obuku. U nekim slučajevima bilo je jeftinije naterati agenta da ponovo implementira podskupove funkcionalnosti nego da zaobilazi neprozirno uzvodno ponašanje javnih biblioteka. Na primer, umesto da uvodimo generički paket u stilu p-limit, implementirali smo sopstveni pomoćni alat map-with-concurrency: tesno je integrisan sa našom OpenTelemetry instrumentacijom, ima 100% pokrivenost testovima i ponaša se tačno onako kako naše izvršno okruženje očekuje.

Prebacivanje sve većeg dela sistema u oblik koji agent može direktno da pregleda, proverava i menja povećava polugu — ne samo za Codex, već i za druge agente (npr. Aardvark) koji takođe rade na bazi koda.

Sama dokumentacija ne održava koherentnost baze koda koja je u potpunosti generisana od strane agenata. Sprovođenjem invarijanti, a ne mikroupravljanjem implementacijama, omogućavamo agentima da isporučuju brzo, a da pritom ne potkopavaju temelje. Na primer, zahtevamo da Codex parsira oblike podataka na granici⁠(отвара се у новом прозору), ali ne propisujemo kako se to tačno radi (čini se da model voli Zod, ali nismo naveli tu konkretnu biblioteku).

Agenti su najefikasniji u okruženjima sa strogim granicama i predvidivom strukturom⁠(отвара се у новом прозору), pa smo aplikaciju izgradili oko rigidnog arhitektonskog modela. Svaki poslovni domen podeljen je na fiksan skup slojeva, sa strogo validiranim smerovima zavisnosti i ograničenim skupom dozvoljenih veza. Ova ograničenja se mehanički sprovode preko prilagođenih lintera (koje je, naravno, generisao Codex!) i strukturnih testova.

Dijagram ispod prikazuje pravilo: unutar svakog poslovnog domena (npr. App Settings), kod može da zavisi samo „unapred” kroz fiksan skup slojeva (Types → Config → Repo → Service → Runtime → UI). Zajednički aspekti koji se presecaju kroz sistem (auth, konektori, telemetrija, feature flags) ulaze kroz jedan eksplicitan interfejs: Providers. Sve ostalo je zabranjeno i mehanički se sprovodi.

Ovo je vrsta arhitekture koju obično odlažete dok ne budete imali stotine inženjera. Sa agentima za kodiranje, to je rani preduslov: ograničenja su ono što omogućava brzinu bez propadanja ili arhitektonskog odstupanja.

U praksi, ova pravila sprovodimo pomoću prilagođenih lintera i strukturnih testova, uz mali skup „invarijanti ukusa”. Na primer, statički sprovodimo strukturisano logovanje, konvencije imenovanja za šeme i tipove, ograničenja veličine fajlova i zahteve za pouzdanošću specifične za platformu pomoću prilagođenih lint pravila. Pošto su lint pravila prilagođena, pišemo poruke o greškama tako da ubace uputstva za otklanjanje u kontekst agenta.

U toku rada usmerenom prvenstveno na ljude, ova pravila mogu delovati pedantno ili ograničavajuće. Sa agentima, ona postaju multiplikatori: kada se jednom kodifikuju, primenjuju se svuda odjednom.

Istovremeno, eksplicitno navodimo gde su ograničenja važna, a gde nisu. To podseća na vođenje velike organizacije inženjerske platforme: centralno sprovodite granice, lokalno dopuštate autonomiju. Duboko vam je stalo do granica, ispravnosti i ponovljivosti. Unutar tih granica, timovima — ili agentima — dopuštate značajnu slobodu u tome kako su rešenja izražena.

Dobijeni kod se ne poklapa uvek sa ljudskim stilskim preferencijama, i to je u redu. Sve dok je izlaz ispravan, održiv i čitljiv za buduća pokretanja agenata, ispunjava kriterijum.

Ljudski ukus se neprekidno vraća u sistem. Komentari u pregledu, refaktorisani zahtevi za pregled izmena i bagovi okrenuti korisniku beleže se kao ažuriranja dokumentacije ili se direktno kodifikuju u alatkama. Kada dokumentacija nije dovoljna, promovišemo pravilo u kod

Kako je Codex-ova propusna moć rasla, mnoge konvencionalne inženjerske norme postale su kontraproduktivne.

Repo radi sa minimalnim blokirajućim kapijama za spajanje. Zahtevi za pregled izmena kratko traju. Nestabilni testovi se često rešavaju naknadnim pokretanjima umesto da neograničeno blokiraju napredak. U sistemu u kome propusna moć agenata daleko prevazilazi ljudsku pažnju, ispravke su jeftine, a čekanje skupo.

To bi bilo neodgovorno u okruženju sa niskom propusnom moći. Ovde je to često pravi kompromis.

Kada kažemo da bazu koda generišu Codex agenti, mislimo na sve u bazi koda.

Agenti proizvode:

• Kod proizvoda i testove
• CI konfiguraciju i alatke za izdanja
• Interne alatke za programere
• Dokumentaciju i istoriju dizajna
• Harness-e za evaluaciju
• Komentare u pregledu i odgovore
• Skripte koje upravljaju samim repoom
• Datoteke sa definicijama produkcionih kontrolnih tabli

Ljudi uvek ostaju u petlji, ali rade na drugačijem nivou apstrakcije nego ranije. Dajemo prioritet poslu, prevodimo povratne informacije korisnika u kriterijume prihvatanja i proveravamo ishode. Kada agent naiđe na poteškoće, to tretiramo kao signal: identifikujemo šta nedostaje — alati, zaštitne ograde, dokumentacija — i vraćamo to u repo, uvek tako što sam Codex napiše ispravku.

Agenti direktno koriste naše standardne razvojne alate. Povlače povratne informacije iz pregleda, odgovaraju inline, šalju ažuriranja i često sami squash-uju i spajaju svoje zahteve za pregled izmena.

Kako se sve veći deo razvojne petlje direktno kodifikovao u sistem — testiranje, validacija, pregled, obrada povratnih informacija i oporavak — repo je nedavno prešao značajan prag na kome Codex može end-to-end da vodi novu funkcionalnost.

Na osnovu jedne instrukcije, agent sada može da:

• Proveri trenutno stanje baze koda
• Reprodukuje prijavljeni bag
• Snimi video koji prikazuje kvar
• Implementira ispravku
• Potvrdi ispravku upravljajući aplikacijom
• Snimi drugi video koji prikazuje razrešenje
• Otvori zahtev za pregled izmena
• Odgovori na povratne informacije agenata i ljudi
• Otkrije i otkloni neuspehe u build-u
• Eskalira ka čoveku samo kada je potreban sud
• Spoji izmenu

Ovakvo ponašanje u velikoj meri zavisi od specifične strukture i alatki ovog repoa i ne treba pretpostaviti da se može generalizovati bez sličnog ulaganja — barem ne još.

Puna autonomija agenata uvodi i nove probleme. Codex replicira obrasce koji već postoje u repou — čak i neujednačene ili suboptimalne. Vremenom to neizbežno vodi ka odstupanju.

U početku su se ljudi time bavili ručno. Naš tim je nekada svaki petak (20% nedelje) provodio čisteći „AI slop”. Nije iznenađujuće, to nije moglo da se skalira.

Umesto toga, počeli smo da ono što nazivamo „zlatnim principima” direktno kodifikujemo u repo i izgradili smo periodični proces čišćenja. Ti principi su normativna, mehanička pravila koja održavaju bazu koda čitljivom i doslednom za buduća pokretanja agenata. Na primer: (1) dajemo prednost deljenim paketima pomoćnih alata u odnosu na ručno pravljene pomoćne funkcije kako bi invarijante ostale centralizovane, i (2) ne ispitujemo podatke „YOLO stilom” — validiramo granice ili se oslanjamo na tipizirane SDK-ove kako agent ne bi slučajno gradio na pretpostavljenim oblicima. U redovnom ritmu imamo skup pozadinskih Codex zadataka koji skeniraju odstupanja, ažuriraju ocene kvaliteta i otvaraju ciljane refaktorske zahteve za pregled izmena. Većina njih može da se pregleda za manje od minuta i automatski spoji.

To funkcioniše kao prikupljanje otpada. Tehnički dug je kao zajam sa visokom kamatom: gotovo je uvek bolje da ga otplaćujete kontinuirano, u malim inkrementima, nego da ga pustite da se gomila i da ga rešavate u bolnim naletima. Ljudski ukus se beleži jednom, a zatim kontinuirano sprovodi na svakoj liniji koda. To nam takođe omogućava da loše obrasce hvatamo i rešavamo svakodnevno, umesto da ih puštamo da se šire kroz bazu koda danima ili nedeljama.

Ova strategija je za sada dobro funkcionisala sve do internog lansiranja i usvajanja u OpenAI-ju. Pravljenje stvarnog proizvoda za stvarne korisnike pomoglo je da naše investicije ostanu ukorenjene u realnosti i usmerilo nas ka dugoročnoj održivosti.

Ono što još ne znamo jeste kako se arhitektonska koherentnost razvija tokom godina u sistemu koji je u potpunosti generisan od strane agenata. Još uvek učimo gde ljudski sud donosi najveću polugu i kako da taj sud kodifikujemo tako da se nadograđuje. Takođe ne znamo kako će se ovaj sistem razvijati kako modeli vremenom budu postajali sve sposobniji.

Ono što je postalo jasno: izgradnja softvera i dalje zahteva disciplinu, ali se disciplina sada više ispoljava u kosturu nego u samom kodu. Alatke, apstrakcije i povratne petlje koje održavaju koherentnost baze koda postaju sve važnije.

Naši najteži izazovi sada se vrte oko projektovanja okruženja, povratnih petlji i upravljačkih sistema koji pomažu agentima da ostvare naš cilj: da grade i održavaju složen, pouzdan softver u velikom obimu.

Kako agenti poput Codex-a preuzimaju veće delove životnog ciklusa softvera, ova pitanja će postajati još važnija. Nadamo se da će deljenje nekih ranih lekcija pomoći da razmislite gde da uložite svoj trud kako biste mogli jednostavno da gradite stvari.