Ingineria sistemelor: valorificarea Codex într-o lume a agenților

În ultimele cinci luni, echipa noastră a derulat un experiment: a construit și a lansat o versiune beta internă a unui produs software cu 0 linii de cod scrise manual.

Produsul are utilizatori zilnici interni și testeri alfa externi. Se lansează, se implementează, se strică și se repară. Diferența este că fiecare linie de cod — logica aplicației, testele, configurația CI, documentația, observabilitatea și instrumentele interne — a fost scrisă de Codex. Estimăm că am realizat acest lucru în aproximativ 1/10 din timpul necesar pentru a scrie codul manual.

Oamenii conduc. Agenții execută.

Am ales intenționat această constrângere pentru a construi ceea ce era necesar pentru a crește viteza de proiectare cu ordine de mărime. Am avut la dispoziție săptămâni întregi să livrăm ceea ce s-a dovedit a fi un milion de linii de cod. Pentru a face asta, trebuia să înțelegem ce se schimbă atunci când sarcina principală a unei echipe de inginerie software nu mai este să scrie cod, ci să proiecteze medii, să specifice intenția și să construiască bucle de feedback care să le permită agenților Codex să realizeze o activitate fiabilă.

Această postare este despre ce am învățat construind un produs complet nou cu o echipă de agenți — ce s-a stricat, ce s-a amplificat și cum să ne maximizăm singura resursă cu adevărat rară: timpul și atenția umană.

Primul commit către un depozit gol a avut loc la sfârșitul lunii august 2025.

Arhitectura inițială — structura depozitului, configurația CI, regulile de formatare, configurarea managerului de pachete și cadrul aplicației — a fost generată de Codex CLI folosind GPT‑5, în baza unui set redus de șabloane existente. Chiar și fișierul inițial AGENTS.md, care le arată agenților cum să lucreze în depozit, a fost scris de Codex.

Nu a existat niciun cod scris de oameni care să ancoreze sistemul. Încă de la început, depozitul a fost definit de agent.

Cinci luni mai târziu, depozitul conține aproximativ un milion de linii de cod, acoperind logica aplicației, infrastructura, instrumentele, documentația și utilitarele interne pentru dezvoltatori. Pe parcursul acelei perioade, aproximativ 1.500 de pull requesturi au fost deschise și îmbinate de o echipă mică formată din doar trei ingineri care conduc Codex. Aceasta se traduce printr-un randament mediu de 3,5 PRs per inginer pe zi, și, în mod surprinzător, randamentul a crescut pe măsură ce echipa a ajuns să includă șapte ingineri. Un aspect important este că acest rezultat nu a fost obținut fără un scop anume: produsul a fost utilizat de sute de utilizatori interni, inclusiv de utilizatori interni avansați care îl folosesc zilnic.

Pe parcursul procesului de dezvoltare, oamenii nu au contribuit deloc în mod direct cu cod. Aceasta a devenit o filozofie de bază pentru echipă: fără cod scris manual.

Lipsa programării practice cu participare umană a introdus un alt tip de muncă de inginerie, axată pe sisteme, structuri de sprijin și utilizarea eficientă a resurselor.

Progresul inițial a fost mai lent decât ne așteptam, nu pentru că Codex era incapabil, ci pentru că mediul nu era suficient de bine definit. Agentul nu dispunea de instrumentele, abstracțiile și structura internă necesare pentru a progresa către obiective de nivel înalt. Sarcina principală a echipei noastre de ingineri a devenit să le permită agenților să facă o muncă utilă.

În practică, aceasta însemna lucrul în profunzime: descompunerea obiectivelor mai mari în blocuri de construcție mai mici (proiectare, cod, revizuire, testare etc.), îndemnarea agentului să construiască acele blocuri și utilizarea lor pentru a debloca sarcini mai complexe. Când ceva nu a funcționat, soluția nu a fost aproape niciodată „să te străduiești mai mult”. Deoarece singura modalitate de a progresa era să-l determinăm pe Codex să lucreze, inginerii umani interveneau întotdeauna și întrebau: „Ce capacitate lipsește și cum putem face ca aceasta să fie atât lizibilă, cât și aplicabilă pentru agent?”

