You open a pull request written by an AI agent, and it looks great. Clean functions, consistent names, green tests. You hit merge, and two weeks later adding a simple feature feels terrifying: touch one module and a neighboring one breaks. The code looks clean locally, yet the project as a whole is quietly falling apart.
Metarhia creator Timur Shemsedinov unpacked this paradox in his talk 'AI and Architecture 3: A Specification That Doesn't Drift from Code!—Does the Model Invent Requirements?' and paired it with a live experiment from HowProgrammingWorks. Regular documentation won't save you here because it starts lying almost immediately. Let's see where AI breaks systems and how to keep them under control.
How an AI Agent Breaks Your Project While You Praise Its Diffs
The core trap of modern code review is simple: a pull request diff shows lines of code, not system-wide properties. You look at a fresh function and it looks spotless. Yesterday it was a pure function with no side effects; today the agent quietly wired in mutable shared state or broke idempotency (the rule that repeating a request produces the exact same result). The file shines, while a time bomb ticks inside the system.
Then comes round-the-clock duplication. A model can't hold the entire repository in its head, so it happily reinvents the wheel right next to an existing module. Shemsedinov gives a familiar example: one project ends up with five different text editors, or separate invoice parsers in accounting, HR, and sales. Each one is written decently—they just know nothing about each other.
On top of that, neural networks love extra layers because they trained on real-world internet code, which is often overengineered. Non-functional requirements (NFRs—speed, reliability, security, fault tolerance) fare even worse. If you don't state them explicitly, the model stitches together an 'average internet solution' with random NFRs that silently mutate with every new prompt.
Eventually, you lose ownership of the code. You don't need to read every line of a generated report, but a human developer has to understand the overall system design. Shemsedinov pokes fun at the dead end of mindless vibe coding: you can't tell a client, 'Let me go ask the AI what's going on in our project—I have no idea myself, I just pass questions along.'
Invisible Threads in Node.js: Where Hidden Dependencies Come From
Look at a familiar detail in Node.js. Where do require, __filename, process, console, or setTimeout come from in a plain JS file? You never imported any of them. Under the hood, the runtime and bundlers wrap your file in an internal header and inject those objects. In effect, hidden DI (Dependency Injection—passing required tools into a module from the outside) is already baked into the module system.
In a real project, that coexists with import/export, global context, constructors, methods, DI containers, and another pattern: a module exports a function, and dependencies are passed in later via a closure when it's called. Standard static analyzers are 'naive' here—they see explicit imports and standard DI, but miss circular links and deferred closure dependencies.
From that specific pain comes a general rule. All coupling (one module depending on another's internals) boils down to three channels.
| Coupling channel | How it looks in code | Main trap |
|---|---|---|
| API calls | Direct calls to functions and methods | Easier to trace, though chaotic DI still obscures the graph |
| Event streams | EventEmitter, brokers, and event buses | Events hop across buses, get serialized, and land in another layer |
| Shared data | Shared collections, caches, shared state | Hurts maintainability without strict write rules and locks |
Event streams are the sneakiest. Without a separate map, neither a human nor an agent can tell who subscribed to what or where an event went. Shared data, by contrast, isn't always pure evil: if you guard it with mutexes or the Web Locks API, use immutable structures, or restrict writes to a single module while others only read, sharing stays fast and predictable. What matters is seeing all three channels at once.
Executable Specifications and a Two-Day Metarhia Testbed
A fair question: why not just draw a diagram in UML, Mermaid, or PlantUML and keep it next to the code? AI reads them well, and humans can render a picture easily.
There's one catch: those diagrams don't execute. The moment someone edits a service or adds an event, the diagram and text spec start lying. And rewriting every line of code in docs is just double work.
Shemsedinov's idea is an executable spec. A strict declarative DSL (Domain-Specific Language—a focused language for a specific job) describes layers, modules, event and data flows, DI and IoC (Inversion of Control, where an external loader hands a module its dependencies instead of the module hunting for them), DB connections, server instances, and an access matrix of who can call whom. A loader program reads this DSL on startup, spins up modules, wires dependencies, subscribes to events, and routes requests. Because the spec assembles the app itself, it physically cannot drift from the code. The syntax is designed to be pluggable, so the same structure can be written in JS, TS, Lisp, or Markdown.
One important caveat: right now this is the author's working prototype, not a production-ready package. Shemsedinov has been testing variations for two to three years and is only now unifying the format for a future open-source release—there is no public repository yet.
A live testbed already exists, though. In a HowProgrammingWorks note, Timur described building a massive all-in-one prototype with AI in two days on the Metarhia stack (WebRTC plus the open RPC protocol Metacom): a hybrid of YouTube, a messenger, Google Meet, Discord, StreamYard, Telegram, torrents, blockchain, and a video editor. When servers are up, it runs client-server; when they drop, it switches to peer-to-peer. It isn't a production Discord replacement (the code was only shown on a private call), but a test codebase written entirely by AI to check how an architectural language helps navigate it.
For non-executable parts of a spec, he suggests cross-references and a 'project tech map' (so AI doesn't dig through the entire repo for one fact), backed by automated gates: type checkers, ESLint, Prettier, and architectural tests.
Why a Project Needs an ADR Folder: What AI Can Never Read in Code
Okay, you might say, that custom DSL isn't open-sourced yet—what can you actually do in your project today?
Start with what isn't in the source code at all. Code shows what was written and how, but it never explains why that option was chosen: what business constraints applied, what alternatives were rejected, and what NFRs were set at the start.
That's what ADR (Architecture Decision Records) are for—short text notes capturing key decisions. Shemsedinov recommends keeping an ADR folder right inside the repository so both humans and AI agents read it. Then, on every new task, the model builds on real project context instead of inventing requirements on the fly.
Minimum Safety Net Against AI Chaos
- Create an ADR folder in the repository and record key decisions along with their reasons and non-functional requirements.
- Keep an up-to-date map of event streams and shared data so neither humans nor agents lose track of hidden module links.
- Enforce layer boundaries with automated checks—type checker, linter, and architectural tests—instead of relying only on human eyes in review.
- Keep architecture ownership with a human developer: a model can write an isolated report, but you must hold the system's overall design in your head.



