Harness engineering: aprofitant Codex en un món agent-first

Durant els últims cinc mesos, el nostre equip ha estat duent a terme un experiment: construir i lliurar una beta interna d’un producte de programari amb 0 línies de codi escrites manualment.

El producte té usuaris interns diaris i testers alfa externs. Es publica, es desplega, es trenca i es repara. El que és diferent és que cada línia de codi —lògica de l’aplicació, proves, configuració de CI, documentació, observabilitat i eines internes— ha estat escrita per Codex. Calculem que ho hem construït en aproximadament 1/10 del temps que hauria calgut per escriure el codi a mà.

Les persones orienten. Els agents executen.

Vam triar aquesta restricció de manera intencionada perquè construíssim allò necessari per augmentar la velocitat d’enginyeria en ordres de magnitud. Teníem setmanes per lliurar el que va acabar sent un milió de línies de codi. Per fer-ho, necessitàvem entendre què canvia quan la feina principal d’un equip d’enginyeria de programari ja no és escriure codi, sinó dissenyar entorns, especificar la intenció i construir bucles de retroalimentació que permetin als agents Codex fer feina fiable.

Aquesta publicació tracta del que hem après construint un producte completament nou amb un equip d’agents: què es va trencar, què va generar efecte compost i com maximitzar el nostre únic recurs realment escàs: el temps i l’atenció humans.

El primer commit a un repositori buit va arribar a finals d’agost de 2025.

L’esquelet inicial —estructura del repositori, configuració de CI, regles de format, configuració del gestor de paquets i framework de l’aplicació— va ser generat per Codex CLI amb GPT‑5, guiat per un petit conjunt de plantilles existents. Fins i tot el fitxer AGENTS.md inicial que indica als agents com treballar al repositori va ser escrit pel mateix Codex.

No hi havia codi preexistent escrit per humans que servís d’ancoratge al sistema. Des del principi, el repositori va ser modelat per l’agent.

Cinc mesos després, el repositori conté de l’ordre d’un milió de línies de codi entre la lògica de l’aplicació, la infraestructura, les eines, la documentació i les utilitats internes per a desenvolupadors. Durant aquest període, s’han obert i fusionat aproximadament 1.500 sol·licituds d'extracció amb un petit equip de només tres enginyers dirigint Codex. Això es tradueix en un rendiment mitjà de 3,5 PR per enginyer i dia, i sorprenentment el rendiment ha augmentat a mesura que l’equip ha crescut fins a set enginyers. És important destacar que no era producció per producció: el producte ha estat utilitzat internament per centenars d’usuaris, inclosos usuaris avançats interns diaris.

Al llarg del procés de desenvolupament, els humans no van contribuir directament amb cap codi. Això es va convertir en una filosofia central de l’equip: cap codi escrit manualment.

La manca de programació humana directa va introduir un tipus diferent de feina d’enginyeria, centrada en sistemes, bastides i palanques.

El progrés inicial va ser més lent del que esperàvem, no perquè Codex fos incapaç, sinó perquè l’entorn estava insuficientment especificat. A l’agent li faltaven les eines, abstraccions i estructura interna necessàries per avançar cap a objectius d’alt nivell. La feina principal del nostre equip d’enginyeria va passar a ser permetre que els agents fessin feina útil.

A la pràctica, això volia dir treballar en profunditat: descompondre objectius més grans en blocs més petits (disseny, codi, revisió, prova, etc.), indicar a l’agent que construís aquests blocs i utilitzar-los per desbloquejar tasques més complexes. Quan alguna cosa fallava, la solució gairebé mai no era «intenta-ho amb més força». Com que l’única manera d’avançar era aconseguir que Codex fes la feina, els enginyers humans sempre entraven a la tasca i es preguntaven: «quina capacitat falta, i com fem que sigui alhora llegible i exigible per a l’agent?»

