Por qué el monorepo modular es adecuado para los agentes de programación: Ver todo, tocar poco.

Un viejo debate con nuevos riesgos

Durante años, los ingenieros se han dividido en dos grupos. Uno mantiene todo el código en un único repositorio, mientras que el otro asigna un lugar propio a cada componente, con numerosos compromisos intermedios. Nadie tiene razón en todos los casos, y quien afirma lo contrario suele estar extrapolando a partir de un solo proyecto. Si se pregunta si un monorepo o un polyrepo es mejor, la respuesta sincera es “depende”: de lo grande que sea el sistema, de cuán estrechamente estén vinculadas sus partes, de quiénes formen el equipo y de la frecuencia con la que se lanzan las actualizaciones. Algunos servicios poco relacionados entre sí deben estar en repositorios separados. En cambio, un producto diseñado de forma estrecha alrededor de contratos compartidos apunta en dirección opuesta.

Los agentes de codificación intensificaron aún más el debate. Si se les asigna una tarea que involucra un frontend, una biblioteca compartida y un contrato de backend, la estructura del repositorio deja de ser cuestión de preferencias personales. Sus consecuencias se reflejan en la calidad del código, en la frecuencia con la que el agente debe adivinar y en el grado de desorientación que experimenta. Este caso se presenta desde el interior de una configuración TypeScript NX que abarca seis plataformas. Se trata de un punto de vista específico, que no coincidirá con el de todos, por lo que debe considerarse como una opinión firme destinada a iniciar una conversación. Cuatro palabras resumen esta afirmación: verlo todo, tocar poco.

Acantilado uno: barreras que el agente no puede superar

Imagínese el mundo dividido en el que trabajan la mayoría de los equipos: un repositorio de frontend, un par de repositorios de servicios de backend, un paquete shared-types en un registro privado y un repositorio de infraestructura. Las fronteras tienen sentido y cada componente tiene un responsable.

Supongamos que a un agente en el repositorio frontend se le pide que modifique la forma en que llama a un endpoint que pertenece a un repositorio de servicio al que no puede acceder. Al no contar con un procesador para leer la respuesta, este debe adivinar cómo será. Un stub de tipo obsoleto o un ejemplo de prueba aislado se convierten en su única evidencia. El resultado se compila en la máquina local, pero es probable que esté incorrecto una vez integrado. Cada límite entre repositorios es como un muro que el agente no puede traspasar, y este recurre a suposiciones plausibles para superarlo. Lo que protege a los humanos deja a los agentes con sed de información.

Los equipos cubren esta brecha de tres maneras principales, y algunas de las soluciones son efectivas:

• Git submodules colocan los repositorios de dependencias dentro del repositorio principal, de modo que la estructura de archivos parezca unificada. El agente puede leer todo ello, pero a un costo habitual: los commits fijados se desvían, mantener todo actualizado se convierte en una tarea laboriosa, y el flujo de trabajo no satisface a nadie.
• Los espacios de trabajo de IDE multi-raíz permiten que Cursor o VS Code indexen varios repositorios juntos, lo cual es útil cuando el objetivo es simplemente leer su contenido. Sin embargo, esta configuración pertenece a una sola máquina y no al proyecto, por lo que el agente recibe una gran cantidad de archivos sin un grafo de dependencias. Sabe que existe código, pero no qué depende de qué.
• Los monorepos sintéticos son la opción más adecuada. Por ejemplo, Polygraph de NX une repositorios separados en un único grafo de dependencias mientras mantiene el código en su lugar original. Un agente coordinador consulta ese grafo para determinar qué repositorios afecta un cambio, inicia un agente en cada uno de ellos y abre las solicitudes de pull correspondientes, además de hacer seguimiento del proceso de integración continua en todas partes. Este enfoque se acerca más al comportamiento de un monorepo sobre la estructura de un polyrepo.

