Inžinierstvo rámca: Codex v prostredí orientovanom na agenta

Počas uplynulých piatich mesiacov náš tím vykonával experiment: zostavoval a spúšťal internú beta verziu softvérového produktu s 0 riadkami manuálne napísaného kódu.

Produkt má interných denných používateľov a externých alfa testerov. Dodáva sa, nasadzuje sa, pokazí sa a opraví sa. Rozdiel je v tom, že každý riadok kódu – logika aplikácie, testy, konfigurácia CI, dokumentácia, pozorovateľnosť a interné nástroje – bol napísaný pomocou Codexu. Odhadujeme, že sme to vytvorili približne za 1/10 času, ktorý by bol potrebný na ručné napísanie kódu.

Ľudia riadia. Agenti vykonávajú.

Toto obmedzenie sme zámerne zvolili, aby sme vytvorili to, čo bolo potrebné na zvýšenie rýchlosti vývoja o niekoľko rádov. Mali sme niekoľko týždňov na to, aby sme dodali to, čo sa nakoniec ukázalo ako milión riadkov kódu. Aby sme to dosiahli, museli sme pochopiť, čo sa zmení, keď primárnou úlohou tímu softvérových inžinierov už nie je písanie kódu, ale navrhovanie prostredí, špecifikovanie zámeru a budovanie cyklu pripomienok, ktoré umožnia agentom Codexu vykonávať spoľahlivú prácu.

Tento príspevok je o tom, čo sme sa naučili pri vytváraní úplne nového produktu s tímom agentov – čo sa pokazilo, čo sa zhoršilo a ako maximalizovať náš jeden skutočne vzácny zdroj: ľudský čas a pozornosť.

Prvý commit do prázdneho repozitára bol vykonaný koncom augusta 2025.

Počiatočný scaffold – štruktúra repozitára, konfigurácia CI, pravidlá formátovania, nastavenie správcu balíkov a aplikačný rámec – bol vygenerovaný pomocou Codex CLI s použitím GPT‑5, pričom sa riadil malou sadou existujúcich šablón. Dokonca aj pôvodný súbor AGENTS.md, ktorý riadi agentov, ako pracovať v repozitári, bol sám napísaný pomocou Codexu.

Neexistoval žiadny ľuďmi napísaný kód, o ktorý by sa systém mohol oprieť. Od začiatku bol repozitár formovaný agentom.

O päť mesiacov neskôr obsahuje repozitár rádovo milión riadkov kódu, ktorý zahŕňa logiku aplikácie, infraštruktúru, nástroje, dokumentáciu a interné vývojárske nástroje. Počas tohto obdobia bolo otvorených a zlúčených približne 1 500 pull requestov s malým tímom iba troch inžinierov riadiacich Codex. To sa premieta do priemernej priepustnosti 3,5 PR na inžiniera za deň a prekvapivo sa priepustnosť zvýšila, keďže tím sa rozrástol na súčasných sedem inžinierov. Dôležité je, že nešlo o výstup len kvôli výstupu: produkt používali stovky interných používateľov vrátane každodenných interných skúsených používateľov.

Počas celého vývojového procesu ľudia nikdy priamo neprispeli žiadnym kódom. Toto sa stalo základnou filozofiou tímu: žiadny ručne písaný kód.

Nedostatok praktického ľudského kódovania priniesol iný druh inžinierskej práce, zameranej na systémy, štruktúry a efektívnosť.

Počiatočný pokrok bol pomalší, než sme očakávali, nie preto, že Codex nebol schopný, ale preto, že prostredie bolo nedostatočne špecifikované. Agentovi chýbali nástroje, abstrakcie a vnútorná štruktúra potrebná na dosiahnutie pokroku smerom k cieľom na vysokej úrovni. Hlavnou úlohou nášho inžinierskeho tímu sa stalo umožniť agentom vykonávať užitočnú prácu.

