Cursor MDC Rules in Real Repos

Keep Cursor rules small enough to review, or they will become another ignored team document. For Cursor users, the useful version is a checked-in .mdc rule in .cursor/rules that tells the agent how this repo wants code changed, reviewed, and kept inside its boundaries.

I treat this as a Cursor workshop habit, not a prompt trick. A good Cursor rules file carries one durable convention, uses a narrow scope, and gives the agent a concrete check it can apply before it hands work back to a developer.

Put durable team rules in .cursor/rules

Use .cursor/rules for conventions that should survive across tasks. Put task-specific instructions in the chat, not in the repo rule.

A rule should answer three questions: when it applies, what the agent must do, and what it must not change. If the rule cannot answer those questions, it probably belongs in an issue comment, a README section, or a short planning note instead.

In a Next.js repo, I would not write one broad rule called “frontend standards”. I would write a narrow rule for Server Components, route handlers, and server actions, because that is where the mistakes are easier to name and review.

Start with one copyable rule file

Here is the convention I would start with in a repo that uses the Next.js app directory and shared UI package. Save it as .cursor/rules/next-server-client-boundary.mdc.

---
description: "Apply when editing Next.js Server Components, route handlers, server actions, or shared UI imports."
globs: ["app/**/*.{ts,tsx}", "packages/ui/**/*.{ts,tsx}"]
alwaysApply: false
---

# Next.js server and client boundary

When changing files matched by this rule:

- Prefer Server Components unless the file needs browser state, browser events, or browser-only APIs.
- Add `use client` only at the smallest component boundary that needs it.
- Do not move data fetching into a Client Component just to make an edit easier.
- Keep route handlers thin. Put reusable business logic in an existing service or module near the domain code.
- When changing an exported component from `packages/ui`, check at least one importing app file before finalizing the patch.

Before handing back the change:

- Name any new client boundary you introduced.
- Say whether data fetching stayed on the server.
- Mention the files you checked for downstream imports.

This is a Cursor MDC rule in the sense most teams mean it: an .mdc project rule that sits in the repo and gives Cursor Agent a durable instruction surface. It is not a replacement for code review, tests, or architecture ownership.

Adopt the rule like production code

One developer should propose the rule in a pull request, with one real failure mode in mind. A second developer should review whether the rule is narrow enough and whether the glob catches the right files.

Keep the rule in .cursor/rules, next to the codebase it governs. If the same convention also belongs in AGENTS.md or another repo guide, keep the human-facing explanation there and let the Cursor rules file carry the operational instruction the agent should apply during edits.

The review rule is simple: when a PR changes the convention, it must include either a matching code example or a short reason the old instruction was causing bad edits. This belongs to the Review and Document side of our methodology, because the point is not to make the agent sound aligned, it is to make the repo convention visible when work is reviewed.

Choose the right Cursor surface

Do not put every team preference into Cursor rules. Cursor subagents, Cursor skills, custom agents, and Cursor MCP each carry a different kind of team knowledge, and mixing them makes the system harder to debug.

I keep this distinction close to the way I teach Subagents and skills: rules constrain edits, skills package repeatable work, subagents focus attention, and MCP connects outside context. For the agent loop around a real branch, pair the rule with the review habits in Use Cursor Agent in Real Repos.

Keep examples boring and testable

Good Cursor rules examples look almost dull. They name a file area, a coding boundary, and the check the agent should report back.

Avoid rules that say “write clean code”, “follow best practices”, or “use our architecture”. Those phrases feel safe, but they do not give Cursor anything concrete to apply, and reviewers cannot tell whether the rule worked.

A better rule says where service code lives, when a migration is allowed, what test command should run, or which API layer must not be bypassed. The narrower the rule, the easier it is to decide whether it belongs in the repo.

Further reading

• Cursor rules
• Cursor Agent docs
• Cursor skills

Start with one rule

Pick one convention that caused a real review comment last week and turn only that into a .mdc rule. If you want to practise the repo setup with a working branch, bring that example to hands-on training and we will wire it into a Cursor workflow.

Related research

• Cursor Rules vs AGENTS.md, a Team Playbook that Scales
• Use Cursor Rules in Team Repos
• Cursor Subagents, the Official Docs and the Missing Contract