Tus agentes de IA tienen un archivo de reglas. No tienen un modelo de tu sistema.

Abre el CLAUDE.md, AGENTS.md o .cursor/rules que hay en la raíz de tu repository y léelo tal como le llega a un agente: como un bloque de texto, sin nada dentro que marque qué líneas siguen siendo ciertas.

La mayor parte de lo que encontrarás son convenciones. Usa tabs. Nada de any. Retorna pronto. Envuelve los errores con %w. Esas líneas son duraderas, porque describen cómo escribir una línea de código, y el agente las aplica al código que tiene delante.

Luego está el otro tipo de línea. La que describe tu sistema: qué servicios existen, qué paquete es dueño de qué, cómo se les permite hablar a las capas entre sí. Esas líneas son la razón de que el archivo merezca la pena, y son las que se pudren.

Lo sé porque el nuestro se pudrió.

Lo que se quedó obsoleto en el nuestro

El repository de Archyl tiene un CLAUDE.md en la raíz. Es de los buenos según los estándares del género: 422 líneas, un árbol de arquitectura, las variables de configuración, el cableado de la inyección de dependencias, una descripción del pipeline de discovery. Todo agente que toca esta codebase lo lee antes de hacer ninguna otra cosa.

Esto es lo que decía la mañana en que escribí esto, el 5 de agosto de 2026. Línea 392:

No test suite: The codebase currently has no Go test files or frontend tests.

Sin suite de tests: la codebase no tiene actualmente ficheros de test en Go ni tests de frontend.

Hay 146 ficheros _test.go bajo backend/ y 31 ficheros de test bajo frontend/src/.

La línea 140 dice:

AI Provider Abstraction: Supports both OpenAI and Ollama via ai.Provider interface.

Abstracción de proveedor de IA: soporta tanto OpenAI como Ollama a través de la interfaz ai.Provider.

backend/internal/adapter/ai/resolver.go enruta a OpenAI, Anthropic, Gemini, Bedrock y cualquier endpoint compatible con OpenAI, además de la ruta de OpenAI y Ollama gestionada por la plataforma. Cinco tipos de proveedor en un solo switch. El archivo nombra dos.

Y el árbol de arquitectura, en las líneas 74 a 87, lista once paquetes bajo internal/domain/: c4, project, user, team, adr, projectdoc, flow, insight, subscription, dependency, history. Hoy hay cuarenta y un directorios en internal/domain/. Entre los treinta que no menciona: conformance, drift, apicontract, marketplace, reality, managedagent, mcpsession. Es decir, casi todo aquello en lo que se ha convertido el producto desde que se escribió el archivo.

Cada una de esas líneas era cierta el día en que se tecleó. Ninguna se corrigió después, porque corregirlas exige que una persona se dé cuenta, y no había nada vigilando.

Esta es una empresa que vende documentación de arquitectura. Si la disciplina fuera la solución, habría funcionado aquí.

Las dos mitades de ese archivo no tienen nada en común

La mitad de las convenciones es aplicable. "Nada de fmt.Println en Go" es un grep. "Los ficheros Go deben ser snake_case" es un script. Si un agente incumple una, un linter lo dice en CI. Si la convención misma cambia, el linter empieza a fallar y alguien actualiza el archivo. Hay un bucle de realimentación, y es lo bastante corto como para funcionar.

La mitad del sistema no tiene equivalente. No hay ningún go vet para "el servicio de pagos tiene prohibido el acceso directo a la base de datos". Nada parsea esa frase, nada la compara con el repository, nada falla cuando deja de encajar. Es prosa en un fichero markdown, y la prosa no tiene modo de fallo.

Así que un archivo de reglas son dos documentos compartiendo un nombre de fichero. Uno se verifica continuamente, el otro no se verifica nunca, y nada en el archivo los distingue. "Envuelve los errores con %w" y "la codebase no tiene tests" están en la misma lista, con la misma voz. Uno es una regla sobre el código que el agente tiene delante. El otro es una afirmación sobre 146 ficheros que no está mirando.