V praxi to znamenalo pracovať najprv do hĺbky: rozdeliť väčšie ciele na menšie stavebné bloky (návrh, kód, kontrola, testovanie atď.), vyzvať agenta, aby tieto bloky zostavil, a použiť ich na odomknutie zložitejších úloh. Keď niečo zlyhalo, opravou takmer nikdy nebolo „snažiť sa viac“. Keďže jediný spôsob, ako dosiahnuť pokrok, bolo prinútiť Codex, aby prácu vykonal, ľudskí inžinieri sa vždy pustili do úlohy a pýtali sa: „Aká funkcia chýba a ako zabezpečíme, aby bola pre agenta čitateľná a zároveň vykonateľná?“

Ľudia interagujú so systémom takmer výlučne prostredníctvom príkazov: inžinier opíše úlohu, spustí agenta a umožní mu otvoriť pull request. Aby sme dotiahli PR do konca, dáme Codexu pokyn, aby lokálne skontroloval svoje vlastné zmeny, vyžiadal si ďalšie špecifické kontroly agentov lokálne aj v cloude, reagoval na akúkoľvek spätnú väzbu od človeka alebo agenta a iteroval v slučke, kým nebudú všetci hodnotitelia agentov spokojní (v podstate ide o slučku Ralpha Wigguma⁠(otvorí sa v novom okne)). Codex priamo využíva naše štandardné vývojové nástroje (gh, lokálne skripty a zručnosti vložené do repozitára) na zhromažďovanie kontextu bez toho, aby ho ľudia kopírovali a vkladali do CLI.

Ľudia môžu, ale nemusia, kontrolovať pull requesty. Postupom času sme takmer všetko úsilie pri kontrolách presunuli na riešenie agent-agent.

S rastúcou priepustnosťou kódu sa našou prekážkou stala ľudská kapacita v oblasti kontroly kvality. Keďže fixným obmedzením bol ľudský čas a pozornosť, pracovali sme na pridaní ďalších funkcií agentovi tým, že sme veci, ako je používateľské rozhranie aplikácie, protokoly a samotné metriky aplikácie, sprístupnili priamo čitateľne Codexu.

Napríklad sme aplikáciu spustili podľa pracovného stromu git, takže Codex mohol spustiť a spravovať jednu inštanciu na každú zmenu. Taktiež sme do runtime agenta integrovali protokol Chrome DevTools a vytvorili schopnosti na prácu so snímkami DOM, snímkami obrazovky a navigáciou. To umožnilo Codexu reprodukovať chyby, overovať opravy a priamo uvažovať o správaní používateľského rozhrania.

To isté sme urobili pre nástroje na sledovanie pozorovateľnosti. Protokoly, metriky a stopy sú Codexu sprístupnené prostredníctvom lokálneho zásobníka pozorovateľnosti, ktorý je pre akýkoľvek daný pracovný strom dočasný. Codex pracuje na plne izolovanej verzii tejto aplikácie – vrátane jej protokolov a metrík, ktoré sa po dokončení tejto úlohy odstránia. Agenti môžu dopytovať protokoly pomocou LogQL a metriky pomocou PromQL. Vďaka tomuto kontextu sa stanú zvládnuteľnými príkazy ako „zabezpeč, aby sa spustenie služby dokončilo za menej ako 800 ms“ alebo „žiadne rozpätie v týchto štyroch kritických cestách používateľa nepresahuje dve sekundy“.

Pravidelne vidíme, ako jednotlivé spustenia Codexu pracujú na jednej úlohe viac ako šesť hodín (často zatiaľ čo ľudia spia).

Riadenie kontextu je jednou z najväčších výziev pri efektívnom vykonávaní veľkých a zložitých úloh agentmi. Jedno z prvých ponaučení, ktoré sme sa naučili, bolo jednoduché: daj Codexu mapu, nie 1 000-stranový návod na použitie.

Vyskúšali sme „jeden veľký AGENTS.md⁠(otvorí sa v novom okne)“ prístup. Zlyhalo to predvídateľným spôsobom:

