Cursor Rules for Large Monorepos: Scope by Package, Not Globally

What Cursor Rules in a Monorepo Have to Solve

Cursor rules for monorepos are the per-package conventions that keep an AI agent applying the right standard in the right directory. Cursor reads scoped rules from .cursor/rules, so a backend package and a UI package can each carry their own conventions instead of sharing one global file that fits neither.

The official and community advice gets the mechanism right and the hard part wrong. Cursor's own agent best-practices post is generic. Instructa's guide to large codebases in Cursor recommends per-package rules and .cursorignore. The ai-monorepo-scaffold repo shows one worked example.

The advice lands at "put .cursor/rules per package and use .cursorignore." Correct, and incomplete. It tells you to scope rules but not how to derive the scoping from the repo's actual package graph, and it skips the move that matters most in a monorepo: an impact-analysis pass before the agent edits, so a change to a shared package doesn't quietly break six consumers.

Why One Global Rules File Fails Here

A single rules file is fine in a single-purpose repo. In a monorepo it actively misleads. The agent reading a global file gets backend conventions while editing the design system, and frontend conventions while touching the API. It then applies whichever rules it weighted, which is rarely the right set for the package in front of it.

The deeper failure is blindness to blast radius. In a monorepo, the cost of a change isn't local. Edit a shared types package and every consumer inherits the change, including the three you forgot existed. A global rules file says nothing about this. The agent edits the shared package, the build passes locally, and a downstream package breaks in CI because nothing mapped the dependency before the edit.

So two problems compound: wrong rules applied to the wrong package, and edits made without knowing what they touch. Scoping fixes the first. An impact pass fixes the second.

What Scoped Monorepo Rules Need

• A package map. Which packages exist, what each owns, and which depend on which. The rules scoping follows this graph.
• Per-package conventions. Each package's own rules in its own .cursor/rules, so the agent reads only what applies where it's editing.
• A thin root file. The genuinely shared rules, kept short, so common conventions aren't duplicated across every package.
• An impact-analysis pass. Before editing a shared package, list the consumers a change will reach.
• An ignore scope. Use .cursorignore to keep generated and vendored packages out of the agent's context entirely.

The package map is the input everything else derives from. Get the dependency graph wrong and the scoping inherits the error.

A Prompt That Maps the Graph to Scoped Rules

A prompt can read the monorepo's structure and produce both the scoping plan and the impact pass.

You scope Cursor rules across a monorepo.

Package graph: {{package_graph}}
Shared conventions: {{shared_rules}}

Do two things:
1. For each package, list the rules that belong in its
   .cursor/rules. Pull shared rules up to a thin root file.
   Output a table: Package | Scoped rules | Inherits from root.

2. Impact pass: given a planned change to {{target_package}},
   list every consumer that change reaches, depth-first, and
   flag any public-API change as "breaks consumers."

Use only the graph provided. Don't assume packages not listed.

The second half is the part the existing guides skip. Before the agent touches a shared package, it gets a list of what the change reaches. That turns a blind edit into a scoped one.

The depth-first instruction is doing specific work. The packages that break in CI are rarely the direct consumers, which a developer usually remembers. They're the transitive ones, two or three hops down the graph, that nobody holds in their head. A change to a shared validation helper breaks the API package directly, and the API package's break ripples into the two services that import it. An impact pass that walks the graph depth-first surfaces those second-order consumers. A shallow "who imports this directly" check misses exactly the packages that cost you the failed pipeline. Tell the prompt to go deep, and feed it the real dependency edges, because a guessed graph produces a confidently wrong impact list.

How the Agent Handles Scope Across a Monorepo

Scoped rules and an impact pass change agent behavior in measurable ways.

The pattern: scope the rules to the package graph, and never let the agent edit a shared package without the impact pass first. Cursor will read whatever rules you place where. It won't reason about blast radius unless a prompt makes it. That reasoning is the prompt's job, not the editor's.

Variables You'll Set

Getting Started

1. Build the package map: every package and what depends on what.
2. List the conventions that are truly shared versus package-specific.
3. Run the scoping prompt to place rules per package plus a thin root.
4. Add .cursorignore entries for generated and vendored packages.
5. Before any shared-package edit, run the impact pass.
6. Scope the edit to the consumers the impact pass surfaced.
7. For a packaged impact workflow, start with the Monorepo Impact Analysis Agent Pack.

Scoped rules in a monorepo are just per-package versions of a good rules file, so the authoring technique carries straight over. The Code Review Policy System Prompt pairs with the impact pass: the impact analysis says what a change reaches, and the review policy grades whether each touched package's change is sound.

A monorepo needs rules scoped to its package graph and an impact pass before any shared edit. One global file gives the agent the wrong conventions and no sense of blast radius. For the single-file version of this technique, see how to write a .cursorrules file that actually works. And for the cross-tool config that sits above per-package rules, how to write an AGENTS.md file with AI covers the root-plus-scoped pattern that mirrors monorepo rule scoping.