La ausencia es la mitad más difícil

Quedarse obsoleto es el fallo que todo el mundo puede imaginarse. El más silencioso importa más: un archivo de reglas contiene solo aquello que a alguien se le ocurrió escribir, y nada dentro distingue "esto no existe" de "nadie lo mencionó".

El nuestro no menciona nunca internal/adapter/marketplace/. Ese paquete contiene una interfaz de proveedor y ocho adaptadores: GitHub, GitLab, Argo CD, Datadog, Prometheus, Sentry, SonarQube, PagerDuty. La lista de adaptadores en CLAUDE.md se detiene en git, ai, stripe, email, osv y registry. Nada de lo que el archivo dice sobre el marketplace es incorrecto. El archivo no tiene ninguno.

No he hecho el experimento de pedirle a un agente que añada una novena integración, y no voy a decirte qué produciría, porque me estaría inventando el resultado. Lo que sí puedo decirte es que el mapa no lleva ningún marketplace dibujado, y que esa es la condición ordinaria de todo archivo de reglas que he leído, incluidos los que escribí yo.

Un modelo no tiene esa propiedad. Puedes preguntarle a un modelo qué existe y obtener una respuesta que significa algo, porque la respuesta es una consulta sobre un conjunto y no una búsqueda a través de prosa. "Qué habla con el servicio de pagos" es una pregunta que un grafo puede responder y un párrafo no.

Las dos respuestas obvias, y por qué ninguna se sostiene

Escribe un archivo de reglas mejor. Más largo, más cuidadoso, con una casilla en la plantilla de pull request. Los equipos hacen esto, y funciona durante unas semanas. No aguanta, por una razón que no tiene que ver con la disciplina: cada línea que describe el sistema es una copia en caché de algo que vive en otro sitio, y las cachés necesitan invalidación. Aquí, la invalidación es una persona dándose cuenta. Ese es el mecanismo entero, y es el mismo que se suponía que iba a mantener exactos los diagramas de arquitectura durante los últimos veinte años. Ya sabemos cómo fue; la guía de detección de drift es la versión larga de ese argumento.

Deja que el agente lea el repository. Puede hacerlo, y para una pregunta sobre un solo fichero debería. Pero leer el código no te dice qué fronteras fueron deliberadas. La interfaz que hay delante de un servicio tiene el mismo aspecto tanto si está ahí por una decisión tomada hace dos años tras un incidente, como si está porque a alguien le gustan las interfaces. La intención no se recupera desde el artefacto que resultó de ella. Por eso existe el archivo de reglas en primer lugar, y por eso borrarlo tampoco es la respuesta.

Alguien de fuera de esta empresa se dio cuenta de lo mismo

Thoughtworks puso "Architecture drift reduction with LLMs" en el anillo Assess del Technology Radar Vol. 34, publicado en abril de 2026. Su apertura:

Increased use of AI coding agents can accelerate drift from the intended codebase and architecture designs. Left unchecked, this drift compounds as agents and humans replicate existing patterns, including degraded ones, creating a feedback loop where poor code begets poorer code.

El uso creciente de agentes de código con IA puede acelerar la desviación respecto a la codebase y los diseños de arquitectura previstos. Sin control, este drift se acumula a medida que agentes y humanos replican patrones existentes, incluidos los degradados, creando un bucle de realimentación en el que el código malo engendra código peor.

Assess, según la propia definición del radar, significa "worth exploring with the goal of understanding how it will affect your enterprise" — vale la pena explorarlo con el objetivo de entender cómo afectará a tu empresa. No es una recomendación de nada, y desde luego no de nosotros. Es una nota de que algunos de sus equipos están probando esto y de que es pronto.

La parte útil es la forma que describen: herramientas de análisis determinista (nombran Spectral, ArchUnit y Spring Modulith) combinadas con evaluación por LLM, porque la estructura la puede comprobar un programa y la intención no. La lección que reportan también merece que se la robemos: el primer escaneo saca a la luz más violaciones de las que nadie quiere triar.

