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
API design and versioning
Shapes REST or RPC API surfaces with consistent resource modeling, predictable error responses, paginated list endpoints, and an explicit deprecation policy before implementation locks you into contracts that are costly to change. Good API design prevents client breakage, reduces support burden, and makes feature additions less disruptive.
Codebase indexing
Builds and maintains semantic indexes of a codebase so AI coding assistants can retrieve relevant context—file relationships, symbol usage, historical decisions—without re-parsing the entire codebase on every query. Codebase indexing is essential for large codebases where context window limits prevent feeding the entire codebase to the model.
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.