Give Your Codebase a Constitution

Architecture that lives only in people's heads doesn't survive agents. For most of my career, the real rules of a codebase weren't written down. People knew them. Senior engineers knew which layers could talk to which. They knew which dependencies were forbidden, which schemas were effectively frozen, and which shortcuts would create problems six months later. New engineers learned those rules the traditional way: break one, get caught in review, get the explanation, and eventually remember not to do it again. It wasn't perfect, but it mostly worked. What I didn't fully appreciate until I started working heavily with coding agents is how dependent that model is on tribal knowledge. Humans accumulate context over time. Agents don't. They don't remember the migration that went sideways three years ago. They weren't around when the team spent weeks untangling a dependency cycle. They don't know why a particular boundary exists. They only know what they can see. Which means if a rule isn't written down, from the agent's perspective, the rule doesn't exist. I've seen agents wire inner layers directly to outer layers. I've seen them introduce dependencies we intentionally avoided and extend contracts everyone on the team considered settled. The code often worked, which was the dangerous part. The problem wasn't correctness. The problem was architectural drift. That's when something clicked for me. Architecture can't remain folklore once agents start writing code. It has to become law. Not a convention. Not a suggestion. Not something a reviewer remembers at 6 PM on a Friday. A law. Written down, explicit, and enforceable. That's what I mean by a constitution. A Constitution Is Not Documentation The first mistake I made was treating the constitution like another documentation file. It isn't. Documentation explains how the system works today. A constitution defines what the system is allowed to become. Those sound similar, but they serve very different purposes. Package nam