How to Write Cursor Rules: A Complete Guide to .cursorrules and .mdc Files

If you want Cursor to generate production-grade code consistently, you need explicit rules. The fastest way is to define instruction files that state architecture boundaries, coding style, and test expectations in plain language with examples.

What is the difference between .cursorrules and .mdc files?

.cursorrules is a broad, project-level rule set, while .mdc files are modular rule files often scoped to directories or concerns. Use .mdc files when you want targeted behavior by area (for example, API routes vs UI components).

What should every Cursor rule include?

Every high-quality rule should include: scope, intent, non-negotiable constraints, and concrete examples. Vague statements like "write clean code" are weak. Strong statements define exact file patterns, naming conventions, and test requirements.

Example: scoped .mdc rule for API routes

---
description: API route standards
globs: app/api/**/*.ts
alwaysApply: true
---

- Validate all input with shared sanitizers before execution.
- Return typed JSON responses with explicit status codes.
- Never perform database writes without error handling and test coverage.

How do you avoid over-constraining Cursor?

Avoid giant rule files with dozens of rigid constraints. Start with a small set of high-impact rules, then tighten based on review failures. Rules should reduce ambiguity, not block reasonable implementation choices.

How should teams organize Cursor rules at scale?

Use one lightweight top-level policy and several focused .mdc files grouped by concern:

• Architecture and boundaries
• Testing and validation
• Security and secrets handling
• Framework-specific conventions

This structure scales better than one monolithic file.

FAQ

How many Cursor rules should a team start with?

Start with 3 to 5 rules that cover architecture, testing, and security. Expand only after you identify recurring output failures.

Should Cursor rules include examples?

Yes. Examples dramatically improve model compliance because they reduce interpretation ambiguity.

For multi-tool output from one source instruction set, generate files directly with Promptkit at /generate.