Cursor rules in a monorepo: scoping each package without repeating everything

How Cursor decides which rules apply

Cursor has four kinds of rules: Team Rules managed in the dashboard on Team and Enterprise plans, project rules as .mdc files in .cursor/rules, User Rules, and AGENTS.md. A project rule's frontmatter decides when it loads. With alwaysApply set to true it is in every chat. With globs it attaches when a matching file is in context. With only a description, the agent decides. With none of these, it applies only when someone mentions it. A plain .md file in .cursor/rules is ignored.

Three details matter in a monorepo. All applicable rules are merged, with Team Rules before project rules before User Rules when guidance conflicts. Rules are identified by their full path, so two files with the same name in different folders both apply. And Cursor treats a CLAUDE.md like AGENTS.md but always applies it, so a large root CLAUDE.md written for Claude Code also costs context in every Cursor chat.

A layout that scopes by package

AGENTS.md                       # shared commands and conventions
.cursor/rules/
  repo-basics.mdc               # alwaysApply: true, a few lines
  billing/money.mdc             # globs: packages/billing/**
  web/components.mdc            # globs: packages/web/src/**/*.tsx
  migrations.mdc                # description only, agent decides
packages/
  billing/AGENTS.md             # billing build and test commands
  web/AGENTS.md                 # web build and test commands

The two scoping tools serve different purposes. Glob rules keep conventions in one place at the root and can target scattered paths, such as every migration folder. A nested AGENTS.md lives with the package it describes, and Cursor combines it with parent files, giving the more specific file precedence. Other agents read the same file too, which helps a monorepo where some teams use Claude Code or Codex.

Deciding where a rule belongs

• True in every package and short: the always-applied root rule or the root AGENTS.md. Every line here is paid for in every chat.
• True in one package: a glob rule for that package's paths, or its own AGENTS.md.
• A procedure needed now and then, such as writing a migration: a description-only rule the agent pulls in when relevant, or a manual rule.
• A standard across all repositories: a Team Rule, enforced where it must not be switched off. Cursor itself warns that AI guidance should not be your only security control.
• Anything a linter or CI can check: the tool, not a rule. Cursor's documentation advises against copying style guides into rules.

One trap: a rule that mentions a file with @ tells the agent where to look, but the file's contents are not inlined. Anything that must always be in context has to be written in the rule body.

Ownership that follows the package

Rules decay when nobody is responsible for them. Give the package team its rule files through CODEOWNERS, and give the platform team the always-applied rules, because those cost context for everyone. Claude Code's guide to large codebases describes the same split for per-directory instruction files, with each directory's owner maintaining its file.

/.cursor/rules/                  @example-org/platform
/AGENTS.md                       @example-org/platform
/.cursor/rules/billing/          @example-org/billing
/packages/billing/AGENTS.md      @example-org/billing
/.cursor/rules/web/              @example-org/web
/packages/web/AGENTS.md          @example-org/web

GitHub applies the last matching CODEOWNERS pattern, which is why the package lines come after the general rules directory. Cursor recommends keeping each rule under 500 lines and splitting large ones, and package ownership makes that split natural.

Finding overlaps before the agent does

Because every applicable rule is merged, a conflict can come from any mix of sources: Team Rules, an engineer's own User Rules, the always-applied root rule, root and nested AGENTS.md files, glob rules, rules the agent selects by description and rules someone mentions by hand. A common monorepo case is two globs matching one file. In a hypothetical repository, web/components.mdc uses **/*.tsx and so also attaches to packages/admin, whose team writes components differently. A periodic check catches this:

1. 1

   List every source that can apply

   Team Rules, root and nested AGENTS.md or CLAUDE.md files, and each .mdc file with its trigger: always, globs, description only or manual. Ask engineers whether their User Rules touch coding conventions.

2. 2

   Expand globs against the tree

   Flag files matched by rules owned by two different teams.

3. 3

   Check the always-applied rules

   Flag any line that names a single package; it belongs in that package's scope.

4. 4

   Narrow and re-test

   Here, change the glob to packages/web/** and confirm in a chat on an admin file that the web rule no longer attaches.

Rules apply only to the agent in chat, not to Tab completion, Inline Edit or Bugbot reviews, so a convention those features must follow needs another mechanism. Setting up this structure with your teams is part of our Cursor consulting.