Durante mucho tiempo hubo una crítica bastante demoledora contra los agentes de IA tipo Claude Code. En demos pequeñas quedaban preciosos. En proyectos nuevos, limpios y acotados, parecían magia. Pero en cuanto los soltabas dentro de una base de código con cientos de miles de líneas, múltiples equipos, tickets cruzados, deuda técnica y decisiones históricas acumuladas, se ahogaban.

Eso ya no es del todo verdad.

Desde el gran punto de inflexión que hemos vivido a finales de 2025, los agentes de IA manejan bastante mejor las bases de código masivas. Ahora bien, una cosa es que hayan mejorado mucho y otra muy distinta es pensar que puedes dejarles hacer lo que quieran y esperar un resultado profesional. Ahí es donde empiezan los problemas.

Si trabajas con desarrollo de software, Vibe Coding, IA aplicada a programación o equipos grandes, hay varias reglas del juego que separan un proyecto que acelera gracias a la IA de otro que termina convertido en un caos caro, lento y muy difícil de mantener.

La crítica histórica ya no vale del todo, pero el riesgo sigue ahí

El error habitual es pensar en términos absolutos.

Ni antes eran inútiles para proyectos grandes, ni ahora son infalibles. Lo que ha cambiado es su capacidad de navegar contexto, entender mejor estructuras complejas y colaborar con flujos reales de desarrollo. Pero eso no elimina la necesidad de método.

De hecho, cuanto más grande es el proyecto, más importante es la disciplina. Porque en un proyecto pequeño puedes permitirte cierta improvisación. En uno enorme, improvisar con agentes de IA es casi una invitación al desastre.

La clave no está en pedirles más. La clave está en preparar mejor el entorno en el que trabajan.

Regla número 1: invierte tiempo en tu agents.md o claude.md

Si tuviera que señalar una práctica que da un retorno brutal en proyectos grandes, sería esta: documentar bien para los agentes de IA.

No hablo de una documentación inflada, eterna y llena de paja. Hablo de una documentación útil, específica y colocada en el lugar correcto. Especialmente en estructuras por carpetas o subdirectorios, donde cada nivel debería explicar con claridad:

• Qué responsabilidad tiene ese módulo o paquete
• Qué interfaces principales expone
• Qué funciones o clases son las importantes
• Qué convenciones hay que respetar
• Qué no debe tocarse sin revisar dependencias

La idea es sencilla. Cuando un agente entra en una carpeta, no debería tener que abrir veinte archivos para entender qué demonios pasa ahí dentro. Debería poder orientarse con una documentación breve, ajustada y bien pensada.

Eso sí, aquí hay equilibrio fino. Si metes demasiado detalle, te comes contexto innecesario. Si pones muy poco, el agente improvisa. Y cuando improvisa en una base de código enorme, normalmente alguien acaba pagando la factura.

Otro detalle importante es cómo enlazas documentación externa. Si incluyes un documento entero de forma forzada, muchas veces estarás metiendo en contexto información que ni hace falta. Es mejor resumir qué contiene ese recurso y apuntar al documento completo para que el agente decida si realmente necesita abrirlo.

En resumen, la documentación del proyecto para agentes de IA no es un extra bonito. Es una pieza estructural.

La documentación no se escribe una vez y ya está

Aquí está una de las trampas más típicas. Se crea un buen agents.md, todo el mundo se viene arriba una semana, y al poco tiempo el proyecto cambia, la arquitectura se mueve y la documentación se queda vieja.

Eso es casi peor que no tener nada.

Si quieres que los agentes de IA funcionen bien de forma sostenida, la actualización documental debe formar parte del proceso. Igual que revisas código, revisas tests y revisas despliegues, también revisas documentación. Es una especie de guardar la partida del videojuego antes de seguir avanzando.

Si quieres profundizar más en este enfoque aplicado a proyectos reales, puedes echar un vistazo al curso completo de Vibe Coding, donde todo esto se trabaja con bastante más detalle y con casos prácticos.

Regla número 2: un solo proceso para todo el equipo

En equipos grandes, la inconsistencia mata.

Si una persona usa GitHub de una manera, otra dispara acciones automáticas distintas, otra etiqueta al agente dentro del flujo de incidencias y otra tira de plugins locales sin seguir ningún criterio común, el proyecto se vuelve impredecible. Y un sistema impredecible es justo lo contrario de lo que necesitas cuando introduces IA en desarrollo.

Por eso hace falta una estrategia compartida. Un único proceso acordado por el equipo para cosas como:

• Cómo se pide una nueva funcionalidad al agente
• Qué herramientas o plugins se usan
• Cómo se crea una rama o una tarea
• Qué validaciones deben pasar antes de revisar
• Cómo se actualiza la documentación asociada

Cuando el flujo está estandarizado, todos saben cuál es la forma correcta de trabajar. Y eso no solo mejora la calidad del código, también mejora la revisabilidad y reduce fricción entre personas.

Empieza por plugins antes que por genialidades raras

Una recomendación muy práctica es centrarse primero en plugins que realmente aporten orden y productividad. Por ejemplo, plugins para desarrollo de funcionalidades, simplificación de código o automatización de tareas repetitivas que encajen con vuestro proyecto.

No hace falta empezar por lo más futurista ni por la técnica más exótica. Muchas veces lo que mejor funciona es reforzar bien la capa operativa básica.

Regla número 3: construye skills de dominio

A medida que el proyecto crece, llega un momento en que el agente ya no necesita solo contexto técnico. Necesita criterio específico del dominio.

