Ingeniería de harness: usar Codex en un mundo agent-first

• Caso experimental de un equipo interno de OpenAI que construyó y lanzó la beta interna de un producto de software durante 5 meses sin escribir código manualmente, con todo el código generado por agentes de Codex
• Empezaron con 3 ingenieros y procesaron alrededor de 1 millón de líneas de código y 1,500 pull requests, con un promedio de 3.5 PR fusionados por día por ingeniero
• El rol del ingeniero pasó de programar directamente a diseñar el entorno, explicitar la intención y construir bucles de retroalimentación, donde lo clave es crear el scaffolding para que los agentes trabajen de forma estable
• Usaron AGENTS.md no como enciclopedia sino como tabla de contenidos, y aplicaron mecánicamente consistencia arquitectónica mediante documentación estructurada, linters y pruebas estructurales
• A medida que aumenta la autonomía del agente, se vuelve indispensable la gestión de la entropía y una limpieza continua tipo garbage collection, y la disciplina de construir software se está desplazando del código al scaffolding

---

Un experimento que empezó desde un repositorio git vacío

• A finales de agosto de 2025 hicieron el primer commit en un repositorio vacío, y el scaffold inicial (estructura del repositorio, configuración de CI, reglas de formato, configuración del gestor de paquetes, framework de la aplicación) se generó en Codex CLI usando GPT-5 a partir de una plantilla existente
• El archivo inicial AGENTS.md, que le enseñaba al agente cómo trabajar en el repositorio, también fue escrito directamente por Codex
• Desde el inicio, el repositorio se formó por agentes, sin código previo escrito por humanos
• Cinco meses después, ya incluía alrededor de 1 millón de líneas de código entre lógica de aplicación, infraestructura, tooling, documentación y utilidades internas para desarrolladores
• Un equipo pequeño de 3 personas abrió y fusionó cerca de 1,500 pull requests, lo que equivale a una productividad promedio de 3.5 PR por día por ingeniero
• Cuando el equipo creció a 7 personas, la productividad aumentó todavía más
• Cientos de usuarios lo habían estado usando internamente todos los días, incluidos usuarios avanzados internos
• En todo el proceso de desarrollo, ningún humano contribuyó código directamente
• "No hay código escrito manualmente" se convirtió en la filosofía central del equipo

Redefinir el rol del ingeniero

• Como las personas ya no programan directamente, hace falta otro tipo de trabajo de ingeniería, centrado en sistemas, scaffolding y apalancamiento
• El avance inicial fue más lento de lo esperado no por limitaciones de Codex, sino por carencias del entorno
  • Al agente le faltaban herramientas, abstracciones y estructura interna para cumplir objetivos de nivel superior
• El trabajo principal del equipo de ingeniería pasó a ser apoyar a los agentes para que pudieran realizar trabajo útil
• Adoptaron un enfoque de trabajo en profundidad, dividiendo grandes objetivos en bloques más pequeños (diseño, código, revisión, pruebas, etc.) para que el agente pudiera componerlos y luego resolver tareas más complejas
• Cuando algo fallaba, la pregunta clave no era “esforzarse más”, sino "qué capacidad falta y cómo hacerla legible y ejecutable para el agente"
• Las personas interactúan con el sistema casi exclusivamente mediante prompts
  • Dan instrucciones para describir tareas, ejecutar agentes y abrir pull requests
• Para completar un PR, le indicaban a Codex que revisara localmente sus propios cambios, pidiera revisiones adicionales de agentes en local y en la nube, respondiera retroalimentación y repitiera hasta satisfacer a todos los revisores-agente
  • En la práctica, una especie de Ralph Wiggum Loop
• Codex usa directamente herramientas de desarrollo estándar como gh, scripts locales y skills integradas en el repositorio para reunir contexto
• La revisión humana de pull requests sigue siendo posible, pero ya no es obligatoria; con el tiempo, casi toda la revisión pasó a ser entre agentes

Mejorar la legibilidad de la aplicación

• A medida que aumentó el volumen de código, aparecieron cuellos de botella en la capacidad humana de QA
• Como el tiempo y la atención humana son limitados, agregaron capacidades para que Codex pudiera leer y comprender directamente la UI de la aplicación, logs y métricas
• Con la función de arranque de la app por git worktree, Codex podía ejecutar y controlar una instancia separada para cada cambio
• Conectaron el Chrome DevTools Protocol al runtime del agente y crearon skills para snapshots del DOM, screenshots y navegación
  • Así, Codex podía reproducir bugs, validar correcciones y razonar directamente sobre el comportamiento de la UI
