Cursor Rules for Teams: How to Share AI Rules Across Your Entire Codebase
Solo developer with Cursor Rules: one .cursorrules file, one opinion, one style. The AI behaves the same way every session because one person is curating it.
Team of ten with Cursor Rules: one engineer pins React 18, another asks Cursor for a feature and gets React 19 Suspense patterns, and the PR ships. Backend A has a rule saying "use pytest," backend B kept a rule saying "use unittest because we always have," and tests in the same repo import from both. The frontend folder asks for Tailwind, the marketing site is still on CSS Modules, and Cursor writes whichever one the last AI-rule editor preferred. The onboarding doc says "install Cursor," and three weeks in, the new hire is still generating code that fails review because nobody told them the rules live in someone's ~/.cursor/.
Cursor Rules were designed for solo work. Using them across a team means treating them like code: versioned, reviewed, scoped, inherited, and enforced. Seven rules below, each with the failure mode and the fix.
How Team Cursor Rules Differ From Solo Rules
Cursor reads rules from three locations, in priority order: global user rules (~/.cursor/rules/), project rules (.cursor/rules/*.mdc at the repo root), and legacy .cursorrules. For teams, only project rules committed to the repo matter — global rules are per-developer and drift silently. Monorepos additionally use nested .cursor/rules/ under each package, and nested wins over root.
repo-root/
.cursor/rules/ # applies repo-wide
base.mdc
packages/web/.cursor/rules/react.mdc # web-only
packages/api/.cursor/rules/fastapi.mdc # api-only
Rule 1: Central Storage — Rules Live in the Repo, Not in Anyone's Home Directory
An engineer writes an excellent rule, saves it to ~/.cursor/rules/, and nobody else sees it. Six weeks later, three engineers have their own slightly-different personal version of the same rule. Style diverges by author.
All team Cursor rules live in `.cursor/rules/*.mdc` inside the repo.
Global `~/.cursor/rules/` is for personal preferences only
(verbosity, keyboard shortcuts) and MUST NOT contain code-style or
architecture rules. If a rule affects code written for this project,
it belongs in the repo, on a branch, in a PR, with a reviewer.
Rule 2: Monorepo Inheritance — Nested Overrides, Never Duplicates
The naive approach is to put everything in root .cursor/rules/ and let Cursor sort it out. It breaks the moment rules conflict: root says "Jest," the API package uses pytest, Cursor picks one based on load order.
Root `.cursor/rules/` contains ONLY rules that apply to every package:
commit conventions, security baselines, documentation format.
Package-specific rules (testing framework, build tool, UI framework)
live under `packages/<name>/.cursor/rules/` and override root rules
for files in that package. Never restate a root rule in a package
rule — duplication is drift.
Audit what's globally enforced with git grep -l "alwaysApply: true" from the repo root.
Rule 3: Scope Boundaries — Every Rule Declares Where It Applies
A rule written for the API layer leaks into the frontend. Example: "All async functions return Result<T, E>" — correct for the Rust service, incorrect in TypeScript React. The AI applies it everywhere because the rule had no scope.
Every `.mdc` rule MUST declare scope via frontmatter:
globs: ["packages/api/**/*.py"]
alwaysApply: false
A rule without `globs` is global. If global is intentional, state
it explicitly in the body. Rules applied globally by accident are
the #1 source of "why is Cursor suggesting this nonsense here?"
complaints.
Rule 4: Versioning — Rules Reference Exact Library Versions
"Use React hooks" ages well. "Use the latest Next.js" produces a different codebase every month. AI assistants "helpfully" upgrade the rule by inferring the newest version from training data.
GOOD: "Use React 18.3 hooks. Do not use React 19 features
(use, Actions, useOptimistic) — this project is on 18."
BAD: "Use modern React hooks."
When the project upgrades a dependency, the rule file is updated
in the SAME PR as the package.json change:
`chore: bump react to 19 + update cursor rules`.
Cursor's suggestions are only as stable as the rules they follow. An unversioned rule invites AI-driven drift between package.json and the code.
Rule 5: Onboarding — First PR Is to a Cursor Rule
Week-one "read the CONTRIBUTING.md" fails because nobody retains 4,000 words of style guide on day two.
The onboarding task for every new engineer:
1. git clone, open in Cursor.
2. Ask Cursor a typical project question ("add a CRUD endpoint
for invoices"). Observe which rules fire in the chat UI.
3. Find one thing in the generated code that does NOT match the
team's actual convention.
4. Open a PR that either fixes the rule OR adds a new rule
covering the gap.
The new hire learns the rule file is the source of truth, sees how rules are scoped, and the team gets a fresh audit of the rules every hire.
Rule 6: Drift Detection — Rules and Code Reviewed Together
Six months ago the rule said "use axios." Last quarter someone migrated to fetch in new code without updating the rule. Now Cursor writes axios for new files, the reviewer rejects it, the author rewrites, and five minutes of everyone's time is burned every PR.
Every PR that changes a pattern the rules describe MUST update
the rule in the SAME PR. The PR template includes:
- [ ] Does this PR introduce or change a pattern?
- [ ] If yes, which `.cursor/rules/*.mdc` file documents it?
- [ ] Has that file been updated?
Automate where possible: a CI job that greps for banned patterns (axios, moment, console.log) fails the build if rules and code have diverged.
Rule 7: Enforcement — Rules Are Tested Like Linters
Rules that aren't enforced are suggestions. Nothing stops an engineer from disabling the AI and writing prohibited code by hand.
Every `.cursor/rules/*.mdc` about code style or structure has a
corresponding linter/CI check:
Rule Enforced by
"Use pytest, not unittest" ruff + `import unittest` banned
"No console.log in prod" eslint rule
"Type hints on all funcs" mypy --strict
"No axios, use fetch" depcheck / CI grep
"Conventional commits" commitlint pre-commit hook
Unenforceable rules (architecture, naming for new code) are the
only ones that live in Cursor alone. Everything else is belt-and-
braces: Cursor nudges, CI verifies.
The Team Setup — Copy-Paste
.cursor/rules/base.mdc at the repo root:
---
description: Repo-wide rules applied to every file.
alwaysApply: true
---
## Style
- TypeScript strict mode; no `any` in new code.
- Commit messages follow Conventional Commits.
- No console.log in production code; use the project logger.
## Dependencies
- Never add a new package without updating the relevant
`.cursor/rules/*.mdc` in the same PR.
- Do not upgrade majors without a chore: PR updating BOTH
package.json AND the rule files.
## Security
- Never embed secrets; use env vars with a documented schema.
- Do not log request bodies, tokens, or PII at any level.
## Scope
- Package-specific guidance lives under
`packages/<name>/.cursor/rules/` and overrides this file.
That's the shape. Rules live in the repo, scoped by folder, versioned with the code, reviewed in PRs, enforced in CI, learned through onboarding PRs. Cursor becomes consistent across the team, and the rules stop drifting away from the code the moment nobody's watching.
Want the full pack?
We maintain a Cursor Rules pack with production-ready rules for Python, TypeScript, React, Next.js, Go, Rust, Docker, Kubernetes, Terraform, and more — all written to the patterns above (scoped frontmatter, versioned dependencies, CI-enforceable). Teams that need consistent AI-assisted code across a shared codebase use it as a starting point.
Top comments (0)