Cómo preparar tu stack para agentes de código

Si vas a meter agentes de código en tu flujo de trabajo, el problema no es solo que escriban código. El problema real es que puedan trabajar sin desordenar el repositorio, sin saltarse pruebas, sin tocar archivos sensibles y sin convertir una tarea simple en una cadena de cambios difíciles de revisar.

La mayoría de equipos empieza al revés: primero prueba el agente, luego descubre que el entorno no está preparado. Ahí aparecen los fallos típicos: dependencias que cambian entre máquinas, tests que tardan demasiado, permisos demasiado amplios, prompts sin contexto y una evaluación que depende de “se ve bien”. Si quieres que un agente sea útil de verdad, necesitas diseñar el stack alrededor de él. Eso es, en esencia, lo que plantea la idea de harness engineering: construir el entorno, las validaciones y los límites para que el agente haga trabajo real sin romper producción.

Qué cambia cuando el código lo escribe un agente

Cuando un agente de código entra a tu flujo, ya no basta con pensar en “desarrollador + editor + CI”. Ahora tienes un actor que ejecuta pasos, lee archivos, propone cambios y, si lo dejas, puede iterar más rápido que un humano sin entender del todo el impacto de cada decisión. Por eso el stack tiene que responder a dos preguntas: ¿qué puede hacer el agente? y ¿cómo verificas que lo que hizo está bien?

OpenAI describe este enfoque en su artículo sobre harness engineering y el uso de Codex en un mundo agent-first, donde el valor no está solo en el modelo sino en el sistema que lo rodea. Puedes leer la fuente oficial aquí: https://openai.com/index/harness-engineering/ y la documentación de Codex en https://platform.openai.com/docs/guides/codex. La idea central es simple: si el entorno está mal diseñado, el agente va a amplificar ese desorden.

El agente no reemplaza tu proceso, lo estresa

Un agente no inventa tus problemas, los vuelve más visibles. Si tu repo ya tiene tests frágiles, linters inconsistentes o scripts que dependen de variables de entorno no documentadas, el agente va a fallar más seguido que una persona, porque no improvisa igual y porque repite patrones con menos tolerancia al caos.

Piensa en un caso realista: le pides al agente que agregue un endpoint nuevo en una API de Node.js. Si el proyecto tiene TypeScript, ESLint, tests unitarios y un pipeline de integración, el agente puede avanzar bien. Pero si cada carpeta usa convenciones distintas, si hay scripts manuales que solo conoce una persona y si los fixtures cambian según la máquina, el agente terminará generando cambios parciales, más ruido en el diff y más tiempo de revisión para ti.

El valor está en la repetibilidad

Los agentes funcionan mejor cuando el trabajo es repetible. No necesitan magia, necesitan instrucciones claras, acceso limitado y señales de éxito medibles. Eso significa que tu stack debe reducir ambigüedad: misma versión de Node, mismo comando para testear, misma forma de levantar el entorno local, mismos criterios para decidir si un cambio pasó o no.

Si hoy un desarrollador junior tarda 40 minutos en dejar listo el proyecto y el agente tarda 12 minutos pero falla por una variable no documentada, no ganaste nada. El objetivo no es que el agente “sepa más”, sino que pueda avanzar con menos fricción y con límites más estrictos que un humano.

Diseña el harness antes de abrir acceso al agente

El harness es el conjunto de herramientas, permisos, validaciones y reglas que rodean al agente. No es un detalle de implementación. Es la capa que define si el agente puede hacer trabajo útil o si va a convertirse en una fuente de cambios ruidosos. Si lo piensas como infraestructura, vas por buen camino.

Hay tres piezas que conviene cerrar antes de darle tareas reales: el entorno, las herramientas y el criterio de salida. Si alguna de esas piezas queda floja, el agente va a compensar con iteraciones extra, y cada iteración extra cuesta tiempo y aumenta el riesgo de tocar algo que no debía.

Entorno reproducible

Tu prioridad es que el agente vea el mismo mundo que ve tu pipeline. Si el entorno local usa una versión distinta de runtime, si los paquetes se resuelven diferente o si los tests dependen de datos externos, el agente va a tomar decisiones sobre una base inestable.

Haz esto desde el día uno:

1. Fija versiones con archivos de lock y gestores claros, por ejemplo package-lock.json, pnpm-lock.yaml o poetry.lock.
2. Define un comando único para preparar el proyecto, como make setup o npm run bootstrap.
3. Usa contenedores o entornos efímeros cuando el stack sea sensible a diferencias de sistema.
4. Documenta variables de entorno obligatorias y valores de ejemplo.
5. Separa datos de prueba de datos reales para que el agente no tenga acceso accidental a información de producción.