• Aplicaron el mismo enfoque al tooling de observabilidad
  • Los logs, métricas y trazas se exponían a Codex mediante un stack de observabilidad local efímero para cada worktree
  • Al terminar la tarea, los logs y métricas se eliminaban
  • El agente podía consultar logs con LogQL y métricas con PromQL
• Con este contexto, era más fácil procesar prompts como “haz que el inicio del servicio termine en menos de 800 ms” o “asegúrate de que ningún span supere los 2 segundos en cuatro recorridos clave de usuario”
• Una sola ejecución de Codex podía trabajar en una tarea durante más de 6 horas seguidas, a menudo mientras la persona dormía

Usar el conocimiento del repositorio como sistema de registro

• La gestión del contexto es uno de los mayores desafíos para que los agentes resuelvan tareas grandes y complejas de forma efectiva
• Una lección temprana fue que había que darle a Codex un mapa, no un manual de 1,000 páginas
• Intentaron el enfoque de “un solo AGENTS.md grande”, y falló de forma predecible
  • El contexto es un recurso escaso: un archivo enorme de instrucciones complicaba la tarea, el código y los documentos relevantes, haciendo que el agente omitiera restricciones importantes u optimizara para restricciones equivocadas
  • Si hay demasiadas instrucciones, dejan de ser instrucciones: si todo es “importante”, nada lo es; el agente termina haciendo matching local de patrones en lugar de exploración intencional
  • Se degrada muy rápido: un gran manual uniforme se convierte en un cementerio de reglas obsoletas, y el agente no puede saber qué sigue vigente
  • Es difícil de verificar: un blob único no sirve para chequeos mecánicos como cobertura, vigencia, ownership o enlaces cruzados, así que el drift es inevitable
• La solución fue tratar AGENTS.md como una tabla de contenidos, no como una enciclopedia
• La base de conocimiento del repositorio se gestionó como sistema de registro en un directorio docs/ estructurado
• Un AGENTS.md corto (unas 100 líneas) se inyecta en contexto y funciona principalmente como mapa, apuntando a fuentes de información más profundas y confiables
• La documentación de diseño está clasificada e indexada, e incluye creencias clave que definen el estado de validación y los principios operativos agent-first
• La documentación de arquitectura ofrece el mapa de más alto nivel del dominio y del layering por paquetes
• La documentación de calidad califica cada dominio de producto y cada capa de arquitectura, y sigue las brechas a lo largo del tiempo
• Los planes se tratan como artefactos de primera clase
  • Los planes breves y efímeros se usan para cambios pequeños
  • El trabajo complejo se guarda en el repositorio dentro de planes de ejecución, junto con el progreso y el registro de decisiones
  • Los planes en curso, los completados y toda la deuda técnica conocida quedan versionados en el mismo lugar
• Esto permite una divulgación progresiva: el agente puede empezar desde un punto de entrada pequeño y estable sin sobrecargarse desde el inicio, y avanzar al siguiente paso
• Aplicación mecánica: linters dedicados y jobs de CI verifican que la base de conocimiento esté actualizada, enlazada entre sí y bien estructurada
• Un agente recurrente de "doc-gardening" revisa documentos viejos o inválidos y abre pull requests para corregirlos

El objetivo es la legibilidad para agentes

• Como el repositorio fue generado por agentes de principio a fin, se optimizó primero para la legibilidad de Codex
• El objetivo de los ingenieros humanos era que el agente pudiera razonar sobre todo el dominio de negocio directamente desde el propio repositorio
• Desde la perspectiva del agente, lo que no está accesible en el contexto de ejecución prácticamente no existe
  • El conocimiento en Google Docs, hilos de chat o en la cabeza de las personas no es accesible para el sistema
  • Solo puede acceder a artefactos versionados dentro del repositorio (código, Markdown, esquemas, planes de ejecución)
