Give Your Codebase a Constitution

A developer argues that codebase architecture must be codified as explicit, enforceable rules—a 'constitution'—when AI coding agents are involved, because agents lack the tribal knowledge that human engineers accumulate. The developer proposes short, restrictive, and slow-to-change laws that define invariants and boundaries, with layer membership determined by role rather than directory structure.

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. 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 names change. Directories move. Frameworks get replaced. Implementations come and go. None of that belongs in a constitution. The constitution should contain only things that should survive a major refactor: the laws, the invariants, and the boundaries that define the shape of the system. A useful test is simple. If a statement could become false next quarter and nobody would care, it probably doesn't belong in the constitution. That's documentation. Not law. The best constitutions I've seen share three properties. They're short, restrictive, and slow to change. Short because nobody reads a 50-page constitution. Restrictive because a law that forbids nothing protects nothing. Slow to change because laws only create trust when people can rely on them. I didn't design the structure upfront. Most of it came from repeatedly explaining the same architectural rules in reviews. After the tenth explanation, I stopped explaining and started writing. The first section contains a handful of principles. Very few. Five or six at most. Things like: These aren't implementation details. They're foundational assumptions. If one of them changes, you're not editing architecture. You're redefining it. The second section defines the layers and their allowed dependencies. One rule turned out to be surprisingly important: Layer membership is determined by role, not directory. Directories change all the time. Roles don't. A module that opens a network listener is still an entry point even if someone moves it tomorrow. A domain model is still a domain model regardless of which folder it lives in. Tying architecture to directories makes it fragile. Tying architecture to responsibilities makes it durable. Every law also gets a reason. This turned out to be more important than I expected. A rule without a rationale eventually gets deleted by someone who doesn't understand why it exists. The rule teaches behavior. The rationale teaches judgment. You need both. Everything above helps. None of it is enough. The biggest lesson I've learned working with agents is one I keep relearning in different forms: Instructions are guidance. Enforcement is reality. You can write "inner layers must never depend on outer layers" in the clearest prose imaginable. An agent will still violate it occasionally. Humans will too. Not because they're careless. Because instructions drift. That's when I realized every rule falls into one of two categories: Guidance belongs in documents. Enforcement belongs in code. If something absolutely must happen, don't rely on instructions. Enforce it. Put it in CI. Put it in a validator. Put it in a lint rule. Put it in a pre-merge check. Use whatever mechanism makes the violation impossible to merge. A law that can't be enforced is just a comment with good intentions. That's why every important rule in my constitution has two forms: The human version explains the intent. The machine version guarantees compliance. One creates understanding. The other creates trust. Both matter. It's easy to look at all this and see process. I see leverage. The goal isn't to slow agents down. The goal is to trust them more. Once architecture becomes enforceable, I don't need to manually inspect every decision. The validator does that for me. An agent can touch ten files across multiple layers and I don't have to wonder whether dependency boundaries stayed intact. The system already checked. That's the unlock. The constitution isn't what limits autonomy. It's what makes autonomy possible. Because once the important boundaries are guaranteed, you can safely delegate everything else. The same thing happens with onboarding. New engineers no longer need months of tribal knowledge. Agents no longer need endless prompt engineering. Everyone starts from the same set of laws, and the machine enforces them equally. Knowledge stops being gatekept by tenure. Don't start by writing fifty laws. Start by paying attention. Every time you hear yourself say: "We don't do that because..." You've probably found a candidate law. Every time an agent makes a change that makes you uncomfortable, ask yourself why. More often than not, you've discovered a boundary that exists in your head but nowhere else. Start with the handful of rules whose violation would genuinely hurt: Write the rule. Write the reason. Then add the check that makes it impossible to ignore. Because that's the part people usually skip. A law without enforcement is a suggestion. A constitution without enforcement is documentation. And architecture that exists only in people's heads doesn't survive agents.