Un agente de código te promete lo mismo que el café a las 9 de la mañana: productividad inmediata. Y durante la primera semana, la promesa se cumple. El agente abre PRs, escribe tests, refactoriza módulos enteros. Luego llega el lunes de la verdad: un deploy nocturno rompe producción, una migración corrompe datos, o un cambio “inofensivo” borra una configuración que nadie sabía que existía. El agente no tenía la culpa. Tú sí, por no evitar los errores que ya conocemos de sobra.

Los agentes de código no fallan por mala suerte: fallan por patrones predecibles. Estos son los errores más comunes al llevarlos a producción, la causa de fondo detrás de cada uno y las soluciones que funcionan de verdad.

Error 1: Confiar en el contexto por defecto

La causa. La mayoría de los agentes trabajan con una ventana de contexto limitada. Si no le das explícitamente la información que necesita, inventa lo que falta. El resultado: código que funciona en el repositorio de juguete del agente y explota en el tuyo, con variables de entorno mágicas, imports inexistentes y convenciones de equipo ignoradas.

La solución. Trata el contexto como código. Crea un archivo AGENTS.md en la raíz del repositorio que documente: arquitectura del proyecto, convenciones de naming, comandos de build y test, y las reglas de “no tocar” (por ejemplo, carpetas generadas o archivos de configuración sensibles). Cuando inicies una sesión, incluye siempre los archivos relevantes en el contexto en lugar de esperar que el agente “los encuentre”. La diferencia entre un agente que alucina y uno que acierta casi siempre es la calidad del contexto que le diste.

“Un agente de código no es más inteligente que el contexto que le das: es un espejo de tu documentación.”

Error 2: Darle permisos de administrador

La causa. Por comodidad, muchos equipos le dan al agente acceso total: puede escribir en cualquier archivo, instalar dependencias, modificar credenciales y hacer push directo a la rama principal. El agente no es malintencionado, pero sí literal: si una instrucción mal escrita dice “limpia los archivos temporales”, puede interpretarla con una amplitud que no imaginaste.

La solución. Aplica el principio de menor privilegio, igual que harías con cualquier servicio. Restringe al agente a las ramas de trabajo, prohíbele tocar secretos y archivos críticos (.env, terraform/, migrations/), y exige que todos sus cambios pasen por pull request con revisión humana. Las herramientas modernas permiten definir “áreas permitidas” por carpeta; úsalas. Si el agente no puede romper producción, no la va a romper.

Error 3: Merge sin verificación

La causa. El agente genera un cambio que “se ve bien”: la sintaxis es correcta, los nombres son razonables y el diff no es enorme. El humano aprueba sin ejecutar nada. El problema es que los agentes optimizan para que el código parezca correcto, no para que sea correcto. Los tests pueden estar rotos, el linter puede fallar y la compatibilidad con versiones anteriores puede haberse roto silenciosamente.

La solución. Convierte la verificación en un gate automático e innegociable: CI obligatorio en cada PR, cobertura mínima de tests, linting y type-checking. Nunca apruebes un cambio de un agente sin ver evidencia de ejecución: capturas de los tests pasando, logs del build y, si toca lógica crítica, un test nuevo que demuestre el comportamiento. La regla es simple: si no corrió, no existe.

Error 4: No validar contra los datos reales

La causa. Los agentes prueban contra datos sintéticos, fixtures bonitas y casos felices. En producción los datos son feos: nulos inesperados, formatos heredados, emojis en campos de texto, zonas horarias olvidadas. El agente nunca vio esos datos, así que su lógica se rompe exactamente donde duele.

La solución. Para cambios que tocan lógica de negocio, exige pruebas con datos reales anonimizados o, al menos, con fixtures que repliquen los edge cases de tu base de datos. Un patrón que funciona bien: pedirle al agente que escriba tests con los casos límite antes de implementar la solución. Así la validación queda codificada y no depende de la memoria de nadie.

Error 5: Dejarlo sin supervisión en tareas largas

La causa. Lanzas una tarea de refactorización “que va a tomar 20 minutos” y te vas a almorzar. El agente, fiel a su instrucción, sigue trabajando: cambia archivos que no debía, entra en bucles de “corregir un error que él mismo introdujo” y termina con un diff de 3.000 líneas que nadie puede revisar con calma.

La solución. Divide las tareas grandes en unidades pequeñas y verificables, y supervisa cada una antes de pasar a la siguiente. Establece un límite de iteraciones o un presupuesto de tiempo, y configura alertas cuando el agente se desvíe del plan original. Un agente productivo es como un buen pasante: rinde mejor con tareas chicas, claras y con checkpoints, que con un mandato vago de “arregla todo”.

Error 6: Ignorar la deuda técnica que él mismo genera

La causa. Los agentes optimizan para la tarea inmediata. Duplican lógica en vez de refactorizar, dejan código muerto, y generan abstracciones que nadie entiende. El código funciona, los tests pasan, y la deuda se acumula en silencio hasta que el equipo paga la factura en la forma de bugs difíciles de rastrear.

La solución. Incluye en el prompt del agente reglas explícitas de calidad: “no dupliques lógica existente, reutiliza los helpers del proyecto”, “elimina código muerto”, “sigue los patrones del código vecino”. Y agrega revisiones periódicas de la producción del agente: una sesión mensual de limpieza donde un humano revise qué generó, qué se puede simplificar y qué convenciones se están violando sistemáticamente. La deuda que no se ve, se paga igual.

El patrón que resume todo

Si hay una frase que resume esta lista, es esta: el agente de código es un multiplicador, no un reemplazo. Multiplica la velocidad de un proceso que tú defines, valida y supervisas. Los equipos que mejor usan agentes en producción no son los que más confían en ellos, sino los que construyeron el andamiaje correcto: contexto explícito, permisos mínimos, verificación automática y supervisión humana en los puntos de decisión.

Empieza con un solo flujo: una tarea repetitiva y bien definida, con contexto documentado, permisos acotados y CI fuerte. Mide el resultado durante dos semanas. Cuando veas que el flujo es confiable, replica el patrón. Así se escala el uso de agentes de código sin convertir tu repositorio en un experimento.

Sigue explorando estos temas en el blog de DojoFullStack: encontrarás guías sobre agentes de código, automatización y desarrollo de software para equipos que quieren construir con IA sin perder el control. Y si quieres llevar estas prácticas al siguiente nivel, en DojoFullStack te enseñamos a dominar este stack completo, del primer commit al deploy en producción.