• Incluso un patrón arquitectónico acordado en Slack es ilegible para el agente si no puede buscarlo
• Darle más contexto a Codex no significa cargarlo con instrucciones temporales, sino organizar y exponer la información correcta para que el agente pueda razonar
• Obtuvieron mejores resultados al darle al agente información sobre principios de producto, normas de ingeniería y cultura del equipo (incluidas preferencias de emoji), como se haría al incorporar a un nuevo miembro del equipo
• Prefieren dependencias y abstracciones que puedan internalizarse y razonarse por completo dentro del repositorio
• Las tecnologías “aburridas” suelen ser más fáciles de modelar para el agente gracias a su acoplamiento, estabilidad de API y representación en los datos de entrenamiento
• En algunos casos, sale más barato que el agente reimplemente directamente un subconjunto de funcionalidad en lugar de depender de comportamiento upstream opaco de una librería pública
  • Ejemplo: en vez de un paquete genérico estilo p-limit, implementaron su propio helper de map-with-concurrency, estrechamente integrado con instrumentación OpenTelemetry, con 100% de cobertura de pruebas y comportamiento exacto según lo esperado en runtime
• Cuanto más se lleva el sistema a una forma que el agente pueda inspeccionar, validar y modificar directamente, mayor es el apalancamiento no solo para Codex sino también para otros agentes como Aardvark

Imponer arquitectura y preferencias

• La documentación por sí sola no basta para mantener completamente consistente una codebase generada por agentes
• Mantuvieron una base sólida imponiendo invariantes sin microgestionar la implementación, lo que permite a los agentes lanzar rápido
  • Por ejemplo, querían que Codex parseara las formas de datos en los límites, pero no especificaban exactamente cómo hacerlo (aunque el modelo tiende a preferir Zod)
• Los agentes funcionan mejor en entornos con límites estrictos y estructuras predecibles
• Construyeron la aplicación alrededor de un modelo arquitectónico estricto
  • Cada dominio de negocio se separa en un conjunto fijo de capas, con direcciones de dependencia estrictamente validadas y un conjunto limitado de edges permitidos
  • El código fluye en el orden Types → Config → Repo → Service → Runtime → UI
  • Los temas transversales (autenticación, conectores, telemetría, feature flags) entran por una sola interfaz explícita llamada Providers
  • Todo lo demás está prohibido y se fuerza mecánicamente
• Estas restricciones se aplican mediante linters personalizados y pruebas estructurales generados por Codex
• Este nivel de arquitectura suele posponerse hasta equipos de cientos de ingenieros, pero para agentes de programación es un prerrequisito temprano
• También aplicaron estáticamente, con lint personalizado, reglas de logging estructurado, convenciones de nombres para esquemas y tipos, límites de tamaño de archivos y requisitos de estabilidad por plataforma
  • Como el lint es personalizado, pueden redactar mensajes de error que inyectan instrucciones de corrección directamente en el contexto del agente
• En flujos de trabajo pensados para humanos, estas reglas podrían sentirse demasiado detalladas o restrictivas, pero con agentes multiplican el efecto varias veces
• Las restricciones dejan claro qué importa y qué no
  • Es parecido a operar una gran organización de plataformas de ingeniería: límites centralizados, autonomía local
• Puede que el resultado no siempre coincida con las preferencias estilísticas humanas, pero si el output es correcto, mantenible y fácil de leer durante la ejecución del agente, cumple el estándar
• Las preferencias humanas se retroalimentan continuamente al sistema
  • Los comentarios de revisión, PR de refactorización y bugs reportados por usuarios se registran como actualizaciones de documentación o se codifican directamente en el tooling
  • Cuando la documentación no basta, la regla se promueve a código

Cambio en la filosofía de merge

• A medida que creció la productividad de Codex, las normas clásicas de ingeniería empezaron incluso a jugar en contra
• El repositorio operaba con gates mínimos de merge que realmente bloquearan
• Los pull requests son de vida corta, y la inestabilidad en pruebas se resuelve en ejecuciones de seguimiento en lugar de bloquear indefinidamente el avance
• En sistemas donde la productividad de agentes supera por mucho la atención humana, el costo de corregir es barato y el costo de esperar es alto
• Puede que esto no sea adecuado en entornos de baja productividad, donde haría falta otro equilibrio

El alcance real de “generado por agentes”

• Decir que la codebase fue generada por agentes de Codex significa literalmente todo lo que hay en la codebase
  • Código de producto y pruebas
  • Configuración de CI y tooling de releases
  • Herramientas internas para desarrolladores
  • Documentación e historial de diseño
  • Harnesses de evaluación
  • Comentarios de revisión y respuestas
  • Scripts que administran el propio repositorio
  • Archivos de definición de dashboards de producción
