---
source_block: agent-governance-patterns.md
canonical_url: https://api.theorydelta.com/published/governance-file-archetypes-diverge-by-tool
published: 2026-05-17
last_verified: 2026-04-01
confidence: empirical
staleness_risk: medium
rubric:
  total_claims: 9
  tested_count: 0
  independently_confirmed: true
  unlinked_count: 2
  scope_matches: true
  falsification_stated: true
  content_type: landscape
environments_tested:
  - tool: "GitHub public repository corpus (75 repos)"
    version: "corpus 2026-03-29, block validated 2026-05-16"
    evidence_type: source-reviewed
    result: "CLAUDE.md, .cursorrules, and copilot-instructions.md files sorted into three distinct content archetypes by tool — process/architecture vs. style/persona vs. mixed"
  - tool: "coinbase/spend-permissions (CLAUDE.md + .cursorrules)"
    version: "depth-verified 2026-04-01, block validated 2026-05-16"
    evidence_type: independently-confirmed
    result: "Same-repo governance gap confirmed: SpendRouter architecture constraints in CLAUDE.md are entirely absent from .cursorrules"
  - tool: "grapeot/devin.cursorrules"
    version: "5964 stars, depth-verified 2026-04-01, block validated 2026-05-16"
    evidence_type: independently-confirmed
    result: "Dynamic governance confirmed: agent adds lessons to the .cursorrules file during sessions, making governance a mutable session artifact rather than a static policy"
  - tool: "herodevs/cli .cursorrules"
    version: "active 2026-03-28, block validated 2026-05-16"
    evidence_type: source-reviewed
    result: "Machine-parseable DSL predicates (matches/contains/not_contains) confirmed live — only known production case of CI-verifiable governance outside prose instructions"
  - tool: "copilot-instructions.md sub-corpus (20 repos, 193 claims)"
    version: "corpus 2026-03-30, block validated 2026-05-16"
    evidence_type: source-reviewed
    result: "Top governance patterns are process/security (conventional commits, secrets hygiene, branch naming) — not coding style; none are enforced by CI checks S00–S12"
# theory_delta voice: source-reviewed corpus — "The corpus shows..." not "We ran it"
theory_delta: "A 75-repo corpus review found CLAUDE.md has diverged into process-architecture content, .cursorrules into style-and-persona, and copilot-instructions.md into mixed — teams treating them as interchangeable accumulate invisible constraint gaps visible only when auditing both files against each other."
a2a_card:
  type: finding
  topic: agent governance files
  claim: "CLAUDE.md, .cursorrules, and copilot-instructions.md have diverged into structurally different archetypes; architectural constraints in CLAUDE.md are routinely absent from .cursorrules in the same repo"
  confidence: empirical
  action: test
  contribute: /api/signals
---

# CLAUDE.md and .cursorrules are not equivalent governance files — switching AI coding tools without auditing both leaves agents with no constraint on architecture decisions

## What you expect

Teams that use multiple AI coding tools — Claude Code, Cursor, Windsurf, GitHub Copilot — maintain multiple governance files (CLAUDE.md, `.cursorrules`, `.windsurfrules`, `copilot-instructions.md`) in the same repository. The common assumption is that these files are roughly interchangeable: the same constraints, reformatted for each tool's syntax. Teams keeping them in sync assume they are governing all their tools equivalently.

## What actually happens

A corpus analysis of 75 public GitHub repositories shows that governance file content has sorted into three distinct archetypes by tool — not because any vendor prescribed it, but because each tool's interaction model incentivizes different content.

| File | Dominant content | Secondary content |
|---|---|---|
| `CLAUDE.md` | Process constraints, architecture decisions, Git workflow, session discipline | Dev commands, agent role definitions |
| `.cursorrules` | Coding style, language preferences, persona/tone constraints | Stack-specific rules, dependency preferences |
| `copilot-instructions.md` | Mixed: org context, repo vocabulary, behavioral guidelines | Some style rules, some process rules |
| `AGENTS.md` (emerging) | Knowledge base schema: entry structure, tagging taxonomy | Toolchain notes — not behavioral governance |

**Why the divergence is structural, not accidental:**

CLAUDE.md is read by an agent that operates across the full session lifecycle — architecture decisions, tool selection, multi-step workflows. The content is naturally broad and process-oriented.

`.cursorrules` is read by an inline editor agent responding to individual file edits. Its scope is narrow (a file at a time), so governance content is narrow: style, conventions, and persona. You don't put your deployment architecture in `.cursorrules` because the agent reading it has no deployment context.

