Use Cursor Rules in Team Repos

Keep Cursor rules narrow, scoped, and reviewed like code. Cursor’s rules documentation points teams to .cursor/rules for durable repo instructions, which is where I would put conventions the agent should follow whenever it edits a matching part of the codebase. For Cursor for engineering teams, this removes repeated prompt boilerplate without pretending that rules can replace review.

The Cursor rules .cursor/rules documentation is best read as a workflow guide, not just a settings page. In a Cursor workshop, I would rather see one reviewed rule that changes daily behavior than a long cursor rules file that nobody trusts. The decision is also connected to Subagents and skills, because not every instruction belongs in rules.

Put durable repo behavior in .cursor/rules

Use .cursor/rules for conventions that are stable enough to version with the repo. Good cursor rules tell the agent how this repository works: package manager, test entry points, architecture boundaries, naming conventions, and review expectations.

Do not turn a rule into a project brief. A rule should not say “build checkout v2” or “refactor auth this week.” Those belong in the task prompt or issue, because they expire.

If you still have a root .cursorrules file, treat it as legacy team memory and check the current Cursor rules docs before copying it forward. The old cursor rules file .cursorrules pattern often became one flat pile of instructions, while scoped .mdc rules let the team attach context to the part of the repo where it matters.

A common real workflow is a Next.js monorepo with apps/web, packages/ui, and packages/db. I would not give every edit the database migration rules. I would scope React component guidance to apps/web and packages/ui, then keep migration safety rules near the database package.

Start with one scoped convention

Save this as .cursor/rules/react-boundaries.mdc and adjust the paths to your repo. It is small on purpose.

---
description: Use when editing React components in apps/web or packages/ui.
globs:
  - "apps/web/**/*.{ts,tsx}"
  - "packages/ui/**/*.{ts,tsx}"
alwaysApply: false
---

Follow the existing component boundary.

- Use pnpm commands from the repository root.
- Keep server data loading in app routes or server components.
- Keep shared presentational components in packages/ui.
- Do not add a new state library without an approved architecture note.
- When changing behavior, update or add the nearest component test.

Adoption path: any engineer can propose the rule in a normal pull request. The owning team for that area reviews it, and the file lives under .cursor/rules so it changes with the code it governs.

Review rule: if a pull request changes a durable convention that the agent should know next time, the PR either updates the relevant .mdc rule or says why the convention should stay out of Cursor. That small check keeps cursor rules examples from becoming stale wiki text.

Choose rules, skills, subagents, or MCP deliberately

Rules are only one part of the Cursor customization surface. I use this split when deciding where a team convention should live.

For Cursor MCP, start with the smallest safe access pattern and document why the agent needs it. I wrote more about that boundary in Use Cursor MCP Safely on Teams, because external access changes the review burden.

This split fits the Review step in our methodology: delegate the edit, then check whether the agent used the right context and respected the team boundary. Rules make that review easier because the expected behavior is visible in the repo.

Keep the rule short enough to review

A rule that nobody can review will not improve agent behavior for long. Keep each file focused on one area, use plain language, and delete instructions that are no longer true.

The main limitation is context pressure. Too many always-on rules can crowd the prompt and create conflicts, especially when a repo has old conventions next to new ones. Scoped rules are easier to reason about than one global instruction block.

I also avoid putting secrets, private operational details, or unreviewed policy language into rules. If the agent needs sensitive system access, that belongs in a controlled MCP setup, not in a markdown instruction.

Check the rule in a real Cursor workflow

After merging the first rule, run a small edit that should trigger it. Open a matching file, ask Cursor Agent for a contained change, and inspect whether the output follows the boundary without needing you to repeat the rule in the prompt.

Then review the diff as normal code. Did it use the right package command? Did it keep the component in the right package? Did it add or update the nearest test when behavior changed?

If the answer is no, improve the rule before adding more rules. A compact correction beats a second file that says the same thing in different words.

Further reading

• Cursor rules
• Cursor Agent docs
• Cursor skills

Next step

Pick one repeated review comment in your repo and turn it into a scoped .mdc rule today. In hands-on training, we turn that same habit into a working team workflow across rules, skills, and review.