Els humans interactuen amb el sistema gairebé exclusivament a través d’indicacions: un enginyer descriu una tasca, executa l’agent i li permet obrir una sol·licitud d'extracció. Per portar una PR fins al final, indiquem a Codex que revisi els seus propis canvis localment, demani revisions addicionals específiques d’agents tant en local com al núvol, respongui a qualsevol comentari humà o d’agent i iteri en un bucle fins que tots els agents revisors estiguin satisfets (això és, de fet, un Ralph Wiggum Loop⁠(s'obre en una finestra nova)). Codex utilitza directament les nostres eines de desenvolupament estàndard (gh, scripts locals i habilitats incrustades al repositori) per recopilar context sense que els humans hagin de copiar i enganxar res al CLI.

Els humans poden revisar les sol·licituds d'extracció, però no és obligatori. Amb el temps, hem orientat gairebé tot l’esforç de revisió perquè el gestionin agents entre ells.

A mesura que augmentava el rendiment de codi, el nostre coll d’ampolla va passar a ser la capacitat humana de QA. Com que la restricció fixa ha estat el temps i l’atenció humans, hem treballat per afegir més capacitats a l’agent fent que elements com la UI de l’aplicació, els registres i les mètriques de l’app siguin directament llegibles per Codex.

Per exemple, vam fer que l’app es pogués arrencar per cada git worktree, de manera que Codex pogués llançar i controlar una instància per canvi. També vam connectar el Chrome DevTools Protocol al runtime de l’agent i vam crear habilitats per treballar amb snapshots del DOM, captures de pantalla i navegació. Això va permetre a Codex reproduir errors, validar correccions i raonar directament sobre el comportament de la UI.

Vam fer el mateix amb les eines d’observabilitat. Els registres, les mètriques i les traces s’exposen a Codex a través d’una pila local d’observabilitat que és efímera per a qualsevol worktree concret. Codex treballa sobre una versió completament aïllada d’aquella app —incloent-hi els seus registres i mètriques, que es desmunten un cop la tasca s’ha completat. Els agents poden consultar registres amb LogQL i mètriques amb PromQL. Amb aquest context disponible, indicacions com «assegura’t que l’inici del servei es completa en menys de 800 ms» o «cap span en aquests quatre recorreguts crítics d’usuari supera els dos segons» esdevenen abordables.

Veiem regularment execucions úniques de Codex treballant en una sola tasca durant més de sis hores (sovint mentre els humans dormen).

La gestió del context és un dels reptes més grans a l’hora de fer que els agents siguin efectius en tasques grans i complexes. Una de les primeres lliçons que vam aprendre era simple: dona a Codex un mapa, no un manual d’instruccions de 1.000 pàgines.