• Kontext je vzácny zdroj. Obrovský súbor s inštrukciami vytláča úlohu, kód a relevantnú dokumentáciu – takže agent buď prehliadne kľúčové obmedzenia, alebo začne optimalizovať pre tie nesprávne.
• Príliš veľa usmernení sa stáva neusmernením. Keď je všetko „dôležité“, nič nie je dôležité. Agenti nakoniec namiesto zámernej navigácie porovnávajú vzory lokálne.
• Okamžite sa rozkladá. Monolitický manuál sa zmení na cintorín zastaraných pravidiel. Agenti nedokážu rozoznať, čo je stále pravdivé, ľudia prestanú súbor udržiavať a nenápadne sa stane lákavou nepríjemnosťou.
• Je ťažké to overiť. Jeden blob sa nehodí na mechanické kontroly (pokrytie, čerstvosť, vlastníctvo, krížové prepojenia), takže odklon je nevyhnutný.

Takže namiesto toho, aby sme súbor AGENTS.md považovali za encyklopédiu, považujme ho za obsah.

Znalostná báza repozitára sa nachádza v štruktúrovanom adresári docs/ ktorý sa považuje za systém záznamov. Krátky súbor AGENTS.md (zhruba 100 riadkov) je vložený do kontextu a slúži predovšetkým ako mapa s odkazmi na hlbšie zdroje pravdy inde.

Dizajnová dokumentácia je katalogizovaná a indexovaná, vrátane stavu overenia a súboru základných presvedčení, ktoré definujú princípy fungovania zamerané na agenta. Dokumentácia architektúry⁠(otvorí sa v novom okne) poskytuje mapu domén a vrstvenie balíkov na najvyššej úrovni. Dokument o kvalite hodnotí každú produktovú doménu a architektonickú vrstvu a sleduje medzery v priebehu času.

S plánmi sa zaobchádza ako s prvotriednymi artefaktmi. Efemérne odľahčené plány sa používajú na malé zmeny, zatiaľ čo komplexná práca sa zachytáva v plánoch realizácie⁠(otvorí sa v novom okne) so záznamami o priebehu a rozhodnutiach, ktoré sa ukladajú do repozitára. Aktívne plány, dokončené plány a známy technický dlh sú všetky verzované a umiestnené na jednom mieste, čo umožňuje agentom fungovať bez spoliehania sa na externý kontext.

To umožňuje postupné odhaľovanie: agenti začínajú s malým, stabilným vstupným bodom a učia sa, kde hľadať ďalej, namiesto toho, aby boli hneď na začiatku zahltení.

Toto presadzujeme mechanicky. Vyhradené lintery a úlohy CI overujú, či je znalostná báza aktuálna, prepojená a správne štruktúrovaná. Opakujúci sa agent „doc-gardening“ prehľadáva zastaranú alebo neaktuálnu dokumentáciu, ktorá neodráža skutočné správanie kódu, a otvára pull requesty na opravy.

S vývojom kódovej základne sa musel vyvíjať aj rámec Codexu pre dizajnové rozhodnutia.

Keďže repozitár je kompletne generovaný agentmi, je najprv optimalizovaný pre čitateľnosť Codexu. Rovnako ako sa tímy snažia zlepšiť navigáciu v kóde pre nových inžinierov, cieľom našich ľudských inžinierov bolo umožniť agentovi uvažovať o celej obchodnej doméne priamo zo samotného repozitára.

Z pohľadu agenta čokoľvek, k čomu nemá prístup v kontexte počas svojho behu, v podstate neexistuje. Znalosti, ktoré sa nachádzajú v Google Docs, vláknach četu alebo hlavách ľudí, nie sú pre systém prístupné. Vidí iba lokálne repozitárne artefakty s verziami (napr. kód, markdown, schémy, spustiteľné plány).

Zistili sme, že časom musíme do repozitára vkladať čoraz viac kontextu. Tá diskusia na Slacku, ktorá zosúladila tím v súvislosti s architektonickým vzorom? Ak to agent nedokáže objaviť, je to nečitateľné rovnako, ako by to bolo neznáme pre nového zamestnanca, ktorý nastúpi o tri mesiace neskôr.

