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.
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 si lo aterrizo a lo que uso día a día, es esto.
- La estructura grita la intención (esto es la herencia directa de Screaming Architecture).
- Contexto embebido: un
AGENTS.mdoCLAUDE.mden 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. - 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.
- Las capacidades son descubribles: tools, skills y comandos en rutas predecibles, donde el agente los va a buscar.
¿Y qué hace cumplir todo eso? Mecanismos que hacen fallar lo falso, cada uno atrapando a su nivel. 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 uno de esos mecanismos, está colgando de un hilo.
En la práctica esto se vuelve un loop, y es lo que más me cambió el día a día. Cada vez que agrego contexto nuevo al repo, una convención, una fuente de verdad, una decisión sobre qué no tocar, en el mismo cambio le ato su mecanismo de verificación. No en el commit siguiente, no en el ticket de deuda que nunca llega. Ahí mismo. Y si no se me ocurre cómo verificarlo, casi siempre es que todavía no tengo claro qué estoy afirmando.
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.
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. Y no se quedó ahí. La apliqué 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.
No te puedo tirar un número acá, y no me lo voy a inventar. La prueba es que las reglas aguantan cuando el repo crece y cuando el que escribe ya no eres tú, es un agente a las 2 AM.
Y empecé a contarlo en charlas. Di una presencial en el Duoc de Puerto Montt, "Context Architecture: cómo diseñar código para personas y agentes de IA", en el marco del SummIT de IA Aplicada que organizó Duoc. También salió en el webinar "Más allá del vibe coding: Ingeniería de software con agentes de IA". Pero las charlas pasan. Quería un lugar donde la idea quedara completa y abierta, para que cualquiera entre a verla en profundidad cuando le haga sentido. Esa es la spec, y por eso vive en su propia web y no enterrada en este post.
El cierre
Si algo de esto te hizo sentido, dos cosas concretas.
Una, lee la spec completa en context-architecture.dev. Ahí está la idea entera y cómo aplicarla mañana en tu propio repo. La mantengo viva, así que va a seguir creciendo.
Dos, si te sirve, déjale una estrella al repo en GitHub. Me ayuda a que más gente lo encuentre. 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.