Oamenii interacționează cu sistemul aproape în întregime prin solicitări: un inginer descrie o sarcină, rulează agentul și îi permite să deschidă un pull request. Pentru a finaliza un PR, îl instruim pe Codex să-și revizuiască modificările local, să ceară recenzii suplimentare de la agenți atât local, cât și în cloud, să răspundă la orice feedback de la oameni sau agenți și să repete procesul într-o buclă până când toți agenții evaluatori sunt mulțumiți (practic, aceasta este o buclă Ralph Wiggum⁠(se deschide într-o fereastră nouă)). Codex folosește direct instrumentele noastre standard de dezvoltare (gh, scripturi locale și abilități încorporate în depozit) pentru a aduna context fără ca oamenii să copieze și să lipească în CLI.

Oamenii pot revizui pull requesturile, dar nu sunt obligați să o facă. De-a lungul timpului, am concentrat aproape tot efortul de evaluare asupra unei relații directe între agenți.

Pe măsură ce randamentul codului a crescut, obstacolul nostru a devenit capacitatea umană de QA. Deoarece constrângerea fixă a constat în timpul și atenția umane, ne-am străduit să-i adăugăm mai multe capacități agentului, astfel încât interfața utilizatorului aplicației, jurnalele și indicatorii aplicației să fie direct lizibile pentru Codex.

De exemplu, am făcut aplicația bootabilă pentru fiecare arbore de lucru git, astfel încât Codex să poată lansa și rula o instanță pentru fiecare modificare. De asemenea, am integrat protocolul Chrome DevTools în runtime-ul agentului și am creat competențe pentru lucrul cu instantanee DOM, capturi de ecran și navigare. Acest lucru i-a permis lui Codex să reproducă buguri, să valideze remedieri și să dezvolte un raționament direct despre comportamentul interfeței de utilizare.

Am procedat la fel și în cazul instrumentelor de observabilitate. Jurnalele, indicatorii și urmele sunt expuse la Codex prin intermediul unei stive de observabilitate locală care este efemeră pentru orice arbore de lucru dat. Codex funcționează pe o versiune complet izolată a acelei aplicații, inclusiv jurnalele și indicatorii săi, care sunt demontate odată ce sarcina este finalizată. Agenții pot interoga jurnalele cu LogQL și indicatorii cu PromQL. Cu acest context disponibil, solicitări precum „asigură-te că pornirea serviciului se finalizează în mai puțin de 800 ms” sau „niciun interval din aceste patru călătorii critice ale utilizatorilor nu depășește două secunde” devin abordabile.

Vedem frecvent cum o rulare Codex lucrează la o sarcină unică timp de mai mult de șase ore (adesea în timp ce oamenii dorm).

Gestionarea contextului este una dintre cele mai mari provocări în ceea ce privește eficiența agenților în sarcini mari și complexe. Una dintre primele lecții pe care le-am învățat a fost simplă: oferă-i lui Codex o hartă, nu un manual de instrucțiuni de 1.000 de pagini.

Am încercat abordarea „un singur AGENTS.md⁠(se deschide într-o fereastră nouă) mare”. A eșuat în moduri previzibile:

• Contextul este o resursă rară. Un fișier de instrucțiuni gigantic aglomerează sarcina, codul și documentele relevante, astfel încât agentul fie ratează constrângerile cheie, fie începe să optimizeze pentru cele greșite.
• Prea multă îndrumare devine neîndrumare. Când totul este „important”, nimic nu mai contează. Agenții ajung să asocieze modele la nivel local, în loc să navigheze în mod intenționat.
• Se strică instantaneu. Un manual monolitic se transformă într-un cimitir de reguli învechite. Agenții nu-și mai dau seama ce este adevărat, oamenii nu mai întrețin informația, iar fișierul devine treptat o povară atractivă.
• E dificil de verificat. Un singur blob nu se pretează la verificări mecanice (acoperire, prospețime, responsabilitate, linkuri încrucișate), așa că deviația este inevitabilă.

Așadar, în loc să tratăm AGENTS.md ca pe o enciclopedie, îl tratăm ca pe un cuprins.

Baza de cunoștințe a depozitului se află într-un director structurat docs/, considerat ca sistem de referință. Un fișier AGENTS.md scurt (aproximativ 100 de linii) este introdus în context și servește în principal ca o hartă, cu referințe către surse mai detaliate ale adevărului din alte părți.

Documentația de design este catalogată și indexată, inclusiv starea de verificare și un set de convingeri fundamentale care definesc principiile de operare orientate pe agent. Documentația de arhitectură⁠(se deschide într-o fereastră nouă) oferă o hartă de nivel înalt a domeniilor și stratificării pachetelor. Un document de calitate notează fiecare domeniu de produs și strat arhitectural, urmărind lacunele de-a lungul timpului.

