{"slug": "architectures-agents-can-read", "title": "Architectures Agents Can Read", "summary": "Legacy codebases encode organizational history in formats that AI agents cannot safely interpret, leading to architectural hallucinations when agents apply public-code patterns to enterprise systems. Vibe coding's low node density—too few intermediate constraints between intent and implementation—produces tutorial-shaped code that omits production security, as demonstrated by the Moltbook Supabase breach that exposed API tokens and private messages.", "body_md": "# Architectures Agents Can Read\n\n### Legacy systems do not merely have old code. They have old organizational memory in a format agents cannot safely consume.\n\nThe phrase “AI-friendly codebase” is becoming an architectural requirement.\n\nSome systems are easy for agents to work inside. The boundaries are explicit. The tests say what matters. The schemas are visible. The business rules live somewhere other than one senior engineer’s head. The agent can load a bounded context, make a change, and trip a deterministic alarm if it crosses a line.\n\nOther systems ask the agent to infer an organization.\n\nThat is where things get expensive.\n\nLegacy systems don’t merely have old code. They encode old communication patterns. [Conway’s Law](https://en.wikipedia.org/wiki/Conway%27s_law) gets physical inside a twenty-year enterprise codebase: the table name, the duplicated validator, the half-retired service, the batch job no one can remove, the permission check that lives in the caller because the platform team lost an argument in 2017.\n\nAn agent trained mostly on public code does not see that history. It sees a shape and completes the nearest public pattern. That is architectural hallucination.\n\nThis is what I mean by jagged intelligence in software. The agent can be startlingly competent in one pocket of the system and strangely naive one layer over. It produces a clean API client, then misses the business rule hidden in a batch job. It explains the architecture pattern beautifully, then applies it to the wrong organization.\n\n**Vibe Coding Is Low Node Density**\n\nThe purest version of top-down programming is vibe coding: describe the thing you want, let the model generate the implementation, run it, complain until it works.\n\nFor throwaway software, this can be delightful. I don’t want to pretend otherwise. The joy is real - I coded up a quiz show app in about 20 mins that my wife and I regularly enjoy.\n\nProduction is where the missing middle layers show up.\n\nThe problem with vibe coding isn’t the altitude. I like high abstraction levels. The problem is node density: too few intermediate constraints between intent and implementation.\n\nA senior engineer working top-down does more than say “build the app.” They supply contracts and name trust boundaries. They write fixtures, lock the migration, and decide which failures must be loud. Constraint before generation, instrumentation after.\n\nA vibe coder often supplies a wish.\n\nThe agent fills the empty space with training data, which usually means tutorial-shaped code: get the request through, make the UI respond, store the thing, return success. The median tutorial just wants the reader to feel progress before lunch.\n\nMoltbook is a useful warning because the failure was boring. According to [Business Insider’s February 2026 reporting](https://www.businessinsider.com/moltbook-ai-agent-hack-wiz-security-email-database-2026-2) on Wiz’s disclosure, researchers found a Supabase configuration problem that exposed email addresses, private messages, and a large number of API authentication tokens. Skip the easy readings, the ones where Supabase is uniquely dangerous or one startup is the symbol of all AI software. The useful lesson is subtler: functional generation won’t automatically include the security posture that production requires.\n\nIf the constraint isn’t present, the model may not invent it.\n\n**Legacy Is A Retrieval Problem**\n\nEnterprise leaders tend to describe legacy modernization as a code transformation problem. Translate COBOL to Java. Extract services from the monolith. Move workflows to cloud primitives.\n\nThat is only the surface.\n\nThe harder problem is retrieval. The knowledge needed to make a safe change is scattered across source code, deployment scripts, data contracts, incident history, regulatory interpretations, and human memory. Agents are brittle in exactly that environment because the relevant fact is rarely sitting next to the line that needs to change.\n\nThe agent needs context structured around the decision it is making. Which service owns this field? Which downstream report treats null as meaningful? Which customer migration created the exception, and which team must approve a change because their batch job still reads yesterday’s files?\n\nMost legacy companies don’t know the answers in machine-readable form. Many barely know them in human-readable form.\n\nSo the agent applies the public pattern. In a greenfield SaaS app, that may be good enough.\n\nIn a legacy enterprise, the public pattern can be wrong because the real architecture is the fossil record of the company.\n\nThe research on domain-specific languages shows how deep this goes. An industrial case study at BMW ([arXiv 2604.24678](https://arxiv.org/abs/2604.24678), April 2026) found that ordinary prompting was not enough for repository-scale generation in their [Xtext](https://en.wikipedia.org/wiki/Xtext)-based DSL; the path that worked required structured representations of the folder hierarchy plus parameter-efficient fine-tuning. It sounds narrow because the file extension is unusual. The pattern is everywhere. Every large company has a DSL, even when it doesn’t call it one: a YAML convention, a spreadsheet template that drives pricing, a workflow engine configured through UI state, or the private meaning of “eligible” inside billing code. Public training data is weak on these private languages, and the agent can still produce plausible artifacts. Plausible is not safe.\n\nA private language your agents can’t learn becomes a tax on every change they touch.\n\n**MCP Is A Start, Not An End**\n\nAnthropic introduced the [Model Context Protocol](https://www.anthropic.com/news/model-context-protocol) in November 2024 as an open standard for connecting AI assistants to data sources and tools. The announcement names exactly the problem enterprises feel: sophisticated models are constrained when trapped behind information silos and legacy systems.\n\nI think MCP matters because it admits that context is now infrastructure.\n\nA connector isn’t a brain, though. Wire an agent into Slack, GitHub, Postgres, Jira, Confluence, and a document store, and you’ve created access, not understanding. Access is where the problem starts.\n\nThe hard part is deciding what the agent is allowed to retrieve, what it should trust, how retrieved facts should be ranked, which tool calls are reversible, which side effects require approval, and which old document is superseded by last quarter’s incident report.\n\nThis is the enterprise version of node density. The organization needs constraints between intent and action: knowledge graphs, typed APIs, append-only logs, contract tests, generated architecture maps, data lineage, permissions, human approval gates. The exact tools will change. The shape will not.\n\nAgents need a world they can interrogate without accidentally changing it. Then they need a smaller world where they can act.\n\n**Agent-Readable Architecture**\n\nI’d define an agent-readable system by four properties, each with a blunt test attached.\n\n**Retrievable knowledge.** The facts a change depends on can be found by query, not by tenure. Can the agent discover who owns the API, and which contract and migrations sit behind the field it’s about to change, without asking a person?**Explicit boundaries.** Can it tell public interface from internal convenience? A system that can’t say where its edges are asks every reader to guess, and agents guess in public patterns.**Executable verification.** Can it run the relevant tests without knowing the team’s folklore? Ground truth has to be a command.**Bounded action.** Can it propose a change that touches one area, with an obvious reviewer and a rollback plan that fits in a sentence?\n\nMany great human systems are not agent-readable, because humans are good at social lookup. They ask Priya. They remember the incident, know which doc is wrong, and hear the tone in the architecture review.\n\nAgents don’t have that network unless the company builds it.\n\nThe research is converging on this from below. Princeton’s SWE-agent team ([arXiv 2405.15793](https://arxiv.org/abs/2405.15793), NeurIPS 2024) treated the agent’s view of a repository as a design problem in its own right and named it the agent-computer interface: structured search, bounded file views, edit commands, and feedback on every change. Interface design alone changed what the same model could fix. The readability lives in the environment, not the weights. The counterevidence is just as instructive. A study of repository context files ([arXiv 2602.11988](https://arxiv.org/abs/2602.11988), February 2026) found that [AGENTS.md](https://agents.md/)-style files raised inference cost by over 20% on average without generally improving success. The popular repository-overview format didn’t help at all. The files earned their keep in one place: specifying non-standard practices the agent couldn’t guess. Curated exceptions helped where volume didn’t.\n\nPlatform companies are circling the same idea for products and calling it [agent experience](https://biilmann.blog/articles/introducing-ax/). The research world has it for tools. Nobody has written the formal treatment at the system level, the one that would tell a CTO what to excavate first, and I’m suspicious of anyone who claims to have it this early. These four properties are my working draft. I expect the field to overwrite them.\n\nThis is where I think the next architecture competition happens. AI-native companies won’t merely be faster because they use agents. They will be faster because their systems will be born with fewer private meanings: code, docs, tests, schemas, and operational history arranged so an agent can retrieve the right slice and act inside a bounded scope.\n\nLegacy companies still have domain depth, and that depth is valuable, but is it retrievable? The agent sees the codebase the way a consultant sees an org chart on day one: confidently, incompletely, and with fallible optimism.\n\nAn agent-readable architecture is one where the machine can find the rule, touch the right surface, and fail loudly when it misunderstands.", "url": "https://wpnews.pro/news/architectures-agents-can-read", "canonical_source": "https://www.khola.blog/p/architectures-agents-can-read", "published_at": "2026-07-11 18:16:03+00:00", "updated_at": "2026-07-11 18:35:04.756202+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-agents", "ai-safety", "ai-ethics", "developer-tools"], "entities": ["Supabase", "Moltbook", "Wiz", "Business Insider"], "alternates": {"html": "https://wpnews.pro/news/architectures-agents-can-read", "markdown": "https://wpnews.pro/news/architectures-agents-can-read.md", "text": "https://wpnews.pro/news/architectures-agents-can-read.txt", "jsonld": "https://wpnews.pro/news/architectures-agents-can-read.jsonld"}}