Cursor Rules are reusable instructions that give Agent consistent project context. They are useful for commands, architecture boundaries, code conventions, and review checks that should not be rewritten in every prompt. A good rule is short, scoped, testable, and stored with the code when the whole team needs it.
Choose the right type of Cursor instruction
Cursor’s current documentation describes several instruction scopes:
| Instruction | Stored where | Best for |
|---|---|---|
| Project Rule | .cursor/rules/*.mdc | Version-controlled, scoped repository instructions |
| User Rule | Cursor’s user customization settings | Personal preferences across projects |
| Team Rule | Team administration controls | Organization-wide standards supported by the plan |
AGENTS.md | Project root or relevant subdirectory | Plain Markdown instructions without rule frontmatter |
Use a Project Rule when matching files or intelligent attachment matters. Use AGENTS.md when readable, directory-based instructions are enough. Keep personal tone preferences in User Rules rather than committing them to every repository.
Create a minimal project rule
Project Rules use .mdc files under .cursor/rules. A plain .md file in that directory is not a structured Project Rule. Create a focused rule such as .cursor/rules/typescript-checks.mdc:
---
description: TypeScript validation workflow for source changes
globs: src/**/*.ts, src/**/*.tsx
alwaysApply: false
---
- Preserve strict TypeScript settings.
- Follow existing module and naming patterns.
- Run the narrowest relevant test before the full type check.
- Do not weaken a type or skip a test to make validation pass.The description should tell Agent when the rule is useful. The glob limits it to relevant files. alwaysApply: false avoids spending context on TypeScript instructions during unrelated documentation work.
You can also ask Agent to create a rule with /create-rule, or add one through Customize → Rules. Review the generated file before committing it.
Understand rule application modes
The current UI may present application modes with user-friendly labels. Conceptually, rules can be:
- included for every relevant session;
- attached when matching files are involved;
- selected intelligently from a useful description;
- invoked manually by mentioning the rule.
Use always-applied rules sparingly. Every included instruction consumes context and can conflict with a task-specific request. File-scoped or intelligently attached rules are usually easier to maintain in a mixed repository.
Use AGENTS.md for readable repository guidance
For straightforward instructions, create AGENTS.md:
# Project instructions
## Workflow
- Read docs/DEVELOPMENT.md before editing.
- Use pnpm for package commands.
- Run pnpm validate before proposing a merge.
## Boundaries
- Keep public routes backward compatible.
- Never commit .env files or credentials.Cursor’s current Rules documentation supports AGENTS.md in the project root and nested directories. More specific nested instructions apply to work under their directory. Keep each file relevant to its scope, and do not repeat the same rule at every level.
Write rules that can be verified
Weak rule:
Write excellent, clean code and follow best practices.Stronger rule:
For src/api/**/*.ts, validate external input with the existing schema helper.
Return the repository's standard error shape from src/api/errors.ts.
Run pnpm test api before the full validation command.The stronger version identifies a scope, an existing reference, and a check. It guides behavior without inventing a new architecture.
Test whether a rule is active
- Start a fresh Agent conversation in the target repository.
- Reference a file that should match the rule.
- Ask Agent to summarize the relevant instructions before editing.
- Request a tiny change and inspect whether the expected command and pattern are used.
- Repeat with a non-matching file to confirm the rule does not leak into unrelated work.
Do not test a rule on a high-risk migration or production credential flow. A rule influences model behavior; it is not an access-control or compliance boundary.
Troubleshoot Cursor Rules
A Project Rule is ignored
Check the .mdc extension, frontmatter, description, application mode, and glob pattern. A pattern such as *.ts does not recursively match every TypeScript file; use a recursive pattern when that is the real scope.
Instructions conflict
Cursor’s current docs describe precedence as Team Rules, then Project Rules, then User Rules when applicable sources conflict. Remove duplication and place the authoritative instruction at the appropriate scope. Task prompts should not be used to silently bypass organization policy.
The Agent follows a stale command
Update the rule and the project documentation together. Point to the canonical file rather than copying a long command catalog into multiple rules.
Rules make responses worse
Split broad rules into focused files, shorten always-applied content, remove style preferences that do not affect correctness, and retest in a new conversation.
Rules and MCP solve different problems
Rules provide persistent guidance; MCP connects Agent to external tools and data. A rule can explain when a tool should be used, but it does not install or secure that tool. Continue with the Cursor MCP configuration tutorial to add tools with explicit configuration and approval boundaries.