Vam provar l’enfocament «un gran AGENTS.md⁠(s'obre en una finestra nova)». Va fallar de maneres previsibles:

• El context és un recurs escàs. Un fitxer d’instruccions gegant expulsa la tasca, el codi i la documentació rellevant; així, l’agent o bé passa per alt restriccions clau o bé comença a optimitzar per les equivocades.
• Massa orientació es converteix en no-orientació. Quan tot és «important», res no ho és. Els agents acaben fent concordança de patrons localment en lloc de navegar amb intenció.
• Es degrada a l’instant. Un manual monolític es converteix en un cementiri de regles obsoletes. Els agents no poden distingir què continua sent cert, els humans deixen de mantenir-lo i el fitxer es converteix silenciosament en una nosa atractiva.
• És difícil de verificar. Un únic bloc no es presta a comprovacions mecàniques (cobertura, vigència, propietat, enllaços creuats), així que la deriva és inevitable.

Així doncs, en lloc de tractar AGENTS.md com si fos l’enciclopèdia, el tractem com la taula de continguts.

La base de coneixement del repositori viu en un directori docs/ estructurat, tractat com el sistema de registre. Un AGENTS.md curt (aproximadament 100 línies) s’injecta en context i serveix principalment de mapa, amb punters cap a fonts de veritat més profundes en altres llocs.

La documentació de disseny està catalogada i indexada, incloent-hi l’estat de verificació i un conjunt de creences bàsiques que defineixen principis operatius agent-first. La documentació d’arquitectura⁠(s'obre en una finestra nova) proporciona un mapa de nivell superior dels dominis i de l’estratificació dels paquets. Un document de qualitat puntua cada domini de producte i cada capa arquitectònica, fent seguiment de les mancances al llarg del temps.

Els plans es tracten com a artefactes de primer nivell. Els plans lleugers i efímers s’utilitzen per a canvis petits, mentre que la feina complexa es captura en plans d’execució⁠(s'obre en una finestra nova) amb registres de progrés i de decisions que es versionen al repositori. Els plans actius, els plans completats i el deute tècnic conegut estan tots versionats i co-ubicats, cosa que permet als agents operar sense dependre de context extern.

Això permet una divulgació progressiva: els agents comencen amb un punt d’entrada petit i estable i se’ls ensenya on han de mirar després, en lloc de quedar aclaparats d’entrada.

Ho fem complir mecànicament. Linters dedicats i feines de CI validen que la base de coneixement estigui actualitzada, enllaçada creuadament i estructurada correctament. Un agent recurrent de «jardineria documental» escaneja documentació vella o obsoleta que no reflecteix el comportament real del codi i obre sol·licituds d'extracció de correcció.

A mesura que el codi evolucionava, el marc de Codex per a les decisions de disseny també havia d’evolucionar.

Com que el repositori està generat íntegrament per agents, està optimitzat primer per a la llegibilitat de Codex. De la mateixa manera que els equips busquen millorar la navegabilitat del seu codi per a noves incorporacions d’enginyeria, l’objectiu dels nostres enginyers humans era fer possible que un agent raonés sobre tot el domini de negoci directament des del mateix repositori.

Des del punt de vista de l’agent, qualsevol cosa a la qual no pugui accedir en context mentre s’executa, efectivament no existeix. El coneixement que viu a Google Docs, fils de xat o al cap de les persones no és accessible per al sistema. Els artefactes locals al repositori i versionats (p. ex., codi, markdown, esquemes, plans executables) són tot el que pot veure.

Vam aprendre que amb el temps necessitàvem empènyer cada cop més context cap al repo. Aquella discussió de Slack que va alinear l’equip sobre un patró arquitectònic? Si l’agent no la pot descobrir, és il·legible de la mateixa manera que seria desconeguda per a una nova incorporació que arribés tres mesos més tard.

Donar més context a Codex vol dir organitzar i exposar la informació adequada perquè l’agent pugui raonar-hi, en lloc d’atabalar-lo amb instruccions ad hoc. De la mateixa manera que faries l’onboarding d’un nou company sobre principis de producte, normes d’enginyeria i cultura d’equip (preferències d’emojis incloses), donar aquesta informació a l’agent condueix a una sortida més ben alineada.

Aquest marc va aclarir moltes compensacions. Vam afavorir dependències i abstraccions que es poguessin internalitzar completament i sobre les quals es pogués raonar dins del repo. Les tecnologies sovint descrites com a «avorrides» tendeixen a ser més fàcils de modelar per als agents per la seva composabilitat, estabilitat de l’API i representació al conjunt d’entrenament. En alguns casos, era més barat fer que l’agent reimplementés subconjunts de funcionalitat que no pas sortejar el comportament opac upstream de biblioteques públiques. Per exemple, en lloc d’incorporar un paquet genèric d’estil p-limit, vam implementar el nostre propi helper de map-with-concurrency: està fortament integrat amb la nostra instrumentació d’OpenTelemetry, té una cobertura de proves del 100% i es comporta exactament com espera el nostre runtime.

Portar una part més gran del sistema a una forma que l’agent pugui inspeccionar, validar i modificar directament augmenta la palanca, no només per a Codex, sinó també per a altres agents (p. ex. Aardvark) que també treballen a la base de codi.

La documentació sola no manté coherent una base de codi generada completament per agents. Fent complir invariants, no microgestionant implementacions, deixem que els agents lliurin ràpid sense soscavar els fonaments. Per exemple, exigim a Codex que analitzi les formes de les dades al límit⁠(s'obre en una finestra nova), però no som prescriptius sobre com ha de passar això (sembla que al model li agrada Zod, però no vam especificar aquella biblioteca concreta).

Els agents són més efectius en entorns amb límits estrictes i estructura previsible⁠(s'obre en una finestra nova), així que vam construir l’aplicació al voltant d’un model arquitectònic rígid. Cada domini de negoci es divideix en un conjunt fix de capes, amb direccions de dependència estrictament validades i un conjunt limitat d’arestes permeses. Aquestes restriccions es fan complir mecànicament mitjançant linters personalitzats (generats per Codex, és clar!) i proves estructurals.

El diagrama següent mostra la regla: dins de cada domini de negoci (p. ex. App Settings), el codi només pot dependre «cap endavant» a través d’un conjunt fix de capes (Types → Config → Repo → Service → Runtime → UI). Les preocupacions transversals (auth, connectors, telemetry, feature flags) entren per una única interfície explícita: Providers. Qualsevol altra cosa està prohibida i es fa complir mecànicament.

Aquest és el tipus d’arquitectura que normalment ajornes fins que tens centenars d’enginyers. Amb agents de codi, és un requisit previ primerenc: les restriccions són el que permet la velocitat sense degradació ni deriva arquitectònica.

A la pràctica, fem complir aquestes regles amb linters personalitzats i proves estructurals, a més d’un petit conjunt d’«invariants de gust». Per exemple, fem complir estàticament el logging estructurat, les convencions de noms per a esquemes i tipus, els límits de mida dels fitxers i els requisits de fiabilitat específics de plataforma amb lints personalitzats. Com que els lints són personalitzats, redactem els missatges d’error per injectar instruccions de remediació en el context de l’agent.

En un flux de treball human-first, aquestes regles poden semblar pedants o limitadores. Amb agents, es converteixen en multiplicadors: un cop codificades, s’apliquen a tot arreu alhora.

Al mateix temps, som explícits sobre on importen les restriccions i on no. Això s’assembla a dirigir una gran organització de plataforma d’enginyeria: imposar els límits centralment, permetre autonomia localment. Et preocupen profundament els límits, la correcció i la reproductibilitat. Dins d’aquests límits, permets a equips —o agents— una llibertat significativa en la manera d’expressar les solucions.

El codi resultant no sempre coincideix amb les preferències estilístiques humanes, i això està bé. Mentre la sortida sigui correcta, mantenible i llegible per a futures execucions d’agents, supera el llindar.

El gust humà es retroalimenta contínuament al sistema. Els comentaris de revisió, les sol·licituds d'extracció de refactorització i els errors visibles per a l’usuari es capturen com a actualitzacions de documentació o es codifiquen directament a les eines. Quan la documentació no és suficient, promovem la regla a codi

A mesura que augmentava el rendiment de Codex, moltes normes convencionals d’enginyeria es van tornar contraproduents.

El repositori funciona amb un mínim de portes de fusió bloquejants. Les sol·licituds d'extracció tenen una vida curta. Els flakes de proves sovint s’aborden amb execucions de seguiment en lloc de bloquejar el progrés indefinidament. En un sistema on el rendiment dels agents supera amb escreix l’atenció humana, les correccions són barates i esperar és car.

Això seria irresponsable en un entorn de baix rendiment. Aquí, sovint és la compensació adequada.

Quan diem que la base de codi és generada per agents Codex, volem dir tot el que hi ha a la base de codi.

Els agents produeixen:

• Codi de producte i proves
• Configuració de CI i eines de publicació
• Eines internes per a desenvolupadors
• Documentació i historial de disseny
• Harnesses d’avaluació
• Comentaris de revisió i respostes
• Scripts que gestionen el mateix repositori
• Fitxers de definició de dashboards de producció

Els humans sempre continuen dins del bucle, però treballen en una capa d’abstracció diferent de la d’abans. Prioritzem la feina, traduïm el feedback dels usuaris a criteris d’acceptació i validem resultats. Quan l’agent té dificultats, ho tractem com un senyal: identifiquem què falta —eines, barreres de protecció, documentació— i ho retornem al repositori, sempre fent que sigui el mateix Codex qui escrigui la correcció.

Els agents utilitzen directament les nostres eines de desenvolupament estàndard. Recuperen feedback de revisió, responen en línia, empenyen actualitzacions i sovint fan squash i fusionen les seves pròpies sol·licituds d'extracció.

A mesura que una part més gran del bucle de desenvolupament es codificava directament al sistema —proves, validació, revisió, gestió del feedback i recuperació—, el repositori va superar recentment un llindar significatiu en què Codex pot portar una nova funcionalitat d’extrem a extrem.

Amb una sola indicació, l’agent ara pot:

• Validar l’estat actual de la base de codi
• Reproduir un error reportat
• Enregistrar un vídeo demostrant la fallada
• Implementar una correcció
• Validar la correcció controlant l’aplicació
• Enregistrar un segon vídeo demostrant la resolució
• Obrir una sol·licitud d'extracció
• Respondre al feedback d’agents i humans
• Detectar i corregir fallades de build
• Escalar a un humà només quan cal judici
• Fusionar el canvi

Aquest comportament depèn en gran mesura de l’estructura i les eines específiques d’aquest repositori i no s’hauria de suposar que es generalitza sense una inversió similar, almenys, encara no.

L’autonomia completa dels agents també introdueix problemes nous. Codex replica patrons que ja existeixen al repositori, fins i tot si són irregulars o subòptims. Amb el temps, això porta inevitablement a la deriva.

Inicialment, els humans ho abordaven manualment. El nostre equip solia passar cada divendres (el 20% de la setmana) netejant «AI slop». Com era d’esperar, això no escalava.

En lloc d’això, vam començar a codificar allò que anomenem «principis daurats» directament al repositori i vam construir un procés recurrent de neteja. Aquests principis són regles mecàniques i deliberades que mantenen la base de codi llegible i coherent per a futures execucions d’agents. Per exemple: (1) preferim paquets d’utilitats compartides a helpers fets a mà per mantenir els invariants centralitzats, i (2) no sondegem dades «a l’estil YOLO» —validem els límits o ens basem en SDK tipats perquè l’agent no pugui construir accidentalment sobre formes deduïdes. Amb una cadència regular, tenim un conjunt de tasques de fons de Codex que escanegen desviacions, actualitzen graus de qualitat i obren sol·licituds d'extracció de refactorització dirigides. La majoria d’aquestes es poden revisar en menys d’un minut i fusionar-se automàticament.

Això funciona com una recollida d’escombraries. El deute tècnic és com un préstec amb interessos alts: gairebé sempre és millor amortitzar-lo contínuament en petits increments que deixar que es capitalitzi i afrontar-lo en esclats dolorosos. El gust humà es captura una vegada i després es fa complir contínuament a cada línia de codi. Això també ens permet detectar i resoldre patrons dolents diàriament, en lloc de deixar que s’escampin per la base de codi durant dies o setmanes.

Aquesta estratègia ens ha funcionat bé fins ara, fins al llançament intern i l’adopció a OpenAI. Construir un producte real per a usuaris reals ens ha ajudat a ancorar les nostres inversions a la realitat i a orientar-nos cap a la mantenibilitat a llarg termini.

El que encara no sabem és com evoluciona la coherència arquitectònica al llarg dels anys en un sistema generat completament per agents. Encara estem aprenent on el judici humà aporta més palanca i com codificar aquest judici perquè generi efecte compost. Tampoc no sabem com evolucionarà aquest sistema a mesura que els models continuïn esdevenint més capaços amb el temps.

El que ha quedat clar és això: construir programari continua exigint disciplina, però la disciplina es manifesta més en les bastides que no pas en el codi. Les eines, abstraccions i bucles de retroalimentació que mantenen coherent la base de codi són cada cop més importants.

Els nostres reptes més difícils ara se centren a dissenyar entorns, bucles de retroalimentació i sistemes de control que ajudin els agents a assolir el nostre objectiu: construir i mantenir programari complex i fiable a escala.

A mesura que agents com Codex assumeixin parts més grans del cicle de vida del programari, aquestes preguntes seran encara més importants. Esperem que compartir algunes lliçons inicials us ajudi a raonar sobre on invertir el vostre esforç perquè pugueu simplement construir coses.