Architectures Agents Can Read
Legacy systems do not merely have old code. They have old organizational memory in a format agents cannot safely consume.
The phrase “AI-friendly codebase” is becoming an architectural requirement.
Some 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.
Other systems ask the agent to infer an organization.
That is where things get expensive.
Legacy systems don’t merely have old code. They encode old communication patterns. Conway’s 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.
An 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.
This 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.
Vibe Coding Is Low Node Density
The 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.
For 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.
Production is where the missing middle layers show up.
The 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.
A 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.
A vibe coder often supplies a wish.
The 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.
Moltbook is a useful warning because the failure was boring. According to Business Insider’s February 2026 reporting 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.
If the constraint isn’t present, the model may not invent it.
Legacy Is A Retrieval Problem
Enterprise 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.
That is only the surface.
The 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.
The 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?
Most legacy companies don’t know the answers in machine-readable form. Many barely know them in human-readable form.
So the agent applies the public pattern. In a greenfield SaaS app, that may be good enough.
In a legacy enterprise, the public pattern can be wrong because the real architecture is the fossil record of the company.
The research on domain-specific languages shows how deep this goes. An industrial case study at BMW (arXiv 2604.24678, April 2026) found that ordinary prompting was not enough for repository-scale generation in their 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.
A private language your agents can’t learn becomes a tax on every change they touch.
MCP Is A Start, Not An End
Anthropic introduced the 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.
I think MCP matters because it admits that context is now infrastructure.
A 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.
The 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.
This 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.
Agents need a world they can interrogate without accidentally changing it. Then they need a smaller world where they can act.
Agent-Readable Architecture
I’d define an agent-readable system by four properties, each with a blunt test attached.
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?
Many 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.
Agents don’t have that network unless the company builds it.
The research is converging on this from below. Princeton’s SWE-agent team (arXiv 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, February 2026) found that 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.
Platform companies are circling the same idea for products and calling it agent experience. 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.
This 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.
Legacy 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.
An agent-readable architecture is one where the machine can find the rule, touch the right surface, and fail loudly when it misunderstands.