The understanding gap

Every software team runs on a shared understanding of what its systems are, how they connect, and why they are the way they are. That understanding has always been the scarce input: it lives in a few heads, it decays as the code moves, and every new engineer rebuilds it from scratch. Coding agents do not create this shortage. They expose it, because they raise the rate at which systems change without raising the rate at which anyone understands them.

This paper names the gap between what a system is and what its team knows it to be. It traces why documents and diagrams have never closed it, and sets out five properties an architecture map needs before it can. It shows what a map with those properties finds that a drawing cannot, what changes for a team that keeps one, and what such a map does not solve.