Tu repo ya es el contexto de tus agentes, lo hayas diseñado a propósito o no

Esa frase me costó entenderla. En este post te ahorro el camino.

Era Octubre del 2025, trabajando en el monorepo de Skyward con agentes de IA todos los días. Y todos los días la misma rutina: le decía en el prompt al agente "no uses esto", "no hagas esto así", "reutiliza el componente que ya existe". Lo escribía. Lo repetía.

El agente hacía exactamente lo que le dije que no hiciera.

No era que no me escuchara. Era que leía el código y ahí veía otra cosa.

El agente le cree al código, no a tu prompt

Un agente sigue los patrones que ve en el repo, no los que tú le dices en el prompt. Y los subagentes son peores, porque arrancan sin el contexto de la conversación. Toda la pelea que tú diste arriba en el chat, para ellos no existió nunca.

Entonces pasaba esto. Creaba un componente nuevo aunque ya había uno que resolvía exactamente el problema. No respetaba las normas de diseño ni usaba los design tokens. Seguía documentación obsoleta porque seguía ahí, viva, sin nada que la marcara como obsoleta.

Mi primer instinto fue el de todos, meter más contexto en el prompt. Más reglas, más "por favor no hagas esto", más ejemplos pegados a mano. Funcionaba a medias, y para la siguiente tarea había que volver a agregarlo todo. Hasta que llegaba el siguiente subagente y empezaba de cero.

En algún momento, cansado de repetirme, entendí lo obvio.

El agente no me estaba desobedeciendo. Estaba leyendo el repo y haciendo caso a lo que el repo decía de sí mismo. Si conviven el componente bueno y tres versiones viejas, no tiene cómo saber cuál es el oficial. Si la doc dice una cosa y el código hace otra, le va a creer al que esté más a mano. Está haciendo justo lo que le pedí.

El mismo repo es el contexto que usan los agentes. Si está mal estructurado, las respuestas no van a ser buenas. Punto.

No hay prompt que arregle un repo que se contradice a sí mismo.

Screaming Architecture me llevó hasta media cancha

Lo primero que agregué al monorepo fue Screaming Architecture, sobre la que ya escribí acá. Organizar por dominio, no por tecnología: billing/, payments/, no controllers/, services/. Que la estructura grite la intención del negocio.

Y funcionó mejor de lo que esperaba con agentes. Una estructura que grita la intención es una estructura que un agente entiende sin que le pegues medio README en cada prompt. Un agente que sabe dónde vive billing/ no se va a inventar una carpeta nueva. Con eso más buenos specs pude hacer migraciones grandes que antes habrían sido un dolor, como pasar de Biome a oxlint y oxfmt en todo el monorepo.

Pero me quedó corto.

Dónde se quedó corto

Screaming Architecture te da una estructura legible. Te dice dónde están las cosas y qué hace cada parte. Eso es enorme.

Lo que no te da es la garantía de que lo que el repo dice de sí mismo sea cierto.

Un AGENTS.md que describe un flujo que cambió hace tres meses. Un comentario que apunta a una función que ya no existe. Un design token "oficial" que la mitad del código ignora. Un módulo marcado como deprecado que tres features siguen importando porque ningún mecanismo lo prohíbe.

Todo eso vive en silencio. Se lee perfecto, está bien ordenado, grita la intención correcta. Y miente.

Para una persona eso es ruido manejable. Lees alrededor, preguntas en slack, usas tu criterio. Para un agente es veneno. El agente no tiene criterio para saber que esa línea está obsoleta. La lee, le cree, y la propaga.

Ahí estaba el agujero. Me faltaba la verificabilidad. Que todo lo que el repo afirma sobre sí mismo sea verdad, y que cuando deje de serlo, algo se rompa y me avise.

Ese salto, de estructura legible a contexto verificable, es el núcleo de lo que terminó siendo Context Architecture.

La regla que lo ordena todo

Si me hacen quedarme con una sola frase, es esta:

Toda afirmación que un repositorio hace sobre sí mismo debe estar ligada a un mecanismo que falla cuando esa afirmación deja de ser verdad. Si un dato de contexto puede pudrirse en silencio, no es arquitectura: es documentación.

Ahí está todo.