Planurile sunt considerate artefacte de primă clasă. Planurile efemere și ușoare sunt folosite pentru modificări mici, în timp ce munca complexă este consemnată în planuri de execuție⁠(se deschide într-o fereastră nouă) cu jurnale de progres și decizii care sunt înregistrate în depozit. Planurile active, planurile finalizate și datoriile tehnice cunoscute sunt toate versionate și colocate, permițându-le agenților să funcționeze fără a se baza pe context extern.

Acest lucru permite dezvăluirea progresivă: agenții încep cu un punct de intrare mic și stabil și sunt învățați unde să se uite în continuare, în loc să fie copleșiți de la început.

Aplicăm acest lucru în mod mecanic. Linterele dedicate și operațiunile CI validează faptul că baza de cunoștințe este actualizată, interconectată și structurată corect. Un agent recurent de „doc-gardening” scanează documentația învechită sau depășită, care nu reflectă comportamentul real al codului, și deschide pull requesturi de remediere.

Pe măsură ce baza de cod a evoluat, cadrul de lucru al Codex pentru deciziile de design a trebuit să evolueze și el.

Deoarece depozitul este generat în întregime de agent, este optimizat în primul rând pentru lizibilitatea Codex. La fel cum echipele urmăresc să îmbunătățească navigabilitatea codului lor pentru noii ingineri angajați, obiectivul inginerilor noștri a fost să facă posibil ca un agent să poată dezvolta un raționament despre întregul domeniu de afaceri direct din depozit.

Din punctul de vedere al agentului, orice lucru pe care nu îl poate accesa în context în timp ce rulează efectiv nu există. Cunoștințele care se află în Google Docs, în fire de discuție sau în mintea oamenilor nu sunt accesibile sistemului. Nu poate vedea decât artefactele locale din depozit, versionate (de exemplu, cod, marcaje, scheme, planuri executabile).

Am aflat că trebuie să introducem din ce în ce mai mult context în depozit în timp. Discuția aceea pe Slack care a aliniat echipa asupra unui model arhitectural? Dacă agentul nu poate să o descopere, aceasta este ilizibilă, la fel cum ar fi necunoscută pentru un nou angajat care se alătură echipei trei luni mai târziu.

A-i oferi lui Codex mai mult context înseamnă să organizezi și expui informațiile potrivite, astfel încât agentul să poată dezvolta un raționament, în loc să-l copleșești cu instrucțiuni ad-hoc. La fel cum ai instrui un nou coleg cu privire la principiile produsului, normele de inginerie și cultura echipei (inclusiv preferințele în materie de emoji), și agentul va obține rezultate mai bune dacă îi oferi aceste informații.

Această încadrare a clarificat multe compromisuri. Am preferat dependențele și abstracțiile care puteau fi internalizate complet și analizate în cadrul depozitului. Tehnologiile deseori descrise ca fiind „plictisitoare” tind să fie mai ușor de modelat de către agenți datorită componenței, stabilității API și reprezentării în setul de instruire. În unele cazuri, a fost mai ieftin ca agentul să reimplementeze subseturi de funcționalități decât să ocolească comportamentul opac din amonte al bibliotecilor publice. De exemplu, în loc să folosim un pachet generic de tip p-limit, am implementat propriul nostru ajutor map-with-concurrency: este strâns integrat cu instrumentarea noastră OpenTelemetry, are acoperire de testare 100% și se comportă exact așa cum se așteaptă runtime-ul nostru.

Transformarea unei părți mai mari a sistemului într-o formă pe care agentul o poate inspecta, valida și modifica direct crește gradul de influență — nu doar pentru Codex, ci și pentru alți agenți (de exemplu, Aardvark) care lucrează și la baza de cod.

Documentația în sine nu poate menține coerența unei baze de cod generate integral de agenți. Prin aplicarea invariantelor, fără a microgestiona implementările, le permitem agenților să livreze rapid, fără a submina fundația. De exemplu, îi cerem lui Codex să analizeze formele datelor la limită⁠(se deschide într-o fereastră nouă), dar nu suntem prescriptivi cu privire la modul în care se întâmplă asta (modelul pare să prefere Zod, dar nu am specificat acea bibliotecă anume).

