# Context Architecture: the day I realized the whole repo is the context > How Context Architecture started: the pain of fighting AI agents in a real monorepo, and why I ended up giving a name to a way of structuring code. ## 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](/en/blog/screaming-architecture-the-key-to-scalable-frontend), 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](/en/blog/how-to-migrate-with-claude-code-and-not-die-trying) 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](https://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](https://context-architecture.dev/comparison). 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](/en/blog/oxlint-tailwindcss-the-linting-plugin-tailwind-v4-needed), 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](https://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](https://github.com/sergioazoc/context-architecture). 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.