Cursor Rules: Best Practices

The format, current

Modern Cursor rules live in .cursor/rules/ as .mdc files with frontmatter:

---
description: When this rule should influence edits
globs: ["src/**/*.sql"]
alwaysApply: false
---

# Parameterized queries only
[rule body with rationale and examples]

The monolithic .cursorrules file still works and is where most published collections live, but the .mdc format's scoping is the reason to migrate: rules attach per file-glob instead of taxing every request.

Scoping is the craft

Every alwaysApply: true rule is a line of context spent on every request, relevant or not, which is the same context tax a bloated CLAUDE.md pays. Glob-scoped rules cost zero until a matching file is touched.

The discipline: glob-scoped by default, always-on by exception. Universal constraints (security posture, license headers) earn alwaysApply; everything stack-specific belongs to its globs. A rule about SQL applied while editing CSS is noise at best and misdirection at worst.

Writing rules that work

Three properties separate rules that change behavior from rules that decorate a repo:

1. Rationale. Models weigh justified constraints more heavily than bare imperatives, and the humans maintaining the rules file need the why to know when the rule expired. "Parameterized queries only, because string-built SQL reached production twice in 2025" outlives "write safe SQL."
2. A negative example. Show the failure the rule prevents. Negative examples disambiguate faster than positive ones, exactly as they do in skill authoring.
3. One concern per rule. Multi-topic rules fire on the wrong globs and get half-applied. Split them.

The template carries this structure with annotations.

Mining the community collections

The original corpus and the .mdc collection are worth mining and dangerous to adopt wholesale: both are aggregators without review rubrics, and a meaningful fraction of entries encode framework advice that has since expired. The workflow that works: find your stack's entry, read it as a draft, delete what a linter already enforces, verify the remaining claims against current docs, and add your rationale lines.

Relationship to the rest of the identity layer

Cursor rules straddle the instruction-file boundary: always-on rules are identity (like CLAUDE.md content), glob-scoped rules behave like lightweight triggered skills. If multiple agent tools touch the repo, keep shared conventions in one canonical file (usually AGENTS.md) and let the Cursor rules carry only the Cursor-specific and glob-triggered parts. Divergent conventions across tools are worse than either alone, because each agent trusts what it read.