Lecciones Prácticas de Construir una Base de Código de 350K Líneas en Solitario con Agentes de IA

Entorno de Ingeniería como Contexto

El proyecto de 52 días del desarrollador (600 commits, ~965K líneas de código procesadas, 356K líneas de código de producción) reveló que la calidad de la salida del agente depende críticamente del entorno de ingeniería, no solo del modelo. La base de código en sí sirve como sistema de contexto del agente, eliminando la necesidad de archivos separados de RAG o memoria.

Los límites arquitectónicos claros demostraron ser esenciales. La base de código sigue una estratificación estricta de DDD: capa de dominio para estructuras de datos, capa de servicio para lógica de negocio, capa de manejador para conversión de formato HTTP, con 22 módulos de dominio que tienen límites claros. Esto le indica a los agentes dónde realizar cambios.

La estructura de directorios funciona como documentación con alineación de nombres entre pilas. Para una funcionalidad como "Loop": backend/internal/domain/loop/ para estructuras de datos, backend/internal/service/loop/ para lógica, web/src/components/loops/ para el frontend. Este mapeo directo del concepto de producto a la ruta de código elimina la necesidad de que los agentes exploren toda la base de código.

Amplificación de la Deuda Técnica

La deuda técnica se propaga exponencialmente con los agentes de IA. Cuando los desarrolladores hacen compromisos temporales—evitando la capa de servicio para consultar la base de datos directamente o usando números mágicos codificados—los agentes reutilizan sistemáticamente estos patrones como enfoques legítimos. A diferencia de los ingenieros humanos que reconocen el código malo como minas terrestres, los agentes tratan los patrones existentes como precedentes válidos.

La conclusión práctica: la refactorización regular se vuelve esencial no por estética sino para mantener la pureza de la señal de ingeniería. Cuando dominan las buenas prácticas, los agentes amplifican las buenas prácticas; cuando dominan los atajos, los agentes amplifican los atajos. Esto representa un costo de mantenimiento único en el desarrollo colaborativo con agentes.

Tipificación Fuerte como Puerta de Calidad

Usar Go + TypeScript + Proto proporciona detección de errores en tiempo de compilación que desplaza los errores del agente del tiempo de ejecución al tiempo de desarrollo. Las funciones generadas por el agente con firmas incompatibles causan fallos de compilación. TypeScript detecta inmediatamente incompatibilidades de formato de API. El código generado por Proto no compilará si los formatos de mensaje cambian sin sincronización con el backend. Estos errores pasarían al tiempo de ejecución en lenguajes débilmente tipados.

Sistema de Retroalimentación de Cuatro Capas

Los agentes necesitan cuatro capas de retroalimentación para una iteración eficiente:

• Compilación — recarga en caliente, reinicios de Go en menos de 1 segundo, errores de tipo de TypeScript marcados en tiempo real. Elimina errores de sintaxis y tipo.
• Pruebas unitarias — 700+ pruebas que cubren las capas de dominio y servicio. Los agentes saben en 5 minutos si introdujeron regresiones, especialmente para condiciones límite como el aislamiento multiinquilino.
• Pruebas E2E — validación de extremo a extremo de rutas funcionales reales. Detecta problemas de integración que las pruebas unitarias no alcanzan.
• Canalización de CI — cada PR ejecuta la suite completa de pruebas, linting, verificación de tipos, compilación multiplataforma. La red de seguridad final antes de la fusión.

Las cuatro capas proporcionan latencia creciente y cobertura expandida: la capa uno confirma cambios de una sola línea, mientras que la capa cuatro valida la refactorización entre módulos.