Poskytnutie väčšieho kontextu pre Codex znamená organizovať a sprístupňovať správne informácie, aby ich agent mohol prehodnotiť, a nie ich zahlcovať ad-hoc pokynmi. Rovnakým spôsobom by ste zaškolili nového kolegu do produktových princípov, technických noriem a tímovej kultúry (vrátane preferencií emoji). Poskytnutie týchto informácií agentovi vedie k lepšie zosúladenému výstupu.

Toto zarámcovanie objasnilo mnohé kompromisy. Uprednostňovali sme závislosti a abstrakcie, ktoré sa dali plne internalizovať a zdôvodniť v repozitári. Technológie často označované ako „nudné“ bývajú pre agentov ľahšie modelovateľné kvôli kompozovateľnosti, stabilite API a reprezentácii v trénovacej množine. V niektorých prípadoch bolo lacnejšie, aby agent reimplementoval podmnožiny funkcií, ako obchádzať nepriehľadné upstreamové správanie z verejných knižníc. Napríklad, namiesto toho, aby sme použili generický balík v štýle p-limit, implementovali sme vlastného pomocníka map-with-concurrency: je úzko integrovaný s našou inštrumentáciou OpenTelemetry, má 100 % pokrytie testami a správa sa presne tak, ako očakáva náš runtime.

Vtiahnutie väčšej časti systému do formy, ktorú môže agent priamo kontrolovať, overovať a upravovať, zvyšuje jeho účinnosť – nielen pre Codex, ale aj pre iných agentov (napr. Aardvark), ktoré tiež pracujú na kódovej základni.

Samotná dokumentácia neudrží plne agentom generovanú kódovú základňu súdržnú. Vynucovaním invariantov, nie mikromanažmentom implementácií, umožňujeme agentom ich rýchle doručovanie bez toho, aby sme podkopali základy. Napríklad vyžadujeme, aby Codex spracovával dátové štruktúry na hranici⁠(otvorí sa v novom okne), ale nepredpisujeme, ako sa to má stať (zdá sa, že model preferuje Zod, ale tú konkrétnu knižnicu sme nešpecifikovali).

Agenti sú najúčinnejší v prostrediach s prísnymi hranicami a predvídateľnou štruktúrou⁠(otvorí sa v novom okne), preto sme aplikáciu vytvorili na pevnom architektonickom modeli. Každá obchodná doména je rozdelená do pevnej sady vrstiev s prísne validovanými smermi závislostí a obmedzenou sadou povolených hrán. Tieto obmedzenia sa vynucujú mechanicky prostredníctvom vlastných linterov (samozrejme generovaných Codexom!) a štrukturálnych testov.

Diagram nižšie znázorňuje pravidlo: v rámci každej obchodnej domény (napr. Nastavenia aplikácie) môže kód závisieť „dopredu“ iba prostredníctvom pevne stanovenej sady vrstiev (Typy → Konfigurácia → Úložisko → Služba → Runtime → UI). Prierezové záležitosti (autorizácia, konektory, telemetria, príznaky funkcií) vstupujú cez jedno explicitné rozhranie: Poskytovatelia. Čokoľvek iné je zakázané a vynucuje sa mechanicky.

Toto je typ architektúry, ktorú zvyčajne odložíte, kým nebudete mať stovky inžinierov. Pri kódovacích agentoch je to skorý predpoklad: obmedzenia sú tým, čo umožňuje rýchlosť bez degradácie alebo odklonu architektúry.

V praxi tieto pravidlá presadzujeme pomocou vlastných linterov a štrukturálnych testov, plus malej sady „chuťových invariantov“. Napríklad staticky vynucujeme štruktúrované protokolovanie, konvencie pomenovania pre schémy a typy, limity veľkosti súborov a platformovo špecifické požiadavky na spoľahlivosť pomocou vlastných linterov. Keďže lintery sú vlastné, píšeme chybové hlásenia na vloženie pokynov na nápravu do kontextu agenta.

