{"slug": "context-architecture-the-day-i-realized-the-whole-repo-is-the-context", "title": "Context Architecture: the day I realized the whole repo is the context", "summary": "A Skyward engineer discovered that AI agents follow patterns in the repository code, not instructions in prompts, leading to repeated violations of design rules. The engineer introduced Screaming Architecture to organize the monorepo by domain, which improved agent behavior but still allowed stale documentation and deprecated code to mislead agents. This realization led to the concept of Context Architecture, where every claim a repository makes about itself must be tied to a mechanism that fails when the claim becomes false.", "body_md": "That sentence took me a while to understand. In this post I'll save you the trip.\n\nIt 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.\n\nThe agent did exactly what I told it not to do.\n\nIt wasn't that it didn't listen to me. It was that it read the code and saw something else there.\n\nAn 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.\n\nSo 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.\n\nMy 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.\n\nAt some point, tired of repeating myself, I understood the obvious thing.\n\nThe 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.\n\nThe repo itself is the context agents use. If it's badly structured, the answers won't be good. Period.\n\nNo prompt fixes a repo that contradicts itself.\n\nThe first thing I added to the monorepo was [Screaming Architecture](https://dev.to/en/blog/screaming-architecture-the-key-to-scalable-frontend), which I already wrote about here. Organize by domain, not by technology: `billing/`\n\n, `payments/`\n\n, not `controllers/`\n\n, `services/`\n\n. Let the structure scream the business intent.\n\nAnd 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/`\n\nlives 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](https://dev.to/en/blog/how-to-migrate-with-claude-code-and-not-die-trying) across the whole monorepo.\n\nBut it fell short.\n\nScreaming Architecture gives you a readable structure. It tells you where things are and what each part does. That's huge.\n\nWhat it doesn't give you is the guarantee that what the repo says about itself is true.\n\nAn `AGENTS.md`\n\ndescribing 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.\n\nAll of that lives in silence. It reads perfectly, it's well organized, it screams the right intent. And it lies.\n\nFor 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.\n\nThat 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.\n\nThat jump, from readable structure to verifiable context, is the core of what ended up being Context Architecture.\n\nIf you make me keep one single sentence, it's this:\n\nEvery 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.\n\nThat's all of it.\n\nA 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.\n\nThat's the difference between something the agent respects and something the agent ignores deliberately.\n\nI'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.\n\n`AGENTS.md`\n\nor `CLAUDE.md`\n\nat every code boundary, with what you don't learn by reading the code, the decisions, the whys, what not to touch.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.\n\nIf a repo claim doesn't touch at least one of those layers, it's hanging by a thread.\n\nThe 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.\n\nWhere I do want to be precise is the lineage, because I didn't reinvent the wheel.\n\nContext 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.\n\nIt'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).\n\nThey're not competitors. They're different layers of the same problem.\n\nBecause I already tested it and it works.\n\nContext 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](https://dev.to/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.\n\nThe 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.\n\nAnd 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.\n\nIf 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.\n\nThe repo is the context. Make it tell the truth.", "url": "https://wpnews.pro/news/context-architecture-the-day-i-realized-the-whole-repo-is-the-context", "canonical_source": "https://dev.to/sergioazoc/context-architecture-the-day-i-realized-the-whole-repo-is-the-context-3543", "published_at": "2026-06-19 00:48:10+00:00", "updated_at": "2026-06-19 00:59:24.700498+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "large-language-models"], "entities": ["Skyward", "Claude Code", "Biome", "oxlint", "oxfmt"], "alternates": {"html": "https://wpnews.pro/news/context-architecture-the-day-i-realized-the-whole-repo-is-the-context", "markdown": "https://wpnews.pro/news/context-architecture-the-day-i-realized-the-whole-repo-is-the-context.md", "text": "https://wpnews.pro/news/context-architecture-the-day-i-realized-the-whole-repo-is-the-context.txt", "jsonld": "https://wpnews.pro/news/context-architecture-the-day-i-realized-the-whole-repo-is-the-context.jsonld"}}