Se debe respeto al enfoque sintético, pero fíjense en lo que realmente hace: crea túneles a través de paredes que siguen en pie. Los ingenieros invierten mucho esfuerzo en la capa de herramientas para recrear la visibilidad que un monorepo ofrece de forma estructural y sin costo alguno. Y cuando no existen estas herramientas, el ser humano se convierte en el túnel: lee el servicio B, transmite las enseñanzas al agente del servicio A, pega las definiciones de tipo en el chat y actúa como mensajero entre sesiones cerradas.

El segundo obstáculo: el montón sin estructura

Entonces, ¿todo se traslada a un único repositorio y el asunto queda resuelto? No del todo. Un monorepo sin estructura interna funciona peor, porque es tentador. Todo está visible, lo cual parece suficiente. En realidad, hay un único directorio enorme de aplicaciones, bibliotecas que se importan entre sí desde todos los ángulos, sin límites impuestos y sin idea de a quién pertenece cada parte.

Aquí, el contexto amplio resulta perjudicial. Un agente que ve todo no recibe indicación alguna sobre qué omitir. La ventana se llena de código que se encuentra cerca en el disco pero que es irrelevante para la tarea; una sola edición afecta a importaciones que nadie ha monitoreado, y la pregunta importante, ¿qué afecta este cambio?, recibe como respuesta “posiblemente todo”. La visibilidad sin estructura es ruido, no contexto, y por eso depositar todo el código en un único repositorio no es la solución adecuada.

Tres pilares de un monorepo modular

Un monorepo modular triunfa al hacer tres cosas al mismo tiempo. Si se descuida alguna de ellas, se pierde el equilibrio.

Contexto abierto. Un único árbolo contiene todo, y el agente puede recorrerlo: interfaz de usuario, backend, bibliotecas compartidas, pruebas y los contratos de tipo que los unen, en una sola sesión. Sin barreras, sin conjeturas, sin necesidad de intermediarios. La hoja de ruta de NX destaca especialmente este aspecto, y con razón, ya que un agente que lea al productor de un contrato y a todos sus consumidores de una sola vez podrá realizar ediciones más precisas.

Encapsulación. Las bibliotecas están delimitadas y exponen interfaces públicas explícitas, por lo que el agente no necesita tener todo el sistema en mente. Trabaja sobre una parte específica. Es este equilibrio el que permite que se coexistan la visión total de todo y la intervención limitada en cada elemento; sin él, el contexto abierto se desmorona.

Un verdadero grafo de dependencias, con herramientas para explorarlo. Este es el pilar que la gente subestima. NX trata el grafo como un artefacto de primera clase que se puede consultar. En lugar de buscar manualmente con la esperanza de inferir la estructura, el agente puede ejecutar nx show projects, abrir nx graph, preguntar qué afecta un cambio y recibir una respuesta precisa que una máquina pueda analizar. El mapa se encuentra en el repositorio y no en una wiki ni en la memoria de un ingeniero senior, y es ejecutable.

Juntos, estos elementos resuelven la tesis en cuatro palabras: ver todo es el primer pilar, tocar poco es el segundo pilar, y saber qué poco tocar es el tercer pilar, el puente que permite combinar de forma segura los dos primeros.

Adquirir y verificar

Los agentes operan en un ciclo de obtención de contexto, modificación de código, verificación de los cambios y repetición del proceso. Toda la higiene del monorepo cumple una de dos funciones: obtener el contexto de forma económica o verificar una acción de forma económica.