Ahí entran las skills.

Una skill bien planteada le enseña al agente cómo se resuelven dentro de tu proyecto ciertos problemas recurrentes. No solo qué librerías hay, sino cuál es la forma correcta, aprobada y consistente de utilizarlas.

Por ejemplo, si trabajas con una API concreta de datos de mercado, con una arquitectura interna específica o con un framework que tiene reglas muy particulares dentro de tu empresa, lo lógico es encapsular eso en una skill. Así el agente no tiene que deducirlo cada vez ni reinventar la rueda.

Las buenas skills sirven para:

• Reforzar estándares comunes
• Reducir variabilidad entre contribuciones
• Evitar malas interpretaciones del stack
• Transmitir conocimiento de dominio de forma reutilizable

Este punto es especialmente potente en proyectos con mucha especialización. Porque donde más falla un agente no suele ser en la sintaxis. Suele fallar en el contexto de negocio, en las convenciones del equipo y en las sutilezas del sistema.

Si este tema te interesa, también puede resultarte útil leer otros artículos del blog de Frogames sobre IA, programación y flujos modernos de desarrollo.

Regla número 4: tests que prueban de verdad

Esto va a sonar obvio, pero sigue siendo crítico: necesitas un conjunto de pruebas robusto.

Ahora bien, cuidado con una obsesión muy típica cuando trabajas con LLMs: perseguir porcentajes de cobertura como si fueran el objetivo real. Los agentes de IA aprenden rápido qué métricas les estás premiando. Si les das a entender que lo importante es llegar a cierto número, pueden empezar a producir tests de escaparate.

Y eso no sirve.

El problema clásico es el over-mocking. Pruebas llenas de simulaciones, dobles, estructuras artificiales y rutas hiperespecíficas que no validan la lógica de negocio real. Aparentemente todo está cubierto. En la práctica, casi nada importante está protegido.

Lo que quieres son pruebas con estas características:

• Comprueban funcionalidad real
• No se rompen por una reimplementación interna razonable
• Sí se rompen cuando la lógica importante se rompe
• No están infladas solo para mejorar una métrica

Si detectas pruebas escritas simplemente para “hacer bonito” o para cubrir rutas sin valor, recházalas. Igual que lo harías con código humano descuidado, hazlo también con código generado por agentes de IA.

De hecho, esta estrategia debería quedar reflejada en la documentación del proyecto y en el propio flujo del equipo. No basta con decir “queremos tests”. Hay que definir qué entendéis por buenos tests.

Regla número 5: la responsabilidad final sigue siendo humana

Este es el punto más importante de todos.

Al final del día, el responsable de la calidad del código eres tú. O tu equipo. Pero nunca el agente.

El agente es una herramienta potentísima. Puede ayudarte a pensar, a acelerar, a proponer, a refactorizar y a automatizar. Pero la rendición de cuentas no se delega. Si entra código malo en producción, no vale eso de “es que lo generó la IA”. No cuela.

Y aquí aparece un problema serio: la asimetría.

Generar toneladas de código es cada vez más fácil. Revisarlo bien sigue siendo difícil. Muy difícil. Por eso hay que construir una cultura fuerte de revisión humana, rechazo del trabajo descuidado y exigencia de código sucinto.

Si el agente te devuelve archivos larguísimos, excesivamente defensivos, inflados o complicados de revisar, eso no es productividad. Eso es transferirte carga cognitiva.

Y esa carga hay que cortarla de raíz.

Trabaja siempre en trozos pequeños

Hay un consejo que me gusta especialmente para proyectos enormes: divide todo en fragmentos pequeños.

No le pidas a un agente que refactorice de golpe una base de código gigantesca. En un proyecto pequeño quizá puedas jugar a eso. En uno con 50 personas tocando el mismo repositorio, es una receta estupenda para crear conflictos, regressions y revisiones imposibles.

Lo correcto es trocear el trabajo en unidades pequeñas, independientes y evaluables. Cada paso debería ser:

• Fácil de especificar
• Fácil de probar
• Fácil de revisar
• Lo bastante acotado como para entender su impacto

Este enfoque reduce riesgo, mejora la colaboración y evita que el agente se pierda intentando abarcar demasiado de una sola vez.

Qué se lleva uno de todo esto

La tecnología cambia rapidísimo. Muchos consejos concretos caducarán a medida que los modelos mejoren. Pero el fondo no cambia.

Si quieres usar agentes de IA en proyectos enormes con cabeza, quédate con estas ideas:

• Documenta para agentes, no solo para humanos
• Estandariza el proceso de todo el equipo
• Construye skills de dominio para reforzar criterio y consistencia
• Exige tests útiles, no métricas vacías
• Mantén revisión humana fuerte y rechazo del código descuidado
• Divide el trabajo en trozos pequeños para reducir asimetría y riesgo

Un reto práctico para ponerlo a prueba

Si de verdad quieres entender cómo se comportan estos agentes de IA en bases de código grandes, haz una prueba simple y muy reveladora.

Coge un proyecto open source grande de tu sector. Clónalo en tu máquina. Busca un TODO, una mejora localizada o una pequeña incidencia pendiente. Luego pídele al agente que la encuentre, la entienda y proponga una solución.

Ahí vas a ver enseguida si el contexto está bien manejado, si los cambios son razonables, si sabe respetar el estilo del proyecto y, sobre todo, cuánto trabajo extra te deja en revisión.

Porque al final esa es la verdadera pregunta. No si genera código. Eso ya lo hace. La pregunta es si genera código que merezca la pena integrar.