Fíjate en lo que no está en esa receta. La respuesta de nadie al drift acelerado por agentes es un fichero markdown más largo.

Qué tendría que hacer el artefacto

Dos propiedades. Ninguna es exótica.

Tiene que enumerar. Deberías poder preguntar qué existe y recibir el conjunto, no el recuerdo que alguien tenga de él. Eso significa un artefacto que consultas en lugar de leer, y la diferencia se nota más que nunca en las preguntas que nadie dejó escritas.

Tiene que ser falsable. Algo debe compararlo con el código y reportar qué partes han dejado de ser ciertas, con una cadencia que no sea "cuando una persona se dé cuenta". ArchUnit hace esto para reglas de capas en Java. dependency-cruiser lo hace para imports de JavaScript. Ambos son deliberadamente estrechos, y ambos dejan claro el punto: el artefacto que merece la pena tener es aquel con el que un programa puede estar en desacuerdo.

Un archivo de reglas suspende en ambas. No enumera, y nada puede llevarle la contraria.

Dónde estamos, y qué no puedo contarte

Archyl mantiene un modelo C4 de tu sistema: sistemas, containers, componentes, relaciones, generados desde el repository por AI Discovery y aprobados por una persona en lugar de dibujados por una. Ese modelo es la mitad enumerable, y los agentes llegan a él por MCP, el equivalente a 181 herramientas, para que un agente pregunte qué existe en lugar de esperar que alguien lo haya escrito. La mitad de las convenciones es un catálogo de conformance: 169 reglas repartidas entre 23 tecnologías con nombre más un conjunto agnóstico del lenguaje, comprobaciones deterministas en lugar de prosa. Y el modelo se vuelve a contrastar con el código y se puntúa, que es la propiedad de falsabilidad.

Tener un servidor MCP no es la parte interesante, y quien te lo venda como diferenciador te está vendiendo un enchufe. Structurizr trae uno y el de IcePanel está en beta abierta. La pregunta sobre la que merece la pena discutir es si la cosa que hay detrás del enchufe se mantiene, porque un endpoint sirviendo un modelo que se quedó obsoleto en marzo es solo una forma más rápida de equivocarse.

Creo que esa es la diferencia que importa. No puedo demostrarlo. Nadie ha medido si un agente que trabaja desde un modelo mantenido escribe código mejor formado que un agente que trabaja desde un archivo de reglas cuidadoso, y hasta que alguien lo haga, esa frase es una afirmación sobre un mecanismo, no un resultado. Sostenla así, y replica a cualquiera que la enuncie más plana de lo que acabo de hacerlo yo.

Aquí hay también un pliegue honesto. Archyl genera un archivo de reglas. La herramienta MCP get_agent_context devuelve la arquitectura como un briefing en markdown que puedes commitear a tu repository, lo cual es un archivo de reglas con otro nombre. El archivo nunca fue el problema. El problema era que no había nada detrás de él, así que nada podía regenerarlo. Un archivo de reglas que es la caché de un modelo mantenido está bien. Un archivo de reglas que es la única copia es una instantánea de lo que una persona creía una tarde.

La versión de cinco minutos, que no te cuesta nada

Ignora todo lo de arriba y haz esto en su lugar.

Abre tu archivo de reglas. Ve línea por línea y marca cada una como convención, es decir, le dice al agente cómo escribir código, o como afirmación, es decir, le dice al agente algo sobre tu sistema. Después, para cada afirmación, escribe qué te avisaría de que ha dejado de ser cierta.

Mi apuesta es que llegarás al final del archivo con la segunda columna vacía. Ese es el hueco. Qué haces al respecto es una decisión aparte, y no tienes que comprar nada para verlo.

El nuestro llevó unos minutos y sacó tres líneas equivocadas. Arreglarlas es un commit, y no cambia nada estructural: la siguiente línea se quedará obsoleta de la misma manera, y tampoco hay nada vigilando esa.