V pracovnom postupe, v ktorom je človek na prvom mieste, sa tieto pravidlá môžu zdať pedantské alebo obmedzujúce. S agentmi sa stávajú multiplikátormi: po zakódovaní sa uplatňujú všade naraz.

Zároveň jasne uvádzame, kde sú obmedzenia dôležité a kde nie. Toto sa podobá vedeniu veľkej organizácie inžinierskej platformy: centrálne presadzovanie hraníc, lokálne umožnenie autonómie. Veľmi vám záleží na hraniciach, správnosti a reprodukovateľnosti. V rámci týchto hraníc poskytujete tímom – alebo agentom – značnú voľnosť v tom, ako sú riešenia vyjadrené.

Výsledný kód nie vždy zodpovedá ľudským štylistickým preferenciám a to je v poriadku. Pokiaľ je výstup správny, udržiavateľný a čitateľný pre budúce spustenia agentov, spĺňa požiadavky.

Ľudský vkus sa do systému neustále vracia späť. Komentáre k recenziám, žiadosti o zmeny k refaktoringu a chyby, s ktorými sa stretávajú používatelia, sa zaznamenávajú ako aktualizácie dokumentácie alebo sa kódujú priamo do nástrojov. Keď je dokumentácia nedostatočná, pravidlo prenesieme do kódu

S rastúcou priepustnosťou Codexu sa mnohé konvenčné inžinierske normy stali kontraproduktívnymi.

Repozitár funguje s minimálnymi blokovacími zlučovacími bránami. Pull requesty sú krátkodobé. Nestabilné testy (test flakes) sa často riešia následnými spusteniami namiesto toho, aby sa pokrok blokoval na neurčito. V systéme, kde priepustnosť agentov ďaleko prevyšuje ľudskú pozornosť, sú opravy lacné a čakanie je drahé.

V prostredí s nízkou priepustnosťou by to bolo nezodpovedné. Tu je to často správny kompromis.

Keď hovoríme, že kódová základňa je generovaná agentmi Codexu, myslíme tým všetko v kódovej základni.

Agenti produkujú:

• Kód produktu a testy
• Konfiguráciu CI a nástroje na vydávanie
• Interné nástroje pre vývojárov
• Dokumentáciu a históriu návrhu
• Vyhodnocovacie nástroje
• Komentáre k recenzii a odpovede
• Skripty, ktoré spravujú repozitár samotný
• Súbory definícií hlavného panelu produktov

Ľudia sú vždy v obraze, ale pracujú na inej úrovni abstrakcie, ako boli zvyknutí. Uprednostňujeme prácu, premieňame spätnú väzbu od používateľov na kritériá akceptácie a overujeme výsledky. Keď má agent problémy, berieme to ako signál: identifikujeme, čo chýba – nástroje, ochranné prvky, dokumentácia – a vrátime to späť do repozitára, vždy tak, že opravu napíše samotný Codex.

Agenti priamo používajú naše štandardné vývojové nástroje. Získavajú spätnú väzbu z recenzií, reagujú priamo na otázky, odosielajú aktualizácie a často spájajú svoje vlastné pull requesty.

Keďže sa väčšia časť vývojového cyklu kódovala priamo do systému – testovanie, validácia, kontrola, spracovanie spätnej väzby a obnova – repozitár nedávno prekročil zmysluplnú hranicu, kde Codex môže komplexne riadiť vývoj nových funkcií.

Pri zadaní jediného príkazu môže agent teraz:

• Overiť aktuálny stav kódovej základne
• Reprodukovať nahlásenú chybu
• Nahrať video demonštrujúce zlyhanie
• Implementovať opravu
• Overiť opravu spustením aplikácie
• Nahrať druhé video demonštrujúce rozlíšenie
• Otvoriť pull request
• Reagovať na spätnú väzbu od agentov a ľudí
• Zistiť a opraviť chyby zostavenia
• Eskalovať na človeka len vtedy, keď sa vyžaduje úsudok
• Zlúčiť zmenu