Agenții au cea mai mare eficacitate în mediile cu limite stricte și o structură previzibilă⁠(se deschide într-o fereastră nouă), așa că am construit aplicația în jurul unui model arhitectural rigid. Fiecare domeniu de afaceri este împărțit într-un set fix de straturi, cu direcții de dependență strict validate și un set limitat de margini permise. Aceste constrângeri sunt impuse mecanic prin lintere personalizate (generate de Codex, desigur!) și teste structurale.

Diagrama de mai jos prezintă regula: în cadrul fiecărui domeniu de afaceri (de exemplu Setările aplicației), codul poate depinde doar „înainte” printr-un set fix de straturi (Types → Config → Repo → Service → Runtime → UI). Preocupările transversale (autentificare, conectori, telemetrie, semnalizări de funcții) intră printr-o singură interfață explicită: Providers. Orice altceva este interzis și impus mecanic.

Acesta este genul de arhitectură pe care, de obicei, o amâni până când ai sute de ingineri. Cu agenții de programare, este o condiție prealabilă timpurie: constrângerile sunt cele care permit viteza fără degradare sau deviere arhitecturală.

În practică, aplicăm aceste reguli cu lintere personalizate și teste structurale, plus un mic set de „invariante de gust”. De exemplu, aplicăm în mod static înregistrarea structurată în jurnal, convențiile de denumire pentru scheme și tipuri, limitele de dimensiune ale fișierelor și cerințele de fiabilitate specifice platformei cu ajutorul unor lintere personalizate. Pentru că linterele sunt personalizate, scriem mesajele de eroare pentru a injecta instrucțiuni de remediere în contextul agentului.

Într-un flux de lucru centrat pe oameni, aceste reguli ar putea părea pedante sau restrictive. Cu ajutorul agenților, devin factori multiplicatori: odată codificate, se aplică simultan peste tot.

Totodată, precizăm clar unde contează constrângerile și unde nu. Acest lucru seamănă cu conducerea unei mari organizații de platformă de inginerie: se impun limite la nivel central, se permite autonomia la nivel local. Limitele, corectitudinea și reproductibilitatea sunt foarte importante. În cadrul acestor limite, le permiți echipelor — sau agenților — o libertate semnificativă în modul de exprimare a soluțiilor.

Codul rezultat nu se potrivește întotdeauna cu preferințele stilistice ale oamenilor, și asta e în regulă. Dacă rezultatul este corect, ușor de întreținut și lizibil pentru viitoarele rulări ale agentului, îndeplinește cerințele.

Preferințele umane sunt integrate continuu în sistem. Comentariile de revizuire, pull requesturile de refactorizare și bugurile orientate către utilizator sunt capturate ca actualizări ale documentației sau codificate direct în instrumente. Când documentația nu este suficientă, transpunem regula în cod

Pe măsură ce randamentul Codex a crescut, multe norme convenționale de inginerie au devenit contraproductive.

Depozitul funcționează cu porți de îmbinare minime de blocare. Pull requesturile sunt de scurtă durată. Fluctuațiile testelor sunt adesea rezolvate prin rulări suplimentare, mai degrabă decât să blocheze progresul pe termen nedefinit. Într-un sistem în care randamentul agenților depășește cu mult atenția umană, corecțiile sunt ieftine, iar așteptarea este costisitoare.

Acest lucru ar fi iresponsabil într-un mediu cu randament redus. Aici, este adesea compromisul potrivit.

Când spunem că baza de cod este generată de agenții Codex, ne referim la tot ceea ce se află în baza de cod.

Agenții produc:

• Codul produsului și testele
• Instrumente de configurare și lansare CI
• Instrumentele interne pentru dezvoltatori
• Documentație și istoricul designului
• Sisteme de evaluare
• Comentarii și răspunsuri la revizuiri
• Scripturile care gestionează depozitul propriu-zis
• Fișierele de definiție pentru tabloul de bord de producție

Oamenii rămân mereu implicați, dar lucrează la un alt nivel de abstractizare decât înainte. Punem accentul pe muncă, transformăm feedbackul utilizatorilor în criterii de acceptare și validăm rezultatele. Când agentul are dificultăți, tratăm problema ca pe un semnal: identificăm ce lipsește — instrumente, măsuri de siguranță, documentație — și o reintroducem în depozit, întotdeauna prin intermediul lui Codex, care scrie remedierea singur.

Agenții folosesc instrumentele noastre standard de dezvoltare în mod direct. Ei preiau feedbackul de revizuire, răspund direct, trimit actualizări și adesea comprimă și îmbină propriile pull requesturi.

