Shared agent rules — managed policy + per-repo CLAUDE.md + .claude/rules/

Question 5 (Shared infrastructure): Does the team share agent rules (CLAUDE.md / AGENTS.md / managed policy)?

Max-score answer: Multi-tier with update process — managed policy + per-repo CLAUDE.md + .claude/rules/ or Cursor Team Rules.

Why this matters in 2026

Centralized rules turn “tribal knowledge” into “the harness enforces it”. Without a managed-policy tier you cannot guarantee security or stylistic constraints — every developer is one prompt away from giving an agent a different definition of “production-ready”, and you find out in code review (if you’re lucky) or production (if you’re not).

In 2025 most orgs treated CLAUDE.md as a per-repo curiosity one or two enthusiasts maintained. By 2026 the picture has flipped. Anthropic shipped managed settings for Team and Enterprise plans — an organization-wide configuration tier that sits above every developer’s personal config and cannot be overridden. Cursor shipped Team Rules in the same shape. And AGENTS.md — the multi-tool standard now stewarded by the Agentic AI Foundation under the Linux Foundation, backed by OpenAI, Sourcegraph, Cursor, Google, and Factory — passed 60,000+ public repositories.

CTOs who treat shared agent rules as a “nice to have” are the same ones writing the post-mortem when an agent commits hardcoded credentials, force-pushes to main, or autonomously upgrades a critical dependency on a Friday afternoon. CTOs who max out Q5 have already removed those failure modes at the tooling layer — not by hoping developers read the wiki, but by making the agent physically incapable of doing the wrong thing.

The leverage is brutal. One well-crafted managed policy plus a per-repo CLAUDE.md plus a handful of .claude/rules/ files saves every developer ten minutes per session on context priming and removes an entire class of “agent did something it shouldn’t have” incidents.

What “max score” actually looks like

Three layers plus an explicit, named update process. Skip any and you’re not at the top of this question.

Tier 1 · Managed policy (org-wide, enforced, cannot be excluded)
  └── managed-settings.json on every developer's machine (or Cursor Team Rules)
        - permission allow/deny lists
        - required hooks (pre-commit, pre-push)
        - approved MCP servers
        - banned models or banned commands

Tier 2 · Per-repo CLAUDE.md / AGENTS.md (committed to main, shared with team)
  └── one file per repo, checked into source control
        - project overview, stack, commands
        - non-obvious traps and conventions
        - links to the relevant per-area rules

Tier 3 · .claude/rules/ per area (scoped by glob)
  └── auth.md, db.md, deploy.md, payments.md, testing.md
        - deep specifics that only load when relevant
        - each file has a paths: frontmatter

Update process · Quarterly audit + RFC + named owner
  └── AI tooling lead reviews rules every quarter
        - new rules land via RFC, not by accident
        - obsolete rules get pruned
        - changes are announced in the engineering all-hands

The key word in the prompt is and. Two-of-four is the “Optimized” tier; four-of-four is “Strategic Leader”. Managed policy with no per-area rules means you’ve locked in security but not engineering style. Per-repo CLAUDE.md without managed policy means you’ve shared knowledge but nothing stops a developer from disabling rules locally. Rules with no update process become stale within two sprints and start lying to your agents.

Current landscape (web-search-verified)

Managed policy (Anthropic managed settings, Cursor Team Rules)

Most orgs still don’t have this tier — and it’s the one that flips your maturity rating from “shared best practices” to “enforced policy”. Anthropic shipped managed settings as part of the Team/Enterprise rollout. The file lives at an OS-specific path on every developer’s machine:

macOS:        /Library/Application Support/ClaudeCode/managed-settings.json
Linux/WSL:    /etc/claude-code/managed-settings.json
Windows:      C:\ProgramData\ClaudeCode\managed-settings.json

It’s resolved before user settings, project settings, and CLI flags. Anything it sets cannot be overridden by a developer flag or a project file. Typical contents: permissions.deny for dangerous commands (Bash(git push --force *), Bash(rm -rf *)), required hooks for pre-commit lint and pre-push test gates, an allowlist via enabledMcpjsonServers, and a managed apiKeyHelper so developers never paste raw keys into their config. Drop-in fragments go in managed-settings.d/ alongside the base file, sorted alphabetically and merged with later files winning — so security ships 00-banned-commands.json and the platform team ships 50-required-hooks.json without stepping on each other.

Cursor’s equivalent is Team Rules: org-admin-defined rules that propagate to every workspace in the Cursor team, sitting above user rules and project rules in the same precedence chain.

