Team Cursor Rules That Scale

Use Cursor rules for durable repo instructions, not one-off prompts. A good Cursor rules file tells the agent what must always be true before it writes or reviews code. Cursor, Anysphere's AI code editor, is most useful for engineering teams when rules, skills, custom agents, and reviews work together instead of living in scattered chat history.

A Cursor rule is a scoped .mdc instruction file that gives the agent persistent guidance inside a repo or workspace. Treat cursor mdc rules as the team convention layer: small, reviewable, and close to the code they govern.

Put durable instructions in rules, not chat

Write a rule when the instruction should survive the current session. “Use the billing ledger, not the legacy invoices table” belongs in a rule. “Try a quick refactor of this helper” belongs in the prompt.

This matters because Cursor agents can work across longer tasks, including cloud and mobile handoffs. If the important context only exists in a chat, the next agent run can miss it or reinterpret it.

The trap is turning rules into a second README. A cursor rules file should tell the agent how to behave, what boundaries to respect, and what proof to return. It should not explain the entire product.

A real example: in a payments repo, keep a rule for src/billing/** that says migrations must be backward-compatible, ledger writes must be idempotent, and any change touching money movement needs a test receipt in the final response.

Split rules by repo boundary

Put project rules in .cursor/rules as small .mdc files. Start with one repo-wide rule, then add scoped rules only where the cost of a mistake is high: auth, billing, migrations, background jobs, and API contracts.

This is the pattern that makes cursor rules examples useful in real teams. A root rule can define language, test, and review norms. A nested or scoped rule can carry sharper constraints for a directory, service, or package.

The trap is one giant “team brain” rule. Big rules become vague, and vague rules get ignored. Local rules should beat broad rules because the auth package and the marketing page do not need the same agent behavior.

If your repo also uses AGENTS.md, keep the broad human-readable operating model there: architecture map, ownership, release process, and “do not touch” zones. Use Cursor rules for the instructions you expect Cursor agents to apply while editing or reviewing code.

Connect rules to skills and custom agents

Use rules to set boundaries, Cursor skills to package repeatable workflows, and Cursor custom agents or subagents to assign roles. A rule might say “database migrations require a rollback note.” A skill can provide the migration checklist. A custom agent can focus on reviewing schema changes.

This matters for teams running Cursor training or a Cursor workshop because it gives people a simple mental model. Rules are guardrails. Skills are reusable procedures. Agents are workers with a job.

The trap is putting procedure into every rule. If the instruction is long, reusable, or includes scripts and templates, make it a skill instead. Keep the rule short and tell the agent when to use the skill.

For a deeper team workflow, see the related training topic. If you are designing safer agent roles, Use Cursor Agents With Guardrails pairs well with the convention below.

Treat mobile agents as handoffs, not shortcuts

As of July 2026, Cursor’s changelog describes the iOS app as a public beta on paid plans for launching and managing always-on cloud agents. That makes rule quality more important, not less. A phone is great for starting a bounded task; it is not where you want to reconstruct repo policy from memory.

Use mobile for small, well-described jobs: “Add the missing integration test for the checkout retry path” or “Draft a PR for this failing lint rule.” Let the repo rules, skill descriptions, and agent receipt format carry the operational detail.

The trap is approving risky work because the agent sounds confident. For migrations, auth changes, permissions, or money movement, require a desktop review in Cursor before merge. Mobile should help you guide the agent, not skip the review loop.

Paste this starter rule

Copy this into .cursor/rules/team-agent-handoff.mdc, then trim it to fit your repo. It is intentionally boring. Boring rules are easier to enforce.

---
description: Team handoff rule for Cursor agents working in this repository
alwaysApply: true
---

# Team agent handoff rule

Before editing:
- Read the nearest AGENTS.md or package README if one exists.
- Identify the smallest safe change that satisfies the task.
- Do not modify generated files, lockfiles, migrations, or public API contracts unless the task explicitly asks for it.

While editing:
- Prefer existing patterns over new abstractions.
- Keep changes scoped to the files required for the task.
- If a change touches auth, billing, permissions, data deletion, or migrations, stop and call that out before proceeding.

Before finishing:
- Run the narrowest relevant test or explain why it was not run.
- Return a handoff receipt with:
  - files changed
  - tests run
  - risks or assumptions
  - follow-up work

Review rule:
- A human reviewer must check the diff in Cursor before merge.
- Do not mark the work complete if tests failed, were skipped without explanation, or the diff includes unrelated cleanup.

Adopt this like code. Any engineer can propose a rule change in a pull request. The owning team reviews it. The file lives in .cursor/rules so changes are visible, versioned, and discussed with the same seriousness as test helpers or lint config.

Keep it enforced with one review habit: every agent-generated PR must include the handoff receipt. If the receipt is missing, the reviewer asks the agent to produce it before reviewing the diff. That one small ritual turns Cursor rules from documentation into team workflow.

Best ways to use this research

• Best for: Cursor teams turning cursor mdc rules into shared review habits.
• Best first artifact: The .cursor/rules/team-agent-handoff.mdc starter rule above.
• Best comparison angle: Compare a mobile-launched agent task with a desktop-reviewed pull request, then keep the same receipt standard for both.

Common questions

• What are cursor mdc rules in Cursor?

  Cursor mdc rules are .mdc files that give Cursor persistent instructions for a workspace or repo. Use them for durable engineering conventions such as test expectations, safe-change boundaries, and handoff receipts. The key caveat is scope: keep each rule small enough that a reviewer can understand and approve it in one pass.

• Should team conventions live in Cursor rules or AGENTS.md?

  Use both when they serve different jobs. AGENTS.md is a good place for broad repo context, ownership notes, and architecture boundaries. Cursor rules are better for behavior the agent should apply while editing code, such as “run this test,” “avoid this directory,” or “return this review checklist.”

• How do Cursor skills fit with custom agents and subagents?

  Cursor skills should hold reusable procedures, while custom agents or subagents should hold role intent. For example, a “migration reviewer” agent can use a database-review skill, but the repo rule should only say when that review is required. This keeps long procedures out of rule files and makes updates easier.

• Can we trust a Cursor mobile agent run?

  You can trust the workflow only if the repo has reviewable guardrails. Mobile is useful for launching and steering bounded cloud-agent tasks, especially with clear rules and receipts. For high-risk areas like auth, billing, permissions, and migrations, require a desktop diff review in Cursor before merge.

• How many Cursor rules should a repo start with?

  Start with one repo-wide rule and one high-risk scoped rule. That is enough to test whether the convention helps without creating rule sprawl. Add another rule only when a real review miss, repeated prompt, or recurring team mistake proves the need.

Further reading

• Cursor - Agent
• Cursor - Rules
• Cursor - Skills
• Cursor - MCP
• Cursor - Enterprise
• Cursor - Changelog
• Model Context Protocol - specification

Make one rule real this week

Pick one risky workflow, add one .mdc rule for it, and require the handoff receipt on the next agent PR. If the rule saves one review comment, keep it and make the next rule just as small.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.