Give Your Codebase a Constitution

Why Your Codebase Needs a Written Constitution in the Age of AI Coding Agents

For decades, the real rules governing a codebase lived in people's heads. Senior engineers knew which layers could talk to which, which dependencies were forbidden, and which shortcuts would create problems months down the line. New team members learned these rules by breaking them, getting caught in code review, and slowly accumulating the tribal knowledge that kept the architecture intact.

That model worked — until AI coding agents entered the picture.

As developer Mitesh Sharma argues in a recent deep-dive on the topic, the era of unwritten architectural conventions is coming to an end. "What I didn't fully appreciate until I started working heavily with coding agents is how dependent that model is on tribal knowledge," he writes. "Humans accumulate context over time. Agents don't."

The Problem with Unwritten Rules

Coding agents don't remember the migration that went sideways three years ago. They weren't present 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 in the files before them — and if a rule isn't written down, from the agent's perspective, the rule doesn't exist.

Sharma describes watching agents wire inner layers directly to outer layers, introduce dependencies the team had intentionally avoided, and extend contracts everyone considered settled. The code compiled. It passed tests. It even worked in production. The problem wasn't correctness — it was architectural drift, happening one commit at a time.

That's where the concept of a codebase "constitution" enters. Not documentation — a constitution. Something written, explicit, and enforceable.

A Constitution Is Not Documentation

The first mistake most teams make is treating a constitution like another docs file. Documentation explains how the system works today. A constitution defines what the system is allowed to become. Package names change, directories move, frameworks get replaced — none of that belongs in a constitution.

Sharma proposes a simple litmus test: "If a statement could become false next quarter and nobody would care, it probably doesn't belong in the constitution." The best constitutions share three properties: they're short, restrictive, and slow to change. Short because no one reads a fifty-page document. Restrictive because a law that forbids nothing protects nothing. Slow to change because laws only create trust when people can rely on them.

What Goes Into a Codebase Constitution

Rather than designing the structure upfront, Sharma recommends paying attention to patterns in code review. Every time you hear yourself say "We don't do that because…" you've probably found a candidate law. After explaining the same architectural rule ten times, stop explaining and start writing.

The first section should contain a handful of principles — five or six at most. Things like: dependency direction is one-way, contracts are defined before implementations, and inner layers must not know about outer layers. These aren't implementation details; they're foundational assumptions. If one of them changes, you're redefining the architecture, not editing it.

One surprisingly important rule that emerged from Sharma's experience: 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. Tying architecture to directories makes it fragile; tying it to responsibilities makes it durable.

Every law also gets a reason attached. 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," Sharma explains.

Guidance vs. Enforcement

The biggest lesson Sharma has learned working with AI agents is this: "Instructions are guidance. Enforcement is reality." You can write "inner layers must never depend on outer layers" in the clearest prose imaginable — and an agent will still occasionally violate it. Humans will too.

That's where the distinction between guidance and enforcement becomes critical. Guidance belongs in documents. Enforcement belongs in code — in CI pipelines, validators, lint rules, and pre-merge checks. A law that can't be enforced is just a comment with good intentions.

Every important rule in Sharma's constitution has two forms: a human version that explains the intent, and a machine-enforced version that guarantees compliance. One creates understanding; the other creates trust. Both matter.

Why This Matters More Than Ever

It's easy to look at all this and see process. Sharma sees leverage. "The goal isn't to slow agents down. The goal is to trust them more," he writes.

Once architecture becomes enforceable, you don't need to manually inspect every decision. The validator handles that. An agent can touch ten files across multiple layers and you 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.

When important boundaries are guaranteed, you can safely delegate everything else. 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.

How to Start

Don't begin by writing fifty laws. Start by paying attention. Every time you see an agent make 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.

Focus on the handful of rules whose violation would genuinely hurt: dependency direction, secret handling, critical contracts, and boundary ownership. Write the rule. Write the reason. Then add the automated check that makes it impossible to ignore — because that's the step most teams skip.

A law without enforcement is a suggestion. A constitution without enforcement is documentation. And architecture that exists only in people's heads simply won't survive the age of AI coding agents.