Distribution is the hard part. MDM (Jamf, Intune, Workspace ONE) is the cleanest path for laptops; Ansible/Chef/Puppet works for Linux fleets; the lowest-tech option is a bootstrap script in your dotfiles repo that copies a known-good managed-settings.json into place on first run and verifies its hash on every subsequent shell.

Source: Claude Code settings docs, Claude Code Enterprise Rollout Playbook, What’s new in Claude admin controls 2026.

Per-repo CLAUDE.md / AGENTS.md (committed to main)

The middle tier is what most teams already have in some form — but the max-score version treats it as a first-class deliverable, not a side project. Every active repo has a project-level file checked into main. It answers what a new contributor (or a fresh agent) would ask in their first hour: what does this project do, what’s the stack, what are the commands, where do things live, and what are the non-obvious rules.

Two flavors:

CLAUDE.md — Claude Code’s native file, loaded automatically at session start.
AGENTS.md — the multi-tool standard (60,000+ repos in 2026, including n8n and awesome-go), read by Codex, Cursor, Copilot, Aider, and Claude Code.

If your team uses more than one agent (almost everyone does in 2026), write AGENTS.md and symlink CLAUDE.md → AGENTS.md. If you need Claude-specific behavior, put it in .claude/CLAUDE.md. The Prompt Shelf survey of 60,000+ repos shows the two-file pattern is now the dominant convention for any repo opened in more than one tool.

Keep the project file under 200 lines. Past that, frontier models start dropping instructions silently. Split deep specifics into .claude/rules/.

.claude/rules/ per area (auth.md, db.md, deploy.md)

The tier most setups skip — and the one that separates “good” from “max score”. The .claude/rules/ directory holds modular .md files, each scoped to one slice of the system, with YAML frontmatter declaring which paths trigger the rule:

.claude/rules/
├── auth.md         # paths: ["src/lib/auth/**", "src/pages/api/auth/**"]
├── db.md           # paths: ["src/lib/db/**", "drizzle/**", "scripts/schema.sql"]
├── deploy.md       # paths: [".github/workflows/**", "wrangler.toml"]
├── payments.md     # paths: ["src/lib/polar/**", "src/pages/api/webhooks/**"]
└── testing.md      # paths: ["tests/**", "**/*.test.ts"]

A rule with a paths: frontmatter only loads when the agent is actually touching files that match — so you can write 300 lines of detailed payment-flow specifics without crowding out the rest of your context window. The agent gets the auth rules when editing auth, the db rules when editing schemas, and nothing extra the rest of the time.

Cursor users get the same shape with .cursor/rules/ plus the Team Rules tier on top.

Update process (quarterly audit, RFC, AI-tooling-lead ownership)

This is the tier that doesn’t show up in any docs because it’s purely organizational — but it’s what keeps the first three tiers from rotting. The max-score setup has:

A named AI tooling lead (or small AI platform team) who owns the rules. Not a side-of-desk responsibility — a line item in someone’s role.
A quarterly audit on the calendar. Open every layer, prune what’s obsolete, promote frequent corrections into rules, demote rules nobody references.
An RFC process for new managed-policy rules. Adding a permissions.deny that breaks every developer’s workflow destroys trust in centralized governance. Run it as an engineering RFC with a one-week comment period, then ship.
A changelog or all-hands announcement when policy changes. If developers don’t know a rule changed, they’ll fight the tooling instead of using it.

The real hierarchy

This is what the precedence chain actually looks like at runtime, top wins:

1. managed-settings.json              ← org-wide, ENFORCED, cannot override
   + managed-settings.d/*.json        ← drop-in fragments (alphabetical merge)
2. Cursor Team Rules                  ← cross-tool equivalent for Cursor users
3. CLI flags                          ← per-invocation overrides
4. .claude/settings.local.json        ← personal, not checked in
5. .claude/settings.json              ← project, checked in, shared with team
6. ~/.claude/settings.json            ← user defaults (global preferences)
   + ~/.claude/CLAUDE.md              ← user memory (cross-project)
7. ./AGENTS.md (or ./CLAUDE.md)       ← project memory, shared with team
8. .claude/rules/*.md                 ← per-area memory, scoped by `paths:`

A managed policy banning git push --force to main cannot be undone by a developer setting in ~/.claude/settings.json — that’s the point. But rule files (CLAUDE.md, AGENTS.md, .claude/rules/*.md) are memory, not settings: they tell the agent what to do but don’t physically block it. You need both layers to max out Q5 — settings for hard enforcement, memory for shared style.

Step-by-step: rolling out tiered rules

Appoint an owner before writing a single rule.

Pick one engineer to own the AI-tooling rule hierarchy. Put it in their job description, allocate ~10% of their time, give them authority to ship managed-policy changes. Without a named owner the whole thing decays inside a quarter.
Audit what exists today.

Walk every active repo. Note which have CLAUDE.md or AGENTS.md, which have .claude/rules/, and what’s inside. You’ll find three patterns: well-maintained (rare), /init-generated and abandoned (most common), missing entirely.
Draft the managed policy first — start small.

Don’t enforce twenty rules on day one. Start with three: permissions.deny for the most dangerous commands, one required hook (pre-commit lint), and an MCP allowlist via enabledMcpjsonServers. Ship that, add more once developers adapt.
Pick a distribution mechanism for managed settings.

MDM is cleanest. Otherwise: a bootstrap script in your dotfiles repo that runs on first login, copies the canonical managed-settings.json into the OS-specific path, and verifies its hash on every shell start. Document it in the onboarding runbook.
Standardize on AGENTS.md for the per-repo tier.

Run /init in every active repo, rename output to AGENTS.md, symlink CLAUDE.md → AGENTS.md. Prune generic boilerplate, replace with specifics that matter (stack, commands, traps, conventions). Each file under 200 lines.
Carve out .claude/rules/ for deep specifics.

For each repo, identify two-three areas where the agent makes most mistakes — usually auth, database, deploys, payments. Create one .md per area, each with a paths: frontmatter. Move deep specifics out of AGENTS.md and into area files.
Set up the quarterly audit.

Put a recurring 90-minute “rules audit” on the calendar, owned by the AI tooling lead. Open each layer, prune obsolete rules, promote frequent corrections, look for contradictions, check the managed policy still reflects current threat models.
Document the RFC process for managed-policy changes.

New permissions.deny entries, required hooks, MCP allowlist changes — anything hitting every developer — goes through a one-week RFC. The bar isn’t “executive approval”, it’s “one week for developers to flag the workflow it breaks”.
Announce changes in the engineering all-hands.

Five minutes per all-hands on “what changed in the agent rules this sprint, why, and how to adapt”.
Verify with a fresh session in a clean repo.

Once a quarter, on a clean machine, ask the agent: “Summarize the rules you have loaded — managed policy, project memory, area rules.” If the answer doesn’t match, something’s not propagating. Common culprits: managed-settings.json not landing on new machines, paths: frontmatter missing, CLAUDE.md symlink broken.

Common pitfalls

Rules contradicting each other across tiers. Managed policy bans Bash(npm publish) but a per-repo CLAUDE.md instructs the agent to run npm publish as part of a release flow. The agent ends up confused, the rule loses authority. Audit for contradictions every quarter; resolve by deciding which tier owns the rule.

No update cadence. A CLAUDE.md written on day one and never touched again is stale within two sprints. New conventions emerge, old ones die, the file starts lying. Every PR that changes a convention also updates the rules.

Managed policy with no enforcement of the environment itself. You shipped a beautiful managed-settings.json but never verified it landed on every developer’s machine. A bootstrap-script-plus-hash-check approach catches drift; an MDM that reports compliance does too. Without enforcement of the enforcement layer, “managed” is aspirational.

Aspirational rules with no teeth. “Write clean code” tells the agent nothing testable. Every rule should be something you could review a PR against: “Use Drizzle for D1 queries; no raw SQL outside scripts/schema.sql” is testable; “use the database properly” is not.

Per-area rules with no paths: scope. A rule file without frontmatter loads on every session, defeating the point of .claude/rules/. Add a paths: to every area-specific file.

No “why” attached to non-obvious rules. A rule without a reason can’t generalize. The first time the agent hits an edge case, it’ll guess. Two sentences of rationale per non-obvious rule are worth more than ten rules without them.

Claude-only setup when half the team is on Cursor. If a Cursor user opens the repo, .claude/rules/ is invisible. Use AGENTS.md for the project tier, mirror your area rules in .cursor/rules/, and verify both tools see the same context.

Owner-by-rotation. Rotating ownership of the rule hierarchy every quarter sounds fair but kills institutional knowledge. The owner doesn’t need to be senior — they need to be consistent.

Skipping the RFC for managed-policy changes. Adding a permissions.deny that breaks every workflow with no warning is the fastest way to destroy trust in centralized governance.