• Los humanos siguen en el loop, pero trabajando en una capa de abstracción distinta a la de antes
  • Priorizan trabajo, convierten feedback de usuarios en criterios de aceptación y validan resultados
• Cuando el agente tiene dificultades, lo toman como señal para identificar qué falta en herramientas, guardrails o documentación, y siempre hacen que Codex escriba las correcciones para devolverlas al repositorio
• El agente también puede traer feedback de revisión, responder en línea, empujar updates e incluso hacer squash y merge de sus propios pull requests

Aumento del nivel de autonomía

• A medida que más bucles de desarrollo —pruebas, validación, revisión, manejo de feedback, recuperación— se codificaron directamente en el sistema, alcanzaron un punto de inflexión importante
• Cosas que el agente puede hacer con un solo prompt:
  • Validar el estado actual de la codebase
  • Reproducir un bug reportado
  • Grabar un video que demuestre la falla
  • Implementar la corrección
  • Ejecutar la aplicación para verificar la corrección
  • Grabar un segundo video mostrando la solución
  • Abrir un pull request
  • Responder a feedback de agentes y personas
  • Detectar y corregir fallas de build
  • Escalar a una persona solo cuando haga falta juicio
  • Fusionar el cambio
• Este comportamiento depende fuertemente de la estructura y el tooling específicos de este repositorio, y no debería asumirse que se generaliza sin inversiones similares

Entropía y garbage collection

• La autonomía total del agente trae problemas nuevos: Codex replica patrones ya presentes en el repositorio, incluidos patrones desparejos o subóptimos, así que el drift termina apareciendo con el tiempo
• Al principio lo resolvían manualmente, dedicando cada viernes (20% de la semana) a limpiar “AI slop”
  • Como era de esperarse, eso no escalaba
• Como alternativa, codificaron directamente en el repositorio unas “reglas de oro” y establecieron procesos regulares de limpieza
  • (1) Preferir paquetes de utilidades compartidas sobre helpers hechos a mano para gestionar invariantes en un solo lugar
  • (2) No explorar datos en modo “YOLO-style”, sino validar los límites o depender de SDKs tipados, para evitar que el agente construya accidentalmente sobre formas inferidas y equivocadas
• Operan tareas en background de Codex que revisan periódicamente desvíos, actualizan calificaciones de calidad y generan PR de refactorización puntuales
  • La mayoría se puede revisar en menos de un minuto y se fusiona automáticamente
• Esto funciona como garbage collection: la deuda técnica es como un préstamo con interés alto, y conviene pagarla poco a poco antes de que se acumulen los intereses
• Una vez que se captura una preferencia humana, esta puede reflejarse de forma continua en cada línea de código, detectando y corrigiendo malos patrones a diario antes de que se propaguen por días o semanas

Aprendizajes actuales y retos a futuro

• Esta estrategia funcionó bien en OpenAI hasta la etapa de lanzamiento interno y adopción
• La inversión se está aterrizando en la realidad mediante la construcción de productos reales para usuarios reales, asegurando mantenibilidad a largo plazo
• Lo que todavía no saben es cómo evolucionará durante años la consistencia arquitectónica en un sistema totalmente generado por agentes
• Siguen aprendiendo dónde el juicio humano tiene más impacto y cómo codificar ese juicio para reutilizarlo de forma compuesta
• También es incierto cómo evolucionará este sistema a medida que sigan mejorando las capacidades de los modelos
• Construir software sigue requiriendo disciplina, pero esa disciplina se expresa cada vez más en el scaffolding que en el código
• El tooling, las abstracciones y los bucles de retroalimentación para mantener la consistencia de la codebase son cada vez más importantes
• El reto más difícil hoy es diseñar entornos, bucles de feedback y sistemas de control que ayuden a los agentes a construir y mantener software complejo y estable a gran escala

[ragingwind]

40 días, 1 millón de líneas, 13 mil millones de tokens — Lo que descubrió el CEO de Lablup, Jeongkyu Shin, sobre la realidad de los flujos de trabajo agénticos - Silicon Valley de Park Jae-hong - https://wikidocs.net/blog/@jaehong/8206/