Ingeniería de sistemas: aprovechar Codex en un mundo de agentes

Durante los últimos cinco meses, nuestro equipo ha estado llevando a cabo un experimento: desarrollar y lanzar una beta interna de un producto de software sin que se haya escrito manualmente ninguna línea de código.

El producto tiene usuarios diarios internos y evaluadores alfa externos. El producto se lanza, se implementa, se rompe y se arregla. Lo que cambia aquí es que cada una de las líneas de código—lógica de la aplicación, pruebas, configuración de CI, documentación, observabilidad y herramientas internas—ha sido escrita por Codex. Calculamos que lo desarrollamos en aproximadamente una décima parte del tiempo que nos habría llevado escribir el código a mano.

Las personas dirigen. Los agentes ejecutan.

Elegimos intencionadamente esta restricción para desarrollar lo que se precisaba con el fin de aumentar la velocidad de ingeniería por órdenes de magnitud. Fue un trabajo de semanas para entregar lo que terminó siendo un millón de líneas de código. Para lograrlo, fue necesario comprender los cambios que se producen cuando la tarea principal de un equipo de ingeniería de software deja de ser escribir código para pasar a diseñar entornos, especificar intenciones y crear bucles de retroalimentación que permitan a los agentes de Codex desarrollar un trabajo fiable.

Esta publicación describe lo que aprendimos durante el proceso de creación de un producto completamente nuevo a través de un equipo de agentes: qué falló, qué se acumuló y cómo maximizar nuestro único recurso verdaderamente escaso: el tiempo y la atención humanos.

El primer commit en un repositorio vacío se realizó a finales de agosto de 2025.

La estructura inicial (repositorio, configuración de CI, reglas de formato, configuración del gestor de paquetes y marco de la aplicación) fue generado por Codex CLI usando GPT‑5, bajo la orientación de un pequeño conjunto de plantillas existentes. Incluso el archivo AGENTS.md inicial, que guía a los agentes sobre cómo trabajar en el repositorio, fue escrito por Codex.

No existía ningún código escrito por personas para fijar el sistema. Desde el principio, el repositorio fue moldeado por el agente.

Cinco meses después, el repositorio ya consta de aproximadamente un millón de líneas de código en términos de lógica de la aplicación, infraestructura, herramientas, documentación y utilidades internas para desarrolladores. Durante ese período, se abrieron y fusionaron aproximadamente 1500 pull requests, con un pequeño equipo de solo tres ingenieros a cargo de Codex. Esto se traduce en un rendimiento medio de 3,5 PR por ingeniero al día y, sorprendentemente, el rendimiento ha aumentado a medida que el equipo ha crecido hasta llegar a siete ingenieros. Es importante destacar que esto no fue fruto del mero hecho de producir: el producto ha sido utilizado internamente por cientos de usuarios, incluidos usuarios avanzados que lo usan a diario.

Durante todo el proceso de desarrollo, el equipo humano nunca aportó directamente ningún código. Esto se convirtió en una filosofía principal para todos: ningún código escrito a mano.

La ausencia de una programación humana práctica dio lugar a un tipo diferente de trabajo de ingeniería, centrado en sistemas, estructuras de soporte y aprovechamiento.

Al principio, los avances fueron más lentos de lo que esperábamos, no porque Codex fuera incapaz, sino porque el entorno no estaba bien definido. Al agente le faltaban las herramientas, las abstracciones y la estructura interna necesarias para avanzar hacia objetivos de alto nivel. La tarea principal de nuestro equipo de ingeniería fue habilitar a los agentes para realizar un trabajo útil.

En la práctica, esto implicaba un trabajo profundo: desmenuzar objetivos más amplios en bloques más pequeños (diseño, código, revisión, pruebas, etc.), pedir al agente que construyera esos bloques y utilizarlos para resolver tareas más complejas. Cuando algo fallaba, la solución casi nunca consistía en «esforzarse más». Porque la única manera de hacer progresos era logrando que Codex hiciera el trabajo, mientras el equipo humano de ingenieros humanos se involucraba en todo momento en la tarea preguntándose: «¿Qué capacidad falta y qué podemos hacer para sea a la vez legible y exigible para el agente?».