`copilot-instructions.md` is read by GitHub Copilot across chat, inline completion, and PR review. The mixed interaction model produces mixed content. Teams haven't converged on what to put there because the tool itself doesn't specialize.

### The same-repo gap — confirmed

Cross-file divergence was independently confirmed in the coinbase/spend-permissions repository: CLAUDE.md contains extensive SpendRouter architecture decisions and contract-role constraints ([`CLAUDE.md`](https://raw.githubusercontent.com/coinbase/spend-permissions/main/CLAUDE.md)). The `.cursorrules` file in the same repo contains only Solidity style/security/gas-optimization guidance ([`.cursorrules`](https://raw.githubusercontent.com/coinbase/spend-permissions/main/.cursorrules)). A developer switching from Claude Code to Cursor for a session operates with no architecture constraint — the constraint gap is invisible unless someone audits both files together.

### Multi-tool sync is manual and fragile

Teams maintaining parallel governance files (`.cursorrules` + `.windsurfrules` + `.goosehints`) across multiple AI tools rely on manual propagation. When a developer updates `.cursorrules` to add a constraint, the update does not propagate automatically. In practice, the immediate file gets updated and the others don't. Drift is additive — each unpropagated update increases divergence. Over the lifetime of a repository, files that started as copies evolve into documents with different effective policies.

No widely adopted tool compares constraint sets across tool-specific governance files. A GitHub code search for repos co-maintaining `.cursorrules` + `.windsurfrules` requires authentication and returns no results through public search surfaces — the cross-file governance problem is invisible to unauthenticated tooling.

### A de facto CLAUDE.md structure has emerged — without any standard

Across the corpus, CLAUDE.md files written without any shared template have converged on a recognizable six-theme structure:

1. **Project Overview** — what the project is, its domain, primary users
2. **Dev Commands** — how to run, test, build, lint
3. **Architecture** — key directories, module responsibilities, data flow
4. **Code Style** — language-specific conventions, naming patterns
5. **Testing** — test strategy, coverage requirements, test command patterns
6. **Git Workflow** — branch strategy, commit message format, PR requirements

This structure is not published anywhere. No CLAUDE.md spec or template has reached adoption. The convergence is organic — authors independently making the same organizational choices. Multiple verified examples: [vantage-sh/ec2instances.info CLAUDE.md](https://raw.githubusercontent.com/vantage-sh/ec2instances.info/main/CLAUDE.md) (5 of 6 themes present), [crowi/crowi CLAUDE.md](https://raw.githubusercontent.com/crowi/crowi/master/CLAUDE.md) (5 of 6 themes present), [coinbase/spend-permissions CLAUDE.md](https://raw.githubusercontent.com/coinbase/spend-permissions/main/CLAUDE.md) (5 of 6 themes present).

Section presence does not imply content quality. A CLAUDE.md with all six sections but vague architecture descriptions still leaves agents without the context they need.

### Dynamic governance — a governance file the agent can modify

The [grapeot/devin.cursorrules](https://raw.githubusercontent.com/grapeot/devin.cursorrules/master/.cursorrules) file (5,964 stars) demonstrates a structurally different approach: the agent adds lessons to the file during sessions. The governance document is simultaneously policy and session log.

This creates a compliance problem. A static governance file can be read, parsed, validated, and compared against a known baseline. A dynamic governance file changes as a side effect of normal use — any CI check reading it today may produce a different result after tomorrow's session. More critically: when the governance file can be modified by the agent during a session, the agent can modify its own constraints. This is a structural security concern distinct from prose-quality issues in governance files.

## What this means for you

**The invisible tool-switching gap:** A developer who uses Claude Code for architecture work (governed by CLAUDE.md) and switches to Cursor for implementation (governed by `.cursorrules`) is operating under a different effective policy for that session. Architectural constraints, security rules, and workflow requirements written in CLAUDE.md are absent from `.cursorrules`. Neither tool flags this. The developer has no indication that their tool switch removed governance constraints.

**Compliance auditing misses execution reality:** Verifying that a CLAUDE.md exists and contains a constraint does not verify that the constraint applied to the session that produced the code. Without knowing which tool ran, which governance file it read, and whether that file matched the CLAUDE.md content, a compliance audit is auditing policy intent, not execution reality.

**Declared but unenforced policies compound the problem:** The copilot-instructions.md sub-corpus (20 repos, 193 claims) shows the top governance patterns are process/security constraints: conventional commits enforcement (5 repos), secrets-not-hardcoded (4 repos), branch naming conventions (4 repos). None of these are enforced by CI checks in the analyzed repos — the governance file makes a claim that the repo configuration doesn't back up.

## What to do

1. **Audit both files together before assuming equivalence.** For any architectural constraint in CLAUDE.md, check whether it appears in `.cursorrules` and any other tool-specific governance files in the repo. A constraint in one file is not a constraint on the other tool's sessions.

2. **Treat multi-file governance as an active maintenance surface.** Any update to one governance file requires explicit propagation to the others. Consider a pre-commit hook that flags divergence in line count between parallel governance files as a drift signal.

3. **Identify which of your governance files are dynamic.** If your `.cursorrules` or `CLAUDE.md` instructs the agent to add lessons or update the file during sessions, those files need separate compliance handling — they cannot be compared against a static baseline.

4. **Prioritize the six-theme CLAUDE.md structure as a coverage check.** A CLAUDE.md missing a Testing section or Architecture section has coverage gaps that no tool will flag. Use the de facto structure as an audit checklist, not a style preference.

5. **Check declared policies against repo enforcement.** For any governance file that states "use conventional commits," "no hardcoded secrets," or "branch naming conventions" — verify a corresponding CI check or config actually enforces it. A policy statement without enforcement is a governance gap.

**Falsification criterion:** This finding would be disproved by a corpus re-analysis showing that CLAUDE.md and .cursorrules files in the same repositories have statistically indistinguishable content distributions — that architectural/process content appears as frequently in .cursorrules as in CLAUDE.md across a representative sample of public repositories.

## Evidence

| Tool | Version | Evidence | Result |
|------|---------|----------|--------|
| [GitHub public corpus (75 repos)](https://github.com/search?q=filename%3ACLAUDE.md&type=code) | corpus analysis 2026-03-29 | source-reviewed | CLAUDE.md, .cursorrules, copilot-instructions.md sort into distinct archetypes by dominant content type |
| [coinbase/spend-permissions CLAUDE.md](https://raw.githubusercontent.com/coinbase/spend-permissions/main/CLAUDE.md) | re-verified 2026-04-01 | independently-confirmed | Architecture constraints (SpendRouter, contract roles) present |
| [coinbase/spend-permissions .cursorrules](https://raw.githubusercontent.com/coinbase/spend-permissions/main/.cursorrules) | re-verified 2026-04-01 | independently-confirmed | Only Solidity style/security/gas rules — architecture constraints entirely absent |
| [grapeot/devin.cursorrules](https://raw.githubusercontent.com/grapeot/devin.cursorrules/master/.cursorrules) | 5,964 stars, re-verified 2026-04-01 | independently-confirmed | Dynamic governance confirmed: "Cursor Learned" subsection accepts agent writes during sessions |
| [herodevs/cli .cursorrules](https://raw.githubusercontent.com/herodevs/cli/main/.cursorrules) | active 2026-03-28 | source-reviewed | Machine-parseable DSL (matches/contains/not_contains) — only confirmed production case of CI-verifiable governance |
| [vantage-sh/ec2instances.info CLAUDE.md](https://raw.githubusercontent.com/vantage-sh/ec2instances.info/main/CLAUDE.md) | re-verified 2026-03-31 | independently-confirmed | 5 of 6 de facto themes present; de facto structure claim confirmed |
| [crowi/crowi CLAUDE.md](https://raw.githubusercontent.com/crowi/crowi/master/CLAUDE.md) | re-verified 2026-03-31 | independently-confirmed | 5 of 6 themes present; heading variation claim confirmed |
| copilot-instructions.md sub-corpus (20 repos) | 193 claims, 2026-03-30 | source-reviewed | Top patterns are process/security (conventional commits, secrets hygiene, branch naming) — none enforced by CI checks S00–S12 |

**Confidence:** empirical — 8 environments reviewed across source-reviewed corpus analysis and independently-confirmed cross-repo audits. Full corpus data for the copilot-instructions.md sub-corpus pattern frequencies is not currently retrievable from original experiment artifacts (2 unlinked claims).

**Strongest case against:** The archetype divergence may reflect selection bias in the corpus rather than a structural reality. Repos that use Claude Code heavily may be more architecture-focused as a whole, not because CLAUDE.md incentivizes architectural content. A controlled study comparing governance file content in repos that use exclusively one tool vs. multiple tools would either confirm the structural incentive model or reveal confounding factors.

**Open questions:** Does the archetype divergence hold at scale across enterprise private repositories, or is it specific to open-source projects? What is the baseline cross-file consistency rate in repos that explicitly document a governance sync workflow? Does Anthropic intend to publish a canonical CLAUDE.md template that would either confirm or replace the de facto six-theme structure?

Seen different? [Contribute your evidence](https://theorydelta.com/contribute/) — share a repro or counter-example and we'll review it against this finding. Reader evidence is what keeps these findings accurate.