Un README que dice "usamos este patrón" y nada explota cuando dejas de usarlo, es documentación. Se va a pudrir, es cosa de tiempo. Pero un patrón que vive en una regla del linter que falla en CI cuando lo violas, eso sí es arquitectura. No puede mentir, porque si miente, el build se rompe.

Esa es la diferencia entre algo que el agente respeta y algo que el agente ignora deliberadamente.

Cómo se ve en la práctica

No voy a reexplicar acá la arquitectura completa, para eso está la spec en context-architecture.dev. Pero el resumen honesto son cuatro pilares.

• Pilar 1, la estructura grita la intención (esto es la herencia directa de Screaming Architecture).
• Pilar 2, contexto embebido: un AGENTS.md o CLAUDE.md en cada frontera del código, con lo que no se aprende leyendo el código, las decisiones, los porqués, lo que no hay que tocar.
• Pilar 3, la intención se vuelve mecanismo: la spec precede al código y define el qué, y cuando esa intención vive en tests, tipos y lint, la spec se puede borrar porque ya está enforced.
• Pilar 4, las capacidades son descubribles: tools, skills y comandos en rutas predecibles, donde el agente los va a buscar.

¿Y qué hace cumplir todo eso? Cuatro capas que hacen fallar lo falso. El compilador atrapa los tipos (typecheck). El linter atrapa la estructura. Los tests atrapan que la doc no mienta. Y el review atrapa la verdad semántica, lo que ningún agente todavía puede chequear solo. La gracia es empujar cada verdad lo más abajo posible: si algo lo puede garantizar el compilador, no lo dejes para el review humano.

Si una afirmación del repo no toca al menos una de esas capas, está colgando de un hilo.

De dónde viene el nombre (y de dónde viene la idea)

El nombre salió natural. El repo completo es el "contexto" que usan los agentes, y lo que había que mejorar era su estructura, es decir, su arquitectura. Context Architecture. Listo.

Donde sí quiero ser preciso es en el linaje, porque no reinventé la rueda.

Context Architecture hereda de Screaming Architecture (Robert C. Martin, 2011) y la extiende a la era de los agentes. Y su ancestro espiritual es TDD: los tests verifican que el código hace lo que dice; Context Architecture verifica que el repositorio dice la verdad sobre sí mismo. Es la misma idea, subida un nivel.

También es importante marcar las diferencias con dos disciplinas vecinas, porque se confunden seguido. El context engineering es runtime: qué ve el modelo ahora, en esta corrida. El harness engineering es operación: cómo opera el agente. Context Architecture es diseño: el codebase mismo, lo que existe antes de que cualquier agente lo lea y sigue ahí cuando termina. Una buena Context Architecture le baja el trabajo a las capas de arriba, porque el repo ya viene ordenado y verificable de fábrica. Lo desarrollé más en la comparación con context engineering y harness engineering.

No son competencia. Son capas distintas del mismo problema.

Por qué lo cuento ahora

Porque ya lo probé y funciona.

Context Architecture es lo que usamos en el monorepo de Skyward, no es una teoría que se me ocurrió en la ducha. Pero no me quedé ahí. La apliqué también en mi plugin oxlint-tailwindcss, que es puro dogfooding, y en la propia web de context-architecture.dev. Tres codebases reales, de dominios distintos, con la misma arquitectura debajo.

La prueba no es un número que te pueda tirar acá, tampoco me lo voy a inventar. Es la adopción real y el rigor de que las reglas se sostienen cuando el repo crece y cuando el que escribe ya no eres tú, es un agente a las 2 AM.

Y empecé a dar charlas sobre esto. La estreno en un webinar de Duoc UC, "Más allá del vibe coding: Ingeniería de software con agentes de IA". Quería tener un lugar donde dejar la idea completa, para que cualquiera pueda entrar a verla en profundidad cuando le haga sentido, sin depender de que justo viera una charla en vivo. Por eso la spec vive en su propia web y no enterrada en este post.

El cierre

Si algo de esto te hizo sentido, dos cosas concretas: lee la spec completa en context-architecture.dev, está todo ahí, los pilares, las capas, los modos de falla y cómo aplicarlo mañana en tu propio repo. Y si te sirve, déjale una estrella al repo en GitHub. Me ayuda muchísimo a que más gente lo encuentre y le da peso como proyecto real del ecosistema.

El repo es el contexto. Haz que diga la verdad.