Las personas interactúan con el sistema casi por completo a través de prompts: un ingeniero describe una tarea, ejecuta el agente y le permite abrir una pull request. Para completar una PR, pedimos a Codex que revise sus propios cambios localmente, solicite revisiones adicionales específicas de agentes tanto a nivel local como en la nube, responda a cualquier comentario del equipo humano o de los agentes, y repita en un bucle hasta que todos los revisores estén satisfechos (en la práctica, esto es un bucle Ralph Wiggum⁠(se abre en una ventana nueva)). Codex utiliza directamente nuestras herramientas de desarrollo estándar (gh, scripts locales y habilidades integradas en el repositorio) para recopilar contexto sin que las personas tengan que copiar y pegar en la CLI.

El equipo humano puede revisar las pull requests, aunque no está obligado a hacerlo. Con el tiempo, hemos dirigido casi todo el esfuerzo de revisión para que se gestione de agente a agente.

A medida que aumentó el rendimiento del código, nuestro cuello de botella se convirtió en la capacidad humana para el control de calidad. Dado que la limitación constante ha sido el tiempo y la atención humanos, nos hemos centrado en añadir más capacidades al agente y, para ello, nos hemos enfocado en que elementos como la interfaz de usuario de la aplicación, los registros y las métricas de la aplicación sean legibles directamente para Codex.

Por ejemplo, hicimos que la aplicación fuera arrancable por cada worktree de git, de manera que Codex pudiera iniciar y manejar una instancia por cada cambio. También conectamos el protocolo Chrome DevTools al entorno de ejecución del agente y desarrollamos habilidades para trabajar con instantáneas del DOM, capturas de pantalla y navegación. Esto permitió a Codex reproducir errores, validar correcciones y razonar directamente sobre el comportamiento de la interfaz de usuario.

Hicimos lo mismo con las herramientas de observabilidad. Los registros, las métricas y los trazos se exponen a Codex a través de una pila local de observabilidad que es efímera para cualquier worktree dado. Codex trabaja en una versión completamente aislada de esa aplicación, incluidos sus registros y métricas, que se eliminan una vez que se completa la tarea. Los agentes pueden consultar los registros con LogQL y las métricas con PromQL. Con este contexto disponible, prompts como «asegúrate de que el arranque del servicio se complete en menos de 800 ms» o «que ningún intervalo en estos cuatro recorridos críticos de usuario supere los dos segundos» se vuelven manejables.

A menudo vemos que las ejecuciones individuales de Codex trabajan en una sola tarea durante más de seis horas (incluso mientras el equipo humano está durmiendo).

La gestión del contexto es uno de los principales desafíos para que los agentes sean efectivos en tareas grandes y complejas. Una de las primeras lecciones que aprendimos fue sencilla: proporciona a Codex un mapa, no un manual de instrucciones de 1000 páginas.

Probamos el enfoque «gran AGENTS.md⁠(se abre en una ventana nueva)» , el cual falló de maneras predecibles:

• El contexto es un recurso escaso. Un archivo de instrucciones gigantesco eclipsa la tarea, el código y la documentación pertinente, así que se plantean dos opciones para el agente: o pasar por alto restricciones clave u optimizar las que son incorrectas.
• Demasiada orientación se convierte en desorientación. Cuando todo es «importante», nada lo es. Los agentes terminan encajando patrones a nivel local en lugar de navegar con una intención.
• Se descompone al instante. Un manual monolítico se transforma en un cementerio de reglas caducas. Los agentes no pueden saber qué sigue siendo cierto, el equipo humano deja de mantenerlo y el archivo se convierte silenciosamente en un atractivo peligro.
• Es difícil de verificar. Un único bloque no se presta a verificaciones automáticas (cobertura, estado, propiedad, enlaces cruzados), por lo que el desvío es inevitable.

Así que, en lugar de tratar AGENTS.md como una enciclopedia, lo tratamos como un índice.

La base de conocimientos del repositorio reside en un directorio estructurado docs/ que se considera el sistema de registro. Se introduce en el contexto un breve archivo AGENTS.md (aproximadamente 100 líneas) para que sirva principalmente como un mapa, con indicaciones hacia fuentes de verdad más profundas en otros lugares.

Se cataloga e indexa la documentación de diseño, incluyendo aquí el estado de verificación y un conjunto de creencias fundamentales que definen los principios operativos centrados en el agente. La documentación de arquitectura⁠(se abre en una ventana nueva) ofrece un mapa de alto nivel de dominios y la organización de capas de paquetes. Un documento de calidad califica cada dominio de producto y capa arquitectónica, registrando las lagunas a lo largo del tiempo.

