Cursor project rules turn recurring, repository-specific instructions into persistent guidance for Cursor Agent. Store each focused rule as an .mdc file under .cursor/rules/, scope it appropriately, and verify it through a representative task, diff review, and the repository’s normal checks.
What Cursor project rules are and where they apply
Cursor defines rules as system-level instructions that give Agent persistent, reusable context at the prompt level. Project rules are scoped to a codebase, stored as .mdc files under .cursor/rules/, and can be checked into version control for use by a team.
The .mdc format matters: placing a plain .md file in .cursor/rules/ does not create a project rule because it lacks rule frontmatter. Cursor documents AGENTS.md as the plain-Markdown alternative.
Project, user, and team rules apply in Agent, Ask, Plan, and Debug modes. They do not apply to Tab completion or Bugbot pull-request reviews, so a rule should not be expected to influence those features.

When to use a rule instead of repeating prompt instructions
Use a project rule when the same repository-specific instruction would otherwise need to be repeated in chat. Documented examples include codebase knowledge, recurring workflows or templates, and shared style or architecture decisions. Committing the rule to Git gives teammates access to the same repository-scoped guidance.
Not every instruction belongs in a rule. Cursor advises against filling rules with copied style guides, exhaustive command documentation, rare edge cases, or information already represented by the codebase. A smaller rule is also easier to maintain than one broad file covering unrelated concerns.
Start with one instruction that recurs in real work. Cursor recommends adding or revising rules after Agent repeats a mistake instead of attempting to encode every possible convention in advance.

How to create and scope a project rule
Cursor documents two creation paths. From the command palette, select “New Cursor Rule,” name the rule, write its instructions in Markdown, choose when it applies, and save it under .cursor/rules/. Alternatively, enter /create-rule in Agent and describe the desired guidance; Agent generates an .mdc file with frontmatter in that directory.
The frontmatter fields description, globs, and alwaysApply control inclusion. Depending on its configuration, a rule can remain always active, be selected according to relevance, apply to matching file patterns, or be invoked manually. If a rule appears inactive, check whether its application type fits the task, whether a relevance-based rule has a useful description, and whether its glob matches the files being edited.
Keep each rule focused, actionable, and under 500 lines. Split larger guidance into composable files, and add concrete examples or references to canonical repository files where useful. When a rule refers to a file such as @migration-template.sql, Agent reads it with its tools when needed; the file is not automatically inlined into the prompt. Any mandatory instruction should therefore remain in the rule body rather than existing only in the referenced file.
Conclusion
A correctly formatted rule still needs practical verification. Begin with a small rule and give Agent a representative, controlled repository task that should trigger it. Review the resulting diff to see whether the edits follow the intended instruction. Cursor’s diff view allows unwanted changes to be rejected, while a checkpoint can restore files changed after an earlier message.
Next, ask Agent to run the checks already used by the repository, such as its tests, type checker, linter, or local build. Format validation by itself cannot establish that the rule changes Agent behavior correctly; the task, diff, and normal project checks provide the documented verification loop.
Choose one repository instruction you frequently repeat, encode it as a focused project rule, run a representative task, inspect the diff, and complete the project’s usual checks before committing the rule for teammates.
Disclosures and limitations
- This article was prepared with AI assistance using the cited Cursor documentation and does not claim hands-on product testing.
- No purchase recommendation or affiliate endorsement is made in this article.
Sources
- Quickstart | Cursor Docs — Cursor Documentation
- GitHub – PatrickJS/awesome-cursorrules: 📄 Configuration files that enhance Cursor AI editor experience with custom rules and behaviors — GitHub
- The Best Cursor Rules for Every Framework in 2026 (With Examples) — DEV Community
- Cursor Rule Templates, Validator & Migration Tools — cursorrules.org
- Cursor Rules Examples and Templates: A Practical Guide for 2026 — The Prompt Shelf — The-Prompt-Shelf
- Agent mode | Cursor Docs — Cursor Documentation
- Rules | Cursor Docs — Cursor Documentation
- Rules | Cursor Docs — Cursor Documentation
Improve this guide
Report a problem or suggest the next question
Submissions enter a private editorial queue. They are reviewed and deduplicated before any public update or new page is created.
