{"slug": "give-your-codebase-a-constitution", "title": "Give Your Codebase a Constitution", "summary": "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.", "body_md": "For most of my career, the real rules of a codebase weren't written down.\n\nPeople knew them.\n\nSenior 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.\n\nIt wasn't perfect, but it mostly worked.\n\nWhat 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.\n\nThey 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.\n\nThey only know what they can see.\n\nWhich means if a rule isn't written down, from the agent's perspective, the rule doesn't exist.\n\nI'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.\n\nThe problem wasn't correctness.\n\nThe problem was architectural drift.\n\nThat's when something clicked for me.\n\nArchitecture can't remain folklore once agents start writing code.\n\nIt has to become law.\n\nNot a convention. Not a suggestion. Not something a reviewer remembers at 6 PM on a Friday.\n\nA law.\n\nWritten down, explicit, and enforceable.\n\nThat's what I mean by a constitution.\n\nThe first mistake I made was treating the constitution like another documentation file.\n\nIt isn't.\n\nDocumentation 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.\n\nPackage names change. Directories move. Frameworks get replaced. Implementations come and go.\n\nNone of that belongs in a constitution.\n\nThe 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.\n\nA useful test is simple. If a statement could become false next quarter and nobody would care, it probably doesn't belong in the constitution.\n\nThat's documentation.\n\nNot law.\n\nThe best constitutions I've seen share three properties. They're short, restrictive, and slow to change.\n\nShort because nobody reads a 50-page constitution.\n\nRestrictive because a law that forbids nothing protects nothing.\n\nSlow to change because laws only create trust when people can rely on them.\n\nI didn't design the structure upfront.\n\nMost of it came from repeatedly explaining the same architectural rules in reviews. After the tenth explanation, I stopped explaining and started writing.\n\nThe first section contains a handful of principles. Very few. Five or six at most.\n\nThings like:\n\nThese aren't implementation details.\n\nThey're foundational assumptions.\n\nIf one of them changes, you're not editing architecture. You're redefining it.\n\nThe second section defines the layers and their allowed dependencies. One rule turned out to be surprisingly important:\n\n**Layer membership is determined by role, not directory.**\n\nDirectories change all the time. Roles don't.\n\nA 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.\n\nTying architecture to directories makes it fragile.\n\nTying architecture to responsibilities makes it durable.\n\nEvery law also gets a reason.\n\nThis 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.\n\nYou need both.\n\nEverything above helps.\n\nNone of it is enough.\n\nThe biggest lesson I've learned working with agents is one I keep relearning in different forms:\n\nInstructions are guidance. Enforcement is reality.\n\nYou can write \"inner layers must never depend on outer layers\" in the clearest prose imaginable.\n\nAn agent will still violate it occasionally.\n\nHumans will too.\n\nNot because they're careless. Because instructions drift.\n\nThat's when I realized every rule falls into one of two categories:\n\nGuidance belongs in documents.\n\nEnforcement belongs in code.\n\nIf something absolutely must happen, don't rely on instructions. Enforce it.\n\nPut 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.\n\nA law that can't be enforced is just a comment with good intentions.\n\nThat's why every important rule in my constitution has two forms:\n\nThe human version explains the intent.\n\nThe machine version guarantees compliance.\n\nOne creates understanding.\n\nThe other creates trust.\n\nBoth matter.\n\nIt's easy to look at all this and see process.\n\nI see leverage.\n\nThe goal isn't to slow agents down. The goal is to trust them more.\n\nOnce 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.\n\nThe system already checked.\n\nThat's the unlock.\n\nThe constitution isn't what limits autonomy.\n\nIt's what makes autonomy possible.\n\nBecause once the important boundaries are guaranteed, you can safely delegate everything else.\n\nThe same thing happens with onboarding.\n\nNew 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.\n\nKnowledge stops being gatekept by tenure.\n\nDon't start by writing fifty laws.\n\nStart by paying attention.\n\nEvery time you hear yourself say:\n\n\"We don't do that because...\"\n\nYou've probably found a candidate law.\n\nEvery 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.\n\nStart with the handful of rules whose violation would genuinely hurt:\n\nWrite the rule.\n\nWrite the reason.\n\nThen add the check that makes it impossible to ignore.\n\nBecause that's the part people usually skip.\n\nA law without enforcement is a suggestion.\n\nA constitution without enforcement is documentation.\n\nAnd architecture that exists only in people's heads doesn't survive agents.", "url": "https://wpnews.pro/news/give-your-codebase-a-constitution", "canonical_source": "https://dev.to/miteshethos/give-your-codebase-a-constitution-3k4h", "published_at": "2026-06-20 09:14:24+00:00", "updated_at": "2026-06-20 09:36:48.327413+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "ai-agents"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/give-your-codebase-a-constitution", "markdown": "https://wpnews.pro/news/give-your-codebase-a-constitution.md", "text": "https://wpnews.pro/news/give-your-codebase-a-constitution.txt", "jsonld": "https://wpnews.pro/news/give-your-codebase-a-constitution.jsonld"}}