Los planes se consideran artefactos de primera categoría. Para cambios pequeños se utilizan planes efímeros y ligeros, mientras que el trabajo complejo se documenta en planes de ejecución⁠(se abre en una ventana nueva), donde se hacen registros sobre los progresos y las decisiones que se archivan en el repositorio. Los planes activos, los planes completados y la deuda técnica conocida se guardan por versiones en una misma ubicación, lo que permite a los agentes operar sin depender de un contexto externo.

Esto facilita la divulgación progresiva: los agentes parten desde un pequeño punto de entrada estable, y luego se les enseña dónde mirar a continuación, en lugar de abrumarlos desde el principio.

Esto lo aplicamos de manera mecánica. Linters específicos y trabajos de CI validan que la base de conocimiento esté actualizada, interenlazada y estructurada correctamente. Un agente recurrente de «doc-gardening» escanea documentación desactualizada u obsoleta que no refleja el comportamiento real del código y abre pull requests de corrección.

A medida que el código base evolucionaba, el marco de trabajo de Codex para las decisiones de diseño también necesitaba evolucionar.

Como el repositorio está generado íntegramente por un agente, está optimizado en primer lugar para la legibilidad de Codex. Del mismo modo que los equipos buscan mejorar la navegabilidad de su código para las nuevas incorporaciones de ingeniería, el objetivo de nuestro equipo humano de ingenieros era permitir que un agente pudiera razonar sobre todo el dominio empresarial directamente desde el propio repositorio.

Desde el punto de vista del agente, cualquier cosa a la que no pueda acceder en contexto mientras se ejecuta eficazmente, no existe. El conocimiento que reside en Google Docs, en hilos de chat o en la mente de las personas no es accesible para el sistema. Todo lo que puede ver son los artefactos versionados y locales del repositorio (p. ej., código, markdown, esquemas, planes ejecutables).

Aprendimos que, con el tiempo, teníamos que incorporar cada vez más contexto en el repositorio. ¿Aquella conversación en Slack que alineó al equipo en un patrón arquitectónico? Si el agente no puede detectarla, será ilegible de la misma manera que lo sería para un nuevo empleado que se incorporara tres meses después.

Dar más contexto a Codex significa organizar y exponer la información adecuada para que el agente pueda razonar sobre ella, en lugar de abrumarlo con instrucciones específicas. De la misma manera que darías acceso a un nuevo compañero en los principios del producto, las normas de ingeniería y la cultura del equipo (incluidas las preferencias de emojis), dar esta información al agente conlleva un resultado más alineado.

Este marco aclaró muchas disyuntivas. Favorecimos dependencias y abstracciones que pudieran ser completamente internalizadas y razonadas dentro del repositorio. Las tecnologías que a menudo se describen como «aburridas» tienden a ser más fáciles de modelar para los agentes debido a su componibilidad, la estabilidad de la API y la representación en el conjunto de entrenamiento. En algunos casos, resultaba más económico que el agente reimplementara subconjuntos de funcionalidad en comparación con búsqueda de soluciones alternativas al comportamiento opaco de las bibliotecas públicas. Por ejemplo, en lugar de incorporar un paquete genérico de estilo p-limit, implementamos nuestro propio asistente de mapeo con concurrencia, el cual está estrechamente integrado con nuestra instrumentación de OpenTelemetry, tiene una cobertura de pruebas del 100 % y se comporta exactamente como espera nuestro tiempo de ejecución.

Incorporar una proporción mayor del sistema a un formato que el agente pueda inspeccionar, validar y modificar directamente generará un mayor aprovechamiento, no solo para Codex, sino también para otros agentes (p. ej. Aardvark) que también están trabajando en la base de código.

La documentación por sí sola no mantiene coherente una base de código generada completamente por agentes. Al aplicar invariantes, en lugar de microgestionar las implementaciones, permitimos que los agentes avancen rápido sin debilitar la base. Por ejemplo, exigimos que Codex analice las formas de datos en el límite⁠(se abre en una ventana nueva), pero no somos prescriptivos a la hora de decidir cómo debe hacerse (el modelo parece preferir Zod, aunque no habíamos especificado esa biblioteca en particular).