Toto správanie vo veľkej miere závisí od špecifickej štruktúry a nástrojov tohto repozitára a nemalo by sa predpokladať, že sa zovšeobecní bez podobných investícií – aspoň zatiaľ nie.

Plná autonómia agenta tiež prináša nové problémy. Codex replikuje vzory, ktoré už v repozitári existujú – dokonca aj tie nerovnomerné alebo neoptimálne. Postupom času to nevyhnutne vedie k odchýlke.

Spočiatku ľudia riešili tento problém manuálne. Náš tím trávil každý piatok (20 % týždňa) upratovaním „odpadu z umelej inteligencie“. Nie je prekvapením, že to nebolo možné škálovať.

Namiesto toho sme začali kódovať to, čo nazývame „zlaté princípy“, priamo do repozitára a vytvorili sme opakujúci sa proces čistenia. Tieto princípy sú subjektívne mechanické pravidlá, ktoré udržiavajú kódovú základňu čitateľnú a konzistentnú pre budúce spustenia agentov. Napríklad: 1) uprednostňujeme zdieľané balíky nástrojov pred ručne písanými pomocnými funkciami, aby sme udržali invarianty centralizované, a 2) nepreverujeme údaje tzv. „YOLO štýlom“, ale overujeme hranice alebo sa spoliehame na typované SDK, aby agent nemohol omylom stavať na odhadnutých štruktúrach. V pravidelných intervaloch máme sadu úloh Codexu na pozadí, ktoré vyhľadávajú odchýlky, aktualizujú hodnotenia kvality a otvárajú cielené refaktoringové pull requesty. Väčšinu z nich je možné skontrolovať za menej ako minútu a automaticky zlúčiť.

Toto funguje ako zber odpadu. Technický dlh je ako pôžička s vysokým úrokom: takmer vždy je lepšie splácať ho priebežne v malých čiastkach, ako nechať ho hromadiť a riešiť ho v bolestivých nárazových etapách. Ľudský vkus sa zachytí raz a potom sa priebežne uplatňuje na každom riadku kódu. To nám tiež umožňuje denne zachytávať a riešiť zlé vzorce, namiesto toho, aby sa šírili v kódovej základni celé dni alebo týždne.

Táto stratégia doteraz dobre fungovala prostredníctvom interného spustenia a prijatia v OpenAI. Vytvorenie skutočného produktu pre skutočných používateľov nám pomohlo ukotviť naše investície v realite a nasmerovať nás k dlhodobej udržiavateľnosti.

Čo zatiaľ nevieme, je, ako sa architektonická súdržnosť vyvíja v priebehu rokov v systéme, ktorý je plne generovaný agentmi. Stále sa učíme, kde ľudský úsudok pridáva najväčší vplyv a ako tento úsudok zakódovať tak, aby sa znásoboval. Taktiež nevieme, ako sa tento systém bude vyvíjať, keďže modely sa časom budú stávať stále schopnejšími.

Čo sa ukázalo: tvorba softvéru si stále vyžaduje disciplínu, ale táto disciplína sa viac prejavuje v základných konštrukciách než v kóde. Nástroje, abstrakcie a cykly pripomienok, ktoré udržiavajú kódovú základňu koherentnú, sú čoraz dôležitejšie.

Naše najťažšie výzvy sa teraz sústreďujú na navrhovanie prostredí, cyklov pripomienok a riadiacich systémov , ktoré pomáhajú agentom dosiahnuť náš cieľ: vytvárať a udržiavať komplexný a spoľahlivý softvér vo veľkom meradle.

Keďže agenti ako Codex preberajú väčšiu časť životného cyklu softvéru, tieto otázky budú ešte dôležitejšie. Dúfame, že zdieľanie niekoľkých prvých ponaučení vám pomôže premýšľať o tom, kam investovať svoje úsilie, aby ste mohli jednoducho veci budovať.