AI 2026-09-09 8 min

The Governance Chassis: Constitution vs. AGENTS.md (And how not to drown in sync debt)

Learn how to structure AI agent governance in your repository using the Adapter Pattern to separate environmental context from on-demand context.

Written by Samir El Azem Crovetto • Senior Backend Engineer & DevSecOps

If you've tried to get your hands dirty with AI-assisted development in real projects, you've probably ended up with a spinning head seeing the amount of configuration files blooming at the root of the repository. Between .cursorrules, .cursor/rules/*.mdc, CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, and the famous constitution.md from Spec Kit, it seems like you need a master's degree just to teach the AI how we want it to write a function.

(By the way, if you are new to this: Spec Kit is an open-source toolkit sponsored by GitHub and Microsoft that serves to structure and put order in this whole agentic development flow. It is basically the Swiss army knife we use in the industry to force AIs to follow a rigorous process instead of improvising, and you have all its code and public documentation in its official GitHub repository: github/spec-kit.)

It's very common to fall into the trap of thinking: "What an alphabet soup. Isn't this duplicating work? If I already have my style rules in the Cursor file, why on earth do I need a Constitution?"

Today we are going to bring this chaos down to earth. We'll see why having all these files mixed up is the perfect recipe to drive the AI crazy, how to cleanly separate them using the Adapter Pattern to avoid violating the DRY (Don't Repeat Yourself) principle, and we'll close with a real horror story (a Spec Kit bug) that shows what happens when the governance system gets amnesia mid-development.

1. The invisible border: Environmental Context vs. On-Demand Context

The key to keeping your repository from becoming a token dump is understanding that context files don't play in the same league. They are divided into two very clear categories that should never, under any circumstances, be merged:

┌─────────────────────────────────────────────────────────────────────────┐
│                           The Context Ecosystem                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ENVIRONMENTAL Context (Operational)                                    │
│  - Files: AGENTS.md, CLAUDE.md, copilot-instructions.md                  │
│  - Mission: How the agent behaves inside the repo (linters, tests)      │
│  - Frequency: Injected into EVERY request.                              │
│                                                                         │
│                                   VS                                    │
│                                                                         │
│  ON-DEMAND Context (Architecture / Product)                             │
│  - Files: memory/constitution.md (or .specify/...)                      │
│  - Mission: What is being built (logical business rules)                │
│  - Frequency: Only loaded in critical design/validation phases          │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Environmental Context (The operations manual)

This is where files like AGENTS.md, CLAUDE.md or .github/copilot-instructions.md live. Their function is not to explain the business, but to define how the agent should behave inside the repository. They are purely operational and instrumental rules:

"Do not install NPM libraries without asking first."
"Before considering a task finished, run npm run test."
"Use the git commit command with conventional commits format."
"Ignore the files in the dist/ folder."

This context is environmental because editors and agentic terminals read it and inject it into every chat message. That's why it needs to be extremely short and direct (less than 100 or 200 lines). If you bloat it too much, you'll pay the dreaded "token tax": every silly question you ask the AI will consume a large part of its memory remembering operational rules that aren't even relevant at the time.

On-Demand Context (The laws of the product)

This is where the Constitution comes in (like Spec Kit's memory/constitution.md). Its mission is radically different: it defines what is being built and what the architectural laws of the system are. They are immutable engineering rules and logical design decisions:

"All monetary values are processed as BigInt integers in cents; using floating decimals is forbidden."
"Every backend must follow strict hexagonal architecture isolation."
"The database is migrated solely via reversible SQL files with up and down functions."

This context is on-demand because it is not sent to the LLM in every daily interaction. It only comes into play when you run design, planning, or auditing commands (like /speckit.plan or /speckit.analyze). The pipeline engine loads the constitution at those specific milestones to validate whether the proposed plan or code aligns with the system's laws. This way, you keep your daily chat memory ultra-light, but retain a steel-toothed validator for when it's time to integrate code.

2. The danger of "Context Bleed"

The most common mistake when starting with these tools is putting architecture and business rules directly into the editor file (for example, in .cursor/rules/react-patterns.mdc). This causes a pathology called Context Bleed, which crushes you on two fronts:

Vendor Lock-in: If your architecture rules only exist in the .cursor/rules/ folder, the day a teammate uses Claude Code in the terminal, or decides to work with Windsurf or VS Code with Copilot, they will be programming "blind". Your governance has been locked inside a specific editor.
Infernal sync debt: If to solve the above you decide to copy and paste the "use BigInt for money" rule into AGENTS.md, CLAUDE.md, .cursorrules, and the Constitution, you've just created a maintenance monster. The day you decide to switch to another currency strategy, you'll have to update five different files in three different formats. By the second sprint, half of your context files will be outdated and the AI will start contradicting itself.

3. The clean solution: The Adapter Pattern

To avoid this hell and keep the repository completely DRY, the solution usually applied in production is super elegant: establish a single hierarchy where one file commands and the others act as pointers.

The Constitution (memory/constitution.md) is maintained as the single source of truth for your software's architectural guidelines, versioned and audited in Git.

Editor or agent files (like .cursor/rules/ or CLAUDE.md) are configured as slim adapters. Instead of containing the heavy rules, they only contain a line that tells the agent where to go to read the truth.

For example, you can create a global Cursor rule in .cursor/rules/00-governance.mdc that is always applied (alwaysApply: true) but consumes very few tokens:

---
description: Global architectural standards and project design rules
alwaysApply: true
---

For any code design decisions, database patterns, or
architecture, you must first read the canonical governance file at:
@memory/constitution.md

Follow its guidelines mandatorily and without improvising.

And that's it! Cursor, upon seeing the reference with @, knows it has to load that Markdown file when necessary. Claude Code will read its CLAUDE.md and see a similar instruction. Your repository is now tool-agnostic, your tokens are safe from inflation, and you have a single place to change the laws of your architecture. Each layer does its job: the Constitution governs what we build and how it is structured; your agent files govern how the AI operates locally.

4. Spec Kit Bug #2459: When Amnesia Breaks the Feedback Loop

To understand why this governance thing is not a theoretical whim of bored architects, it's worth recalling a real and hilarious bug that occurred during the development of Spec Kit (Issue #2459).

The Spec Kit pipeline works, broadly speaking, in a very structured way via sequential commands:

/speckit.constitution – Defines your laws in constitution.md.
/speckit.specify – Describes the "what" in a Markdown specification.
/speckit.plan – Generates the architecture and technical models.
/speckit.tasks – Breaks everything down into a sequential checklist.
/speckit.implement – Puts on the overalls and writes the code.
/speckit.analyze – Audits the entire repository against the constitution to look for deviations.

During the tool's development, they realized an infuriating behavior: development agents were entering infinite loops of bad design. You'd run the analyzer (/speckit.analyze) and it would brilliantly report: "Warning! The code generated for the shopping cart violates Article I of the Constitution because you are coupling the logic directly into the app instead of abstracting it into an independent library".

Up to there, awesome. The validator worked great.

The mess came in the next step. You told the agent: "Okay, fix the implementation to pass validation". The agent executed the implement command (/speckit.implement), started rewriting the code... and committed exactly the same coupling blunder again! You ran the analyzer again, the constitutional error popped up again, you implemented again, and the AI violated the rule again. It was Groundhog Day.

What was the technical problem?

When gutting the Spec Kit command template in templates/commands/implement.md, the developers discovered an absurd governance gap: the implement command loaded the specs, data plans, task list, and API contracts, but omitted loading the constitution.md file.

The agent writing the code was completely blind regarding the laws of the Constitution. The analyzer had the laws in its context and audited rigorously, but the executor didn't know them, so it improvised based solely on the technical plan.

This design flaw completely broke the closed feedback loop. It was solved very simply in PR #2460 (via Spec Kit v0.8.6) by injecting a simple conditional validation into the implementation template:

- IF EXISTS: memory/constitution.md

This blunder leaves us a golden lesson: you cannot govern a system by auditing decisions with a rulebook that your executors are not allowed to read. If your AI execution harness does not share the same hard constraints as your validation pipeline, you are throwing your token money away and guaranteeing that your agents will reintroduce the same architectural flaws over and over again.

Summary for Monday morning

If you're going to structure your repository's governance today, stick with these three practical pillars:

Don't mix apples and oranges: Leave AGENTS.md or CLAUDE.md only for agent behavioral rules (linters, commits, local commands). Architecture and business logic go to the Constitution.
Apply the Adapter Pattern: Make your editor rules (Cursor's .mdc) slim pointers that point to the memory/constitution.md file. You'll save kilos of tokens and sync debt.
End-to-end Governance: Ensure that both the agent planning, the one writing, and the one validating read the same Constitution file. If any of them get amnesia, your self-correction loop will break at the weakest link.

In the next article, The SDD Pipeline in Practice: From EARS Syntax to Atomic Tasks we'll leave so much organizational theory behind and open the command console. We will do a real end-to-end walkthrough using the Spec Kit CLI to see how the EARS requirements syntax prevents the AI from assuming things it shouldn't, and how the clarification phase with /speckit.clarify forces us to make tough architecture decisions before writing a single line of code. See you in the trenches!

📚 Spec-Driven Development (SDD) Series

Extra: 🚀 CHEATSHEET: The SDD Cycle in Google Antigravity with Spec Kit