Los agentes son más efectivos en entornos con límites estrictos y una estructura predecible⁠(se abre en una ventana nueva), así que construimos la aplicación alrededor de un modelo arquitectónico rígido. Cada dominio empresarial se divide en un conjunto fijo de capas, donde las direcciones de dependencia están estrictamente validadas y se permite un conjunto limitado de aristas. Estas restricciones se imponen mecánicamente a través de linters personalizados (¡generados por Codex, por supuesto!) y pruebas estructurales.

El diagrama siguiente muestra la regla: dentro de cada dominio empresarial (por ejemplo, Configuración de la aplicación), el código solo puede depender «hacia adelante» a través de un conjunto fijo de capas (Tipos → Config → Repositorio → Servicio → Tiempo de ejecución → IU). Las inquietudes transversales (auth, conectores, telemetría, alternancia de funciones) entran a través de una única interfaz explícita: Proveedores. No se permite nada más y se aplica de forma automática.

Este es el tipo de arquitectura que sueles posponer hasta que cuentas con cientos de ingenieros. Con los agentes de codificación, es uno de los prerrequisitos iniciales: las restricciones son lo que permite la velocidad, sin deterioros ni desviaciones arquitectónicas.

En la práctica, aplicamos estas reglas con linters y pruebas estructurales personalizados, además de un pequeño conjunto de «invariantes de estilo». Por ejemplo, imponemos de manera estática el registro estructurado, las convenciones de nomenclatura para esquemas y tipos, los límites de tamaño de archivo y los requisitos de fiabilidad específicos de la plataforma con lints personalizados. Dado que los lints son personalizados, redactamos los mensajes de error para incluir instrucciones de remedios en el contexto del agente.

En un flujo de trabajo principalmente humano, estas reglas podrían parecer pedantes o restrictivas. Con los agentes, se convierten en multiplicadores: una vez codificados, se aplican en cualquier parte de una vez.

Al mismo tiempo, somos claros sobre dónde importan las limitaciones y dónde no. Esto se parece a liderar una gran organización de plataformas de ingeniería: estableciendo límites de manera centralizada y permitiendo la autonomía a nivel local. Te importan mucho los límites, la corrección y la reproducibilidad. Dentro de esos límites, permites a los equipos (o agentes) una libertad considerable en cómo se expresan las soluciones.

El código resultante no siempre coincide con las preferencias estilísticas humanas, y no pasa nada. Mientras el resultado sea correcto, mantenible y legible para futuras ejecuciones del agente, cumple con el estándar.

El estilo humano se retroalimenta en el sistema de manera continua. Los comentarios de revisión, las pull requests de refactorización y los errores de cara al usuario se documentan como actualizaciones o se integran directamente en las herramientas. Cuando la documentación es insuficiente, promovemos la regla al código

A medida que aumentaba el rendimiento de Codex, muchas normas convencionales de ingeniería se volvieron contraproducentes.

El repositorio opera con puertas de fusión que bloquean mínimamente. Las pull requests son de corta duración. Los fallos intermitentes en las pruebas suelen abordarse con ejecuciones de seguimiento en lugar de detener el progreso indefinidamente. En un sistema donde el rendimiento del agente supera con creces la atención humana, las correcciones son baratas, mientras que esperar es caro.

Esto sería irresponsable en un entorno de bajo rendimiento. Aquí, a menudo es el punto medio adecuado.

Cuando decimos que la base de código es generada por agentes de Codex, nos referimos a cualquier cosa en la base de código.

Los agentes producen:

• Código de producto y pruebas
• Configuración de CI y herramientas de lanzamiento
• Herramientas internas para desarrolladores
• Documentación e historial de diseño
• Sistemas de evaluación
• Comentarios y respuestas de revisión
• Scripts que gestionan el repositorio en sí mismo
• Archivos de definición del panel de producción

Las personas siempre permanecemos en el bucle, pero trabajamos en un nivel de abstracción diferente al que solíamos. Priorizamos el trabajo, convertimos los comentarios de los usuarios en criterios de aceptación y validamos los resultados. Cuando el agente tiene dificultades, lo tratamos como una señal e identificamos lo que falta (herramientas, guías, documentación) y lo devolvemos al repositorio, para que Codex escriba la corrección.

