Parts 1 through 3 of this series tell the story of a CLAUDE.md that got out of control: context bloat, then structural chaos, then five outdated patterns shipping silently to production. If you read those posts thinking the problem was technical — too many files, wrong architecture, stale code samples — this post is the correction. The technical issues were symptoms. The root cause was governance. And governance matters because AI doesn't just propagate your outdated patterns — as Your Tech Debt Has a New Co-Author describes, it amplifies them at machine speed. Bad architecture in a memory file doesn't accumulate slowly. It reproduces itself in every session.
Here's how we actually got there.
The project started small: architect, one or two developers, tight communication. We built the core architecture first — API patterns, repository layer, soft deletes, audit fields. The CLAUDE.md was authoritative because one person was mostly responsible for it. When something changed, that person updated it.
Then the UI conversion ramped up. We brought in developers focused specifically on look and feel — screens, grids, forms, modals, button standards. They needed context. We had agents for UI work. We had cursor rules scoped to the Views folder. And we had a workflow that felt responsible at the time: at the end of every session, ask Claude to update the memory files with what we learned that session.
It seemed to work. Knowledge was being captured. Patterns were being written down.
But the updates were additive. No one reviewed what was already there before writing new entries. The UI agent had its own understanding of button order. The cursor rule had a slightly different version. CLAUDE.md had the original. Each looked correct in isolation. None of them matched the others.
Part 3 documented what that drift looks like in practice: five patterns generating code that compiled, passed tests, and shipped bugs. Three of those five — time inputs, ViewBag vs. ViewModel, button order — came directly from UI-focused sessions updating files the way they understood them at the time.
More developers. More sessions. More tools. All feeding the same files with no shared understanding of what was authoritative. That's the constitutional crisis problem. Here's the governance model that solved it.
The Problem With Unstructured Context
The end-of-session memory update is a good instinct. You've learned something. You want the AI to remember it. Asking Claude to update the memory files at the end of a session feels like responsible practice.
The problem is that the updates are additive and unreviewed. No one checks what's already in the file before writing. No one has the authority to declare an old entry obsolete. No one knows whether the UI agent's definition of button order conflicts with the cursor rule's version or the one in CLAUDE.md. Each update looks correct to the person writing it. The drift is invisible until three different files are giving three different answers to the same question.
The failure mode is worse than a stale wiki because the AI doesn't resolve conflicts by asking for clarification. It picks. Sometimes the most recent rule. Sometimes the most specific one. Sometimes the one that appears first in the file. You never know which rule won. The inconsistency is invisible until a bug surfaces.
The fix isn't better tooling or a stricter update workflow. It's explicit governance structure — the same structure that keeps any law-like system coherent when multiple authors are writing into it simultaneously.
The Constitutional Hierarchy
The model we use has five tiers, each with defined authority and scope:
Tier 1: CLAUDE.md (router) -- navigation only, ~20 lines
Tier 2: constitution.md (law) -- immutable principles, versioned
Tier 3: /agents (orchestrators) -- role-scoped, always loaded, thin
Tier 4: /skills (implementation) -- procedures, on-demand
Tier 5: .cursor/rules/*.mdc (hints) -- glob-scoped reminders, thin
Each tier has a defined role and a defined relationship to the tiers above it.
Tier 1: The Router
CLAUDE.md is not a governance document. It's a navigation document. It contains exactly two things: the current project context (what we're building, what stack we're on) and pointers to where the real rules live.
# BargeOps -- AI Context Router
**Stack:** ASP.NET Core Razor Pages + Web API | Dapper | SQL Server | Claude Code Opus 4.6
**Phase:** VB.NET WinForms to ASP.NET Core Razor Pages migration (195k+ lines)
## Governance
All rules are governed by constitution.md (v1.10.0).
Constitution beats agents. Agents load skills. Skills beat cursor rules. This file beats nothing.
## Key References
- Architecture & principles: constitution.md
- Agents: /api-architect, /ui-architect
- API patterns: /api-patterns skill
- UI conventions: /ui-conversion skill
- DataTables: /datatables skill
- Playwright tests: /playwright skill
- Build & run: /build skill
- File locations: /repo-docs skill
- Git workflow: /git-workflow skill
Nothing in CLAUDE.md can be used as a rule. If Claude quotes CLAUDE.md as justification for a pattern choice, that's a bug. The justification should come from the constitution or a skill. The router just tells you where to look.
Tier 2: The Constitution
constitution.md is where the principles live. It's versioned with semantic versioning (1.10.0), it carries a ratification date, and it's the single source of truth for every architectural decision.
The version number isn't decoration. It means something:
- Patch (1.10.0 to 1.10.1): clarification of an existing rule, no behavioral change
- Minor (1.10.0 to 1.11.0): new rule added, backward-compatible with existing skills
- Major (1.10.0 to 2.0.0): rule changed in a way that makes existing skill implementations non-compliant; skills must be audited
# BargeOps Engineering Constitution
**Version:** 1.10.0
**Ratified:** 2026-02-15
**Authority:** Architecture review, Doug Romano
## Hierarchy and Conflict Resolution
This constitution is the highest-authority document in the AI context system.
Skills implement constitutional principles. Cursor rules remind; they do not govern.
When any lower-tier document conflicts with this constitution, this constitution wins.
Open a task to align the lower-tier document.
## Delete Operations (§3.2)
All delete operations return `(bool success, bool softDeleted)`.
Entities with IsDeleted support soft delete on first call and hard delete on second.
Audit logging must record the delete type.
> Procedural implementation: /api-patterns skill, §Delete Patterns
Every section that has an implementation counterpart in a skill ends with that pointer. The constitution describes what, the skill describes how.
Tier 3: Agents (Role-Scoped Orchestrators)
Agents are the orchestration layer. They run parallel work sessions against different parts of the codebase, each scoped to a role: API layer, UI layer, testing, git workflow. An api-architect agent knows the API stack. A ui-architect agent knows the Razor Pages conventions. They can run simultaneously without colliding because their constitutional scope is declared and non-overlapping.
The critical distinction from skills: agents are always loaded, not on-demand. They appear as a dedicated line in /context output and burn tokens in every session whether you invoke them explicitly or not. That changes the design constraint. An agent that contains code samples and step-by-step procedures is doing the skill's job, wasting always-on budget for content that should be on-demand.
Where agents add governance value is in multi-session parallel work. The infrastructure that makes five or six parallel sessions ergonomic is covered in Claude Remote Agents: Running 10 AI Agents While You're Not at Your Desk — the tmux + Tailscale setup that keeps those sessions alive and accessible. The constitutional model here is what keeps them from generating contradictory patterns while they run independently.
The right agent is thin. It declares its constitutional scope, names the skills it delegates to, and says nothing else procedural:
# API Architect Agent
**Role:** API layer design and implementation
**Implements:** constitution.md v1.10.0
**Delegates to:** /api-patterns (always), /datatables (grid work)
## Scope
Repository layer, service layer, controller patterns, delete operations,
audit fields, and authorization enforcement.
Load /api-patterns before any API scaffolding task.
Load /datatables when the task involves data grids.
All patterns are governed by constitution.md § 3.x and § 4.x.
No procedures. No code samples. Scope, constitutional alignment, and skill routing. That's all an agent needs.
Where agents add governance value is in multi-session parallel work. When you're running five or six terminal sessions simultaneously (one for the API layer, one for UI conversion, one writing xUnit tests against what the others are producing), each agent carries the same constitution version reference. They can work in parallel because they each know exactly which constitutional sections govern their domain and where their scope ends. The constitution is the shared reference that keeps independent agents from generating contradictory patterns.
The amendment rules that apply to skills apply to agents as well. When the constitution version changes, any agent that references an old version is flagged. When an agent's declared scope overlaps with another agent's scope, that's a conflict to resolve in the amendment process, not something to leave to chance.
Tier 4: Skills (Versioned Implementations)
Skills are where the code lives. Agents load them. They're written by the developer doing the work, reviewed against the constitution, and versioned independently.
Each skill carries a constitution version reference at the top:
# API Patterns Skill
**Implements:** constitution.md v1.10.0
**Last validated:** 2026-02-15 against BargeOps.API main branch
**Loaded by:** /api-patterns
## Constitutional alignment
This skill implements § 3.1 (Repository Layer), § 3.2 (Delete Operations),
§ 3.4 (Audit Fields), § 3.5 (Authorization), § 4.1 (ListQuery Pattern).
If a pattern here conflicts with the constitution, follow the constitution
and open a task to update this skill.
The Implements: constitution.md v1.10.0 line is load-bearing. When the constitution version changes, any skill that references an old version is immediately flagged as potentially non-compliant without even opening the file.
Skills can evolve independently and frequently. Add new code samples, new patterns for new entities, new sections as the codebase grows without ever touching the constitution. The only constraint is they can't violate a constitutional principle. Everything the constitution permits is fair game.
Tier 5: Cursor Rules (Thin Hints)
Cursor rules are the lowest-authority tier. They exist for one reason: to remind Claude of the most common principles when working in a specific part of the codebase without loading a skill.
The rule for cursor rules is simple: remind, never govern. A cursor rule that contains a code sample is doing the skill's job and should be replaced by a skill pointer. A cursor rule that resolves a conflict is overstepping and belongs in the constitution.
---
globs: "**/BargeOps.UI/Views/**/*"
---
# UI Standards hint
Authority: constitution.md § 5.x. Full detail: /ui-conversion skill.
- Buttons: Search > Clear > Add [Entity]; one row, left-aligned
- ViewModels only, no ViewBag, no ViewData
- Time inputs: type="text" class="time" (custom picker, not type="time")
Three bullets. No code samples. Just enough to catch the most common mistakes without a skill load.
The Precedence Declaration Pattern
The most important part of this isn't the tier system. It's that every file knows its place and says so. That's the precedence declaration pattern, and it turns an implicit hierarchy into one that documents itself.
Every file in the system begins with a block like this:
**Authority tier:** [Router | Constitution | Agent | Skill | Hint]
**Superseded by:** [higher-tier document name]
**Supersedes:** [lower-tier document names, if any]
**Version:** [for constitution, agents, and skills]
When Claude reads any file in the system, it immediately knows the file's authority level and what to do when it conflicts with something else already in context. There's no ambiguity. The conflict resolution rule is written into the file that will be the loser.
This is the single change that eliminates the "which version of the ListQuery pattern is canonical?" problem. The answer is always whichever version is in the highest-authority document that addresses it. And every document tells you what's higher.
The Amendment Process
A constitution without an amendment process is just a suggestion. Ours is lightweight but explicit.
For patch amendments (clarification only): One developer edits the constitution, increments the patch version, adds a note to the changelog, and opens a PR. Another developer reviews to confirm no behavioral change.
For minor amendments (new rule): Developer proposes the rule in a task, documents the use case and why the current constitution doesn't cover it, and opens a PR. Architecture review confirms the rule doesn't conflict with existing ones. Skills are checked to confirm nothing needs updating.
For major amendments (changed rule): Developer documents the old behavior, the reason for the change, and the impact on existing skills. All skills that implement the changed section are updated in the same PR. All cursor rules that mention the changed pattern are updated. A grace period comment is added to the old pattern in any existing screens that need retrofitting.
The process sounds heavyweight. In practice, patches happen weekly (someone clarifying ambiguous wording), minor amendments happen monthly, and major amendments have happened twice in eight months. The friction is the point. A document that governs AI output across an entire codebase shouldn't be easy to change casually.
Applying This at Scale
The constitutional model was designed for one developer working on one codebase. It scales to teams with one rule: never edit the constitution concurrently, and any merge conflict requires both authors to resolve it together.
That sounds like a bottleneck. It isn't, because the constitution changes slowly and deliberately. Day-to-day work happens in skills, which are independent and can be edited freely. The constitution is the stable foundation, not the active working layer.
For teams larger than about four developers, it's worth adding a lightweight RFC process for minor amendments: a short document explaining the proposed rule and a 24-hour comment period before merge. The overhead is minimal and it prevents silent conflicts from two developers independently adding rules that collide.
What This Governance Model Prevents
After eight months under this structure, here are the specific failures it prevents:
Silent contradiction is impossible. Every document has a declared authority level. If two documents say different things, the lower-authority one is wrong by definition, and that's fixable.
Accretive bloat is structurally contained. Principles go in the constitution, reviewed on every edit. Procedures go in skills, large but on-demand. Nothing new gets added to the router. Growth gets routed to the right tier.
Authority ambiguity is eliminated. New developers joining the project don't need to be told "the constitution overrides the cursor rules" because it's written in every file. They don't need to be told "ask before changing the constitution" because the amendment process is in the constitution itself.
Stale patterns are detectable. Skills carry validation dates. The constitution carries a ratification date. When you see a skill that says Implements: constitution.md v1.7.0 and the current constitution is v1.10.0, you know that skill was written against an older version and may need an audit. It doesn't mean it's wrong. It means it's flagged.
The Starting Point
You don't need to implement all of this at once. The minimum viable constitutional governance is two changes from wherever you are today:
1. Add a version number and ratification date to your CLAUDE.md. Even if the document is still a monolith, versioning it immediately makes changes traceable and gives you a reference point when things drift.
2. Add a precedence declaration to every rule file you have. One line at the top of each file: "This document's authority is [level]. It is superseded by [higher document]." This alone will surface conflicts you didn't know you had.
Everything else can be added incrementally: the full tier system, the amendment process, agent scope declarations, the skill-to-constitution version references. Add them as the need becomes obvious.
The goal isn't a perfect governance system on day one. The goal is a system that stays coherent as it grows. The constitutional model is how you get there.
This is the fourth and final post in the AI Context Engineering for .NET Teams series. The series covers context auditing (Part 1), skills architecture (Part 2), pattern drift (Part 3), and governance (Part 4).
Doug is a .NET architect at CSG Solutions leading the BargeOps modernization project, converting 195k+ lines of legacy VB.NET WinForms to ASP.NET Core Razor Pages using Claude Code's agent system. He writes about AI-assisted development, context management, and enterprise modernization patterns. The full backstory on how this project came together is in Nine Months in the Trenches of Agentic Development — and the lessons about why context quality matters are rooted in Most of the Code AI Learned From Is Garbage.