Pe măsură ce o parte din procesul de dezvoltare a fost codificată direct în sistem — testare, validare, revizuire, gestionarea feedbackului și recuperare — depozitul a depășit recent un prag semnificativ, iar Codex poate acum gestiona o nouă funcție de la un capăt la altul.

Având la dispoziție o singură solicitare, agentul poate acum:

• Verifica starea actuală a codului
• Reproduce un bug raportat
• Înregistra un videoclip care demonstrează eroarea
• Implementa o remediere
• Valida remedierea prin rularea aplicației
• Înregistra un al doilea videoclip care demonstrează rezolvarea
• Deschide un pull request
• Răspunde la feedbackul agenților și al utilizatorilor
• Detecta și remedia erorile de compilare
• Escalada la un operator uman doar atunci când este necesară judecata
• Îmbină schimbarea

Acest comportament depinde în mare măsură de structura specifică și de instrumentele acestui depozit și nu ar trebui să se presupună că poate fi generalizat fără investiții similare — cel puțin, nu încă.

Autonomia completă a agentului introduce și probleme noi. Codex reproduce modele care există deja în depozit, chiar și cele inegale sau suboptime. În timp, acest lucru duce inevitabil la deviere.

Inițial, oamenii au abordat acest lucru manual. Echipa noastră era nevoită să-și petreacă fiecare zi de vineri (20% din săptămână) curățând „mizeria generată de IA”. Deloc surprinzător, asta nu a funcționat.

În schimb, am început să codificăm ceea ce numim „principii de aur” direct în depozit și am creat un proces de curățare recurent. Aceste principii sunt reguli mecanice, bazate pe opinii, care mențin codul lizibil și consecvent pentru rulările viitoare ale agentului. De exemplu: (1) preferăm pachetele de utilități partajate în locul unor ajutoare create manual pentru a menține invariantele centralizate și (2) nu sondăm datele în stil „YOLO” — validăm limitele sau ne bazăm pe SDK-uri tipizate, astfel încât agentul să nu poată folosi accidental forme pe ghicite. La intervale regulate, avem o serie de sarcini Codex de fundal care scanează deviațiile, actualizează calificativele de calitate și deschid cereri de extragere a refactorizării specifice. Majoritatea lor pot fi revizuite în mai puțin de un minut și îmbinate automat.

Funcționează ca și colectarea gunoiului. Datoria tehnică este ca un împrumut cu dobândă mare: este aproape întotdeauna mai bine să o rambursezi continuu, în trepte mici, decât să o lași să se acumuleze și să o abordezi în reprize dureroase. Gustul uman este captat o singură dată, apoi aplicat continuu pe fiecare linie de cod. Acest lucru ne permite, de asemenea, să identificăm și să remediem modelele problematice zilnic, în loc să le lăsăm să se răspândească în baza de cod timp de zile sau săptămâni întregi.

Această strategie a funcționat bine până acum, în urma lansării interne și adoptării la OpenAI. Dezvoltarea unui produs real pentru utilizatori reali ne-a ajutat să ne ancorăm investițiile în realitate și ne-a orientat către o capacitate de întreținere pe termen lung.

Încă nu știm cum evoluează coerența arhitecturală de-a lungul anilor într-un sistem generat în totalitate de agenți. Încă încercăm să înțelegem în ce domenii contribuie cel mai mult judecata umană și cum să codificăm această judecată pentru a o îmbunătăți. De asemenea, nu știm cum va evolua acest sistem pe măsură ce modelele devin din ce în ce mai capabile.

Un lucru este clar: dezvoltarea de software necesită în continuare disciplină, dar aceasta se manifestă mai mult în structura de bază decât în cod. Instrumentele, abstracțiile și buclele de feedback care mențin coerența bazei de cod devin din ce în ce mai importante.

Cele mai dificile provocări ale noastre se concentrează acum pe proiectarea de medii, bucle de feedback și sisteme de control care ajută agenții să ne atingă obiectivul: să dezvoltăm și întreținem software complex și fiabil la scară.

Pe măsură ce agenți precum Codex preiau porțiuni mai mari din ciclul de viață al software-ului, aceste întrebări vor deveni și mai importante. Sperăm că aceste câteva lecții inițiale te vor ajuta să hotărăști unde să-ți concentrezi eforturile, astfel încât să poți pur și simplu să creezi lucruri.