Los agentes usan directamente nuestras herramientas de desarrollo estándar. Recopilan comentarios de revisión, responden en línea, envían actualizaciones y, a menudo, combinan y fusionan sus propias pull requests.

A medida que más partes del ciclo de desarrollo se integraban directamente en el sistema (pruebas, validación, revisión, gestión de comentarios y recuperación), el repositorio cruzaba recientemente un umbral significativo en el que Codex puede gestionar de principio a fin una nueva función.

Con un solo prompt, el agente ahora puede:

• Validar el estado actual de la base de código
• Reproducir un error reportado
• Grabar un vídeo demostrando el fallo
• Implementar una solución
• Validar la corrección probando la aplicación
• Grabar un segundo vídeo que demuestre la resolución
• Abrir una pull request
• Responder a los comentarios del agente y del equipo humano
• Detectar y remediar fallos de compilación
• Escalar a una persona solo cuando sea necesario un criterio
• Fusionar el cambio

Este comportamiento depende mucho de la estructura y las herramientas específicas de este repositorio, y no se debe asumir que vaya a generalizarse sin una inversión similar, al menos, por ahora.

La autonomía completa del agente también presenta problemas nuevos. Codex replica patrones que ya existen en el repositorio, incluso los que son irregulares o subóptimos. Con el tiempo, esto inevitablemente conducirá a un desvío.

En un principio, el equipo humano abordó esto manualmente. Nuestro equipo solía dedicar todos los viernes (el 20 % de la semana) a limpiar «la basura de la IA». Y, como era de esperar, eso no escalaba.

En su lugar, empezamos a codificar lo que llamamos «los principios dorados» directamente en el repositorio y desarrollamos un proceso de limpieza recurrente. Estos principios son reglas mecánicas y deliberadamente prescriptivas que mantienen la base de código legible y coherente para futuras ejecuciones del agente. Por ejemplo: 1) preferimos los paquetes de utilidades compartidos en lugar de los ayudantes hechos a mano para mantener las invariantes centralizadas, y 2) no exploramos los datos «al estilo YOLO», sino que validamos los límites o confiamos en SDK tecleados para que el agente no pueda basarse accidentalmente en formas supuestas. Con una cadencia regular, tenemos un conjunto de tareas de Codex en segundo plano que exploran desviaciones, actualizan las calificaciones de calidad y abren pull requests de refactorización específicas. La mayoría de ellas se pueden revisar en menos de un minuto y fusionarse automáticamente.

Esto funciona como la recolección de basura. La deuda técnica es como un préstamo con intereses altos: casi siempre es mejor ir pagándola poco a poco en pequeños incrementos en lugar de dejar que se acumule para tener que abordarla en montañas dolorosas. El gusto humano se captura una vez y luego se aplica continuamente en cada línea de código. Esto también nos permite detectar y resolver patrones problemáticos a diario, en lugar de dejar que se propaguen en la base de código durante días o semanas.

Hasta ahora, esta estrategia ha funcionado bien desde el lanzamiento interno y la adopción en OpenAI. Crear un producto auténtico para usuarios reales nos ayudó a fijar nuestras inversiones en la realidad y a guiarnos hacia una sostenibilidad a largo plazo.

Lo que todavía no sabemos es cómo evolucionará la coherencia arquitectónica a lo largo de los años en un sistema completamente generado por agentes. Seguimos aprendiendo dónde aporta más valor el criterio humano y cómo codificar ese criterio para que se multiplique. Tampoco sabemos cómo evolucionará este sistema a medida que los modelos se vayan volviendo más capaces.

Lo que está claro es que crear software sigue exigiendo disciplina, pero esa disciplina se nota más en la estructura interna que en el código. Las herramientas, las abstracciones y los bucles de retroalimentación que mantienen coherente la base de código son cada vez más importantes.

Nuestros retos más difíciles ahora se centran en diseñar entornos, bucles de retroalimentación y sistemas de control que ayuden a los agentes a lograr nuestro objetivo: desarrollar y mantener software complejo y fiable a gran escala.

A medida que agentes como Codex asumen partes más amplias del ciclo de vida del software, estas preguntas importarán aún más. Esperamos que las lecciones iniciales compartidas te ayuden a razonar sobre dónde invertir tu esfuerzo para que puedas concentrarte simplemente en desarrollar cosas.