En equipos con despliegues frecuentes, esto reduce el clásico “en mi máquina sí funcionaba”. Para un agente, ese problema es peor porque no puede compensar con intuición humana. Si el entorno no es reproducible, el agente va a repetir errores de forma consistente.

Herramientas con permisos mínimos

No le des al agente acceso a todo el repo ni a todas las credenciales. Dale solo lo que necesita para la tarea concreta. Si va a modificar una librería interna, no necesita acceso a secretos de producción. Si va a escribir tests, no necesita permisos para desplegar.

Una buena práctica es crear perfiles de acceso por tipo de tarea. Por ejemplo, un agente que corrige bugs puede leer código, correr tests y proponer cambios. Otro que actualiza documentación puede editar solo archivos Markdown y no tocar código fuente. Otro que genera migraciones puede operar en una rama aislada y con un checklist más duro antes de merge.

Validaciones que sí sirven y las que solo hacen ruido

No todo check ayuda. Muchas veces los equipos llenan el pipeline de validaciones que se ven bien en una demo, pero no detectan errores relevantes. Con agentes de código, lo que importa es cerrar el ciclo entre cambio y evidencia. Si el agente hizo una modificación, necesitas una forma rápida y confiable de confirmar que no rompió nada.

La idea no es agregar más gates por deporte. La idea es construir validaciones que respondan al riesgo real de cada cambio. Un cambio en una función pura no debería pasar por el mismo nivel de fricción que una modificación en autenticación o pagos.

Crea una matriz simple de validación

Una forma práctica de ordenar esto es cruzar tipo de cambio con nivel de riesgo. Aquí tienes una versión básica que puedes adaptar a tu stack:

La tabla no es una receta universal, pero te ayuda a evitar el error más común: tratar todo como si tuviera el mismo riesgo. Un agente puede ser excelente corrigiendo 20 issues pequeños y, al mismo tiempo, ser una mala idea para tocar una migración sin guardrails.

Usa tests que el agente pueda interpretar

Los tests no solo deben fallar o pasar. También deben ser legibles para el agente. Si un error devuelve mensajes vagos, el agente va a iterar a ciegas. Si el output es claro, puede corregir más rápido y con menos cambios innecesarios.

Por ejemplo, un test que dice “expected 200 to equal 201” ayuda más que uno que solo dice “request failed”. Un linter que marca el archivo, la línea y la regla exacta reduce el tiempo de diagnóstico. Y si tu CI emite resultados estructurados en JSON, mejor todavía, porque el agente puede procesarlos de forma más precisa.

No confundas cobertura con confianza

Tener 90% de coverage no significa que tu sistema esté listo para agentes. Si ese coverage vive en rutas poco críticas y no cubre integraciones, el agente seguirá teniendo espacio para romper cosas importantes. Lo que necesitas es cobertura enfocada en los puntos donde el costo de un error es alto.

Piensa en lo que realmente quieres prevenir: regresiones en auth, cambios que rompen deploy, errores de tipo en APIs públicas, queries que degradan rendimiento o componentes de UI que afectan conversiones. Si tus tests no están alineados con esos riesgos, entonces sirven poco para un agente y poco para tu equipo.

Cómo limitar el daño sin frenar la velocidad

El mejor harness no solo valida. También limita el radio de acción del agente. Si algo sale mal, quieres que el daño sea acotado, fácil de revertir y visible rápido. Eso se logra con límites técnicos y con límites operativos.

En la práctica, los límites más útiles suelen ser bastante aburridos: ramas aisladas, diffs pequeños, timeouts, cuotas de ejecución y aprobaciones para tareas sensibles. No necesitan sonar sofisticados. Necesitan funcionar siempre.

Límites que conviene aplicar

• Rama por tarea, nunca cambios directos en main.
• Diffs pequeños, idealmente por debajo de 300 líneas cuando sea posible.
• Timeouts por paso para evitar loops infinitos.
• Acceso de solo lectura a zonas sensibles del repositorio.
• Aprobación humana obligatoria para cambios en auth, billing, secrets o infraestructura.
• Logs de ejecución por tarea para auditar qué hizo el agente y por qué.

Si trabajas con varias apps o servicios, separa el acceso por dominio. Un agente que arregla frontend no debería poder tocar infraestructura. Uno que genera tests no necesita editar variables de entorno de producción. Mientras más pequeño sea el alcance, más fácil será revisar el resultado.

Elige bien el punto de corte

No todo se resuelve con más validaciones. A veces el mejor límite es decir: hasta aquí puede llegar el agente, y de aquí en adelante entra una persona. Ese punto de corte depende del riesgo, no del entusiasmo del equipo.