• Tipos fuertes (adquisición). Una biblioteca de tipos compartida proporciona al agente un contrato que puede leer y que el compilador puede hacer cumplir. Esto resuelve el problema del agente ciego mencionado en el primer escenario, ya que no es necesario adivinar la estructura de las respuestas cuando está definida y verificada por escrito. Los tipos también sirven como documentación que nunca se vuelve obsoleta.
• Reglas de limpieza y de límites de módulos (verificar). Gracias a @nx/enforce-module-boundaries de NX, una importación prohibida genera un error en lugar de pasar desapercibida, y dicho error se muestra dentro del propio bucle del agente como retroalimentación. Si el agente conecta una biblioteca de interfaz de usuario con la capa de datos, la regla lo impide, y la arquitectura se aprende a partir del fallo sin que nadie tenga que describirla manualmente.
• TDD y pruebas afectadas (verificar). nx affected permite realizar verificaciones rápidas y sencillas. Después de editar un fragmento de código, el agente ejecuta únicamente las pruebas relacionadas con él y obtiene de inmediato un resultado positivo o negativo, sin tener que esperar a que se ejecuten todas las pruebas ni dudar de si el cambio funcionó. Los bucles cortos son lo que hace que trabajar con agentes parezca más bien una tarea de construcción que de supervisión constante.
• Habilidades y AGENTS.md o CLAUDE.md (adquirir). Al ejecutar npx nx configure-ai-agents en un espacio de trabajo se instala un servidor MCP, las habilidades del agente y los archivos de convención. Las habilidades se cargan según sea necesario y no todas de una sola vez en la solicitud, por lo que la forma de estructurar una biblioteca se aprende justo cuando se está creando. También guían al agente para que consulte el grafo en lugar de realizar búsquedas simples, lo que vuelve a relacionarse con el tercer pilar.
• Guías atómicas por módulo (adquirir). Cada biblioteca puede contener un breve README o AGENTS.md que proporciona contexto local justo donde el agente acaba de llegar. Al acceder a esa biblioteca, se incluyen su contrato y sus convenciones sin cargar el resto del contenido de la misma.

Si se cuenta la lista, se obtiene la secuencia adquirir, verificar, verificar, adquirir, adquirir, aunque el orden es casual. Cada funcionalidad se adapta a una de estas dos tareas. Un monorepo modular no es una sola característica para los agentes, sino muchas pequeñas que mantienen el proceso rápido y eficaz.

Los argumentos en contra

Nadie se beneficia de un discurso de venta, así que considere el contraargumento. Las ventanas de contexto siguen ampliándose, y los espacios de trabajo multi-raíz junto con las herramientas de tipo synthetic-monorepo van reduciendo la brecha. Un escéptico podría considerar la ventaja del monorepo como un artefacto temporal debido a las limitaciones actuales, algo que desaparecería con ventanas lo suficientemente grandes y herramientas adecuadas para trabajar entre repositorios. La versión más precisa no tiene que ver con las ventanas. El polígrafo demuestra que se puede reconstruir un grafo de dependencias sobre un polyrepo, por lo que la estructura que a menudo se atribuye a los monorepos no puede ser exclusivamente suya.

Cada versión comete el error de no entender de dónde proviene el beneficio. Nunca se trató de leer más texto en bruto, sino de la estructura. Una ventana más grande permite que un agente perdido se pierda en detalles más finos sin poder identificar la puerta correcta. Un grafo sintético también es una estructura, lo que explica por qué funciona, pero esa estructura se reconstruye y mantiene sobre la división del contenido y no proviene del diseño original. El contexto en bruto crece con el modelo, la estructura crece con la disciplina, y la estructura convierte ver todo como un peligro en una ventaja. A medida que las ventanas aumentan, un monorepo que carece de módulos se vuelve más arriesgado, porque las posibilidades de error se amplían. El adjetivo es quien soporta esa carga.

Lo que reveló la era de los agentes

Los gráficos de proyectos, los límites de módulos y los tipos compartidos parecían ser solo conveniencias para un equipo humano. La era de los agentes reveló lo que siempre habían sido: una interfaz para colaboradores no humanos. La arquitectura diseñada para el pensamiento humano resultó ser ingeniería de contexto a nivel de repositorio, años antes de que existiera ese término. Eso explica por qué algo distinto a los monorepos vuelve a estar de moda. El monorepo modular respondió silenciosamente a una pregunta que aún nadie había planteado: verlo todo, tocar poco, y los agentes simplemente lo hicieron evidente.