Version-controlled Agent instructions under .cursor/rules with scoped globs and apply modes
Follow Cursor's official Rules documentation when you want persistent Agent guidance tied to a repository. Project rules encode architecture expectations, risky-folder guardrails, or repeatable workflows; Cursor applies them via Always Apply, intelligent relevance, glob-scoped attachments, or manual @mentions. Use .mdc frontmatter for finer control and reference templates with @file instead of pasting large snippets.
Use cases
- Enforcing migration patterns only inside `database/` directories
- Documenting RPC conventions so Cursor Agent pulls guidance automatically during backend edits
- Blocking edits to generated output folders stated explicitly in Always Apply rules
- Providing onboarding checklists referenced via `@template.md` snippets
- Aligning frontend conventions whenever `*.tsx` files under `src/components/` enter context
Key features
- Create `.cursor/rules/` in the repo root (Cursor Settings → Rules also exposes Add Rule)
- Author `.md` rules for simple prose guidance or `.mdc` rules with YAML frontmatter (`description`, `globs`, `alwaysApply`) matching Cursor's documented matrix
- Pick an apply strategy per rule: always-on, intelligent description-driven pulls, glob attachment when matching paths are open, or manual `@rule-name` mentions
- Keep each rule focused—Cursor recommends staying roughly under 500 lines and splitting oversized guides into composable files
- Reference canonical files via `@filename.ts` per docs rather than duplicating entire style manuals inside rules
- Commit `.cursor/rules` so teammates inherit identical Agent guardrails
When to Use This Skill
- When teammates paste the same multi-paragraph Agent prompt weekly
- When certain folders demand bespoke constraints beyond generic lint rules
- When onboarding contractors who must inherit identical Cursor Agent defaults
- When you want audit-friendly instructions tracked beside application code
Expected Output
A reviewed `.cursor/rules` directory with concise `.md`/`.mdc` policies wired to Cursor apply modes documented at cursor.com/docs/context/rules.
Frequently Asked Questions
- Do Project Rules affect Cursor Tab?
- Cursor states Rules do not impact Cursor Tab or other inline completions—Rules feed Agent chat workflows.
- Can rules reference files?
- Yes—Cursor docs instruct using `@filename.ts` references inside rule bodies instead of copying entire files.
- What about AGENTS.md?
- Cursor documents AGENTS.md as a simpler Markdown alternative without structured metadata; nested AGENTS.md files can scope subtrees.
Related
Related
3 Indexed items
Creating and maintaining Cursor skills
Defines how to author, revise, and validate SKILL.md files so agent skills stay executable, scoped, and testable. It focuses on turning vague know-how into reusable operational instructions with clear triggers, deterministic steps, and verification checks.
Contract testing
Locks API expectations between services using consumer-driven contracts so that when one team changes their implementation, it fails in CI rather than during a coordinated production deployment. Contract testing prevents the common integration failure pattern where both sides of an API appear to work in isolation but break when connected in production.
Designing with LLM structured outputs
This skill covers when and how to ask an LLM for machine-readable payloads: define a JSON Schema (or the vendor's equivalent), enable the structured-output feature your provider documents, validate responses in application code, and handle refusals or validation errors explicitly. It applies to tool-calling agents, extraction pipelines, configuration emitters, and any workflow where brittle text parsing creates production risk.