Post argues AI agents rely on repository context and need verifiable repo rules

Context Architecture: the day I realized the whole repo is the context

Your repo is already your agents' context, whether you designed it on purpose or not That sentence took me a while to understand. In this post I'll save you the trip. It was October 2025, working in Skyward's monorepo with AI agents every day. And every day the same routine: I'd tell the agent in the prompt "don't use this", "don't do it this way", "reuse the component that already exists". I wrote it down. I repeated it. The agent did exactly what I told it not to do. It wasn't that it didn't listen to me. It was that it read the code and saw something else there. The agent believes the code, not your prompt An agent follows the patterns it sees in the repo, not the ones you tell it in the prompt. And subagents are worse, because they start without the conversation's context. The whole fight you put up earlier in the chat, for them it never happened. So this is what kept happening. It created a new component even though one already existed that solved exactly that problem. It didn't respect the design rules or use the design tokens. It followed stale docs because they were still there, alive, with nothing flagging them as outdated. My first instinct was everyone's instinct, cram more context into the prompt. More rules, more "please don't do this", more examples pasted in by hand. It half worked, and for the next task you had to add it all again. Until the next subagent showed up and started from scratch. At some point, tired of repeating myself, I understood the obvious thing. The agent wasn't disobeying me. It was reading the repo and listening to what the repo said about itself. If the good component lives alongside three old versions, it has no way to know which one is the official one. If the docs say one thing and the code does another, it'll believe whichever is closest at hand. It's doing exactly what I asked. The repo itself is the context agents use. If it's badly structured, the answers won't be good. Period. No prompt fixes a repo that contradicts itself. Screaming Architecture got me to midfield The first thing I added to the monorepo was Screaming Architecture, which I already wrote about here. Organize by domain, not by technology: billing/, payments/, not controllers/, services/. Let the structure scream the business intent. And it worked better than I expected with agents. A structure that screams intent is a structure an agent understands without you pasting half a README into every prompt. An agent that knows where billing/ lives won't invent a new folder. With that plus good specs I was able to do large migrations that would have been painful before, like moving from Biome to oxlint and oxfmt across the whole monorepo. But it fell short. Where it fell short Screaming Architecture gives you a readable structure. It tells you where things are and what each part does. That's huge. What it doesn't give you is the guarantee that what the repo says about itself is true. An AGENTS.md describing a flow that changed three months ago. A comment pointing to a function that no longer exists. An "official" design token that half the code ignores. A module marked as deprecated that three features keep importing because no mechanism forbids it. All of that lives in silence. It reads perfectly, it's well organized, it screams the right intent. And it lies. For a person that's manageable noise. You read around it, you ask in Slack, you use your judgment. For an agent it's poison. The agent has no judgment to know that line is stale. It reads it, believes it, and propagates it. That was the hole. I was missing verifiability. That everything the repo claims about itself is true, and that when it stops being true, something breaks and tells me. That jump, from readable structure to verifiable context, is the core of what ended up being Context Architecture. The rule that orders everything If you make me keep one single sentence, it's this: Every claim a repository makes about itself must be tied to a mechanism that fails when that claim stops being true. If a piece of context can rot in silence, it's not architecture: it's documentation. That's all of it. A README that says "we use this pattern" and nothing blows up when you stop using it, that's documentation. It's going to rot, it's just a matter of time. But a pattern that lives in a lint rule that fails in CI when you violate it, that one is architecture. It can't lie, because if it lies, the build breaks. That's the difference between something the agent respects and something the agent ignores deliberately. What it looks like in practice I'm not going to re-explain the whole architecture here, that's what the spec at context-architecture.dev is for. But the honest summary is four pillars. Pillar 1, the structure screams intent (this is the direct inheritance from Screaming Architecture). Pillar 2, embedded context: an AGENTS.md or CLAUDE.md at every code boundary, with what you don't learn by reading the code, the decisions, the whys, what not to touch. Pillar 3, intent becomes mechanism: the spec precedes the code and defines the what, and once that intent lives in tests, types and lint, the spec can be deleted because it's already enforced. Pillar 4, capabilities are discoverable: tools, skills and commands in predictable paths, where the agent will go looking for them. And what enforces all of it? Four layers that make the false stuff fail. The compiler catches the types (typecheck). The linter catches the structure. The tests catch the docs lying. And review catches semantic truth, the thing no agent can check on its own yet. The point is to push every truth as far down as possible: if the compiler can guarantee something, don't leave it for human review. If a repo claim doesn't touch at least one of those layers, it's hanging by a thread. Where the name comes from (and where the idea comes from) The name came out naturally. The whole repo is the "context" agents use, and what needed improving was its structure, that is, its architecture. Context Architecture. Done. Where I do want to be precise is the lineage, because I didn't reinvent the wheel. Context Architecture inherits from Screaming Architecture (Robert C. Martin, 2011) and extends it into the age of agents. And its spiritual ancestor is TDD: tests verify that the code does what it says; Context Architecture verifies that the repository tells the truth about itself. Same idea, one level up. It's also important to mark the differences with two neighboring disciplines, because they get confused all the time. Context engineering is runtime: what the model sees right now, in this run. Harness engineering is operation: how the agent operates. Context Architecture is design: the codebase itself, what exists before any agent reads it and is still there when it's done. Good Context Architecture lowers the workload on the layers above, because the repo already comes ordered and verifiable out of the box. I went deeper on this in the comparison with context engineering and harness engineering. They're not competitors. They're different layers of the same problem. Why I'm telling this now Because I already tested it and it works. Context Architecture is what we use in Skyward's monorepo, it's not a theory I came up with in the shower. But I didn't stop there. I also applied it in my plugin oxlint-tailwindcss, which is pure dogfooding, and in context-architecture.dev's own site. Three real codebases, from different domains, with the same architecture underneath. The proof isn't a number I can throw at you here, and I'm not going to make one up. It's the real adoption and the rigor of the rules holding up when the repo grows and when the one writing is no longer you, it's an agent at 2 AM. And I started giving talks about this. I'm premiering it in a Duoc UC webinar, "Beyond vibe coding: software engineering with AI agents". I wanted a place to leave the complete idea, so anyone can go look at it in depth whenever it makes sense to them, without depending on catching a live talk at the right moment. That's why the spec lives on its own site and not buried in this post. The close If any of this made sense to you, two concrete things: read the full spec at context-architecture.dev, it's all there, the pillars, the layers, the failure modes and how to apply it tomorrow in your own repo. And if it's useful to you, drop a star on the repo on GitHub. It helps me a ton to get it in front of more people, and gives it weight as a real ecosystem project. The repo is the context. Make it tell the truth.

2 days ago

Context Architecture: el día que entendí que el repo entero es el contexto

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.

2 days ago