Un ejemplo útil: el agente puede preparar un PR con cambios en código y tests, pero la aprobación final para merge la hace una persona del equipo. O el agente puede proponer una migración, pero solo un humano la ejecuta en staging. Ese modelo mixto suele funcionar mejor que un “autopilot” total, sobre todo en equipos que todavía están ajustando su proceso.

Cómo evaluar si tu stack está listo para agentes

Antes de escalar el uso de agentes, necesitas métricas que te digan si el sistema está mejorando o solo generando trabajo extra. No midas solo velocidad. Mide retrabajo, tasa de fallos y cuánto tiempo te toma revisar los cambios.

OpenAI recomienda pensar el trabajo del agente como un sistema evaluable, no como una demo aislada. Esa mentalidad importa porque te obliga a mirar resultados repetibles. Si un agente completa una tarea una vez pero falla cuatro veces en tareas parecidas, no está listo para producción de flujo, aunque la demo haya salido bien.

Métricas útiles para tu equipo

Puedes empezar con estas cuatro:

1. Tiempo promedio desde prompt hasta PR listo para revisión.
2. Porcentaje de tareas que pasan validación sin intervención manual extra.
3. Número de iteraciones necesarias para cerrar una tarea.
4. Tasa de rollback o hotfix asociado a cambios hechos por agentes.

Si quieres una señal más concreta, compara contra un baseline humano. Por ejemplo: un cambio de test que a una persona le toma 25 minutos y al agente 9 minutos está bien, siempre que el agente no aumente la carga de revisión. Si te ahorra 15 minutos pero te agrega 30 minutos de revisión y corrección, el balance es negativo.

Pilotos pequeños, objetivos claros

No empieces con el sistema crítico. Elige una zona con riesgo controlado y volumen suficiente para aprender. Buenas candidatas: documentación técnica, tests de bajo impacto, refactors acotados, fixes de bugs repetibles o tareas de mantenimiento que ya tienen patrón.

Un piloto útil debería tener un objetivo concreto, por ejemplo: reducir el tiempo de PR en 20% sin aumentar bugs en staging. Si no defines la meta, el equipo va a discutir percepciones. Y con agentes, las percepciones suelen ser engañosas porque un día bueno puede ocultar una semana de fricción.

Un patrón práctico para equipos de LatAm

En equipos de Latinoamérica, el contexto importa bastante. Muchas veces trabajas con infra compartida, presupuestos ajustados, horarios distribuidos y dependencias entre producto, soporte y delivery. Eso hace que el diseño del harness tenga que ser pragmático: barato de operar, fácil de auditar y lo bastante estricto para evitar sustos.

Si estás en Ecuador, México, Colombia, Perú, Argentina o Chile, probablemente ya conoces el costo de un deploy fallido en una ventana corta o de un cambio que obliga a coordinar a varias personas en distintos husos horarios. Los agentes pueden ayudar justo ahí, pero solo si el stack reduce incertidumbre y deja trazabilidad clara.

Un flujo que sí puedes aplicar

1. El agente recibe una tarea pequeña y bien delimitada.
2. Trabaja en una rama aislada con permisos mínimos.
3. Ejecuta tests y linters con salida legible.
4. Genera un PR con resumen de cambios y evidencia.
5. Una persona revisa el diff, valida riesgo y aprueba o rechaza.
6. Si el cambio toca zonas sensibles, pasa por staging antes de producción.

Ese flujo no es sofisticado, pero sí sostenible. Y lo mejor es que escala sin exigir que tu equipo cambie todo de golpe. Puedes empezar con una sola área y luego extender el patrón al resto del stack.

Qué automatizar primero

Si tu presupuesto o tu tiempo son limitados, prioriza lo que más reduce ruido:

• Setup del entorno.
• Ejecución de tests.
• Formato y lint.
• Generación de PRs con checklist.
• Recolección de logs por tarea.

No empieces por tareas de alto riesgo. Primero haz que el agente sea confiable en lo repetible. Después, con evidencia, puedes ampliar el alcance. Esa secuencia suele ser más barata que intentar un despliegue amplio desde el día uno y terminar corrigiendo demasiado a mano.

Tabla resumen

Si quieres que agentes de código sean útiles, no les pidas que compensen un stack desordenado. Diseña el sistema para que puedan trabajar con límites claros, señales confiables y validaciones que de verdad detecten problemas. Ahí es donde el valor aparece: menos fricción, menos retrabajo y más velocidad con control.

La buena noticia es que no necesitas rehacer toda tu arquitectura. Puedes empezar por una rama aislada, un conjunto pequeño de tests, permisos mínimos y una revisión humana obligatoria. Con eso ya cambias mucho. Lo demás es iterar con datos, no con fe.