Skip to content
eWiki The practical AI reference

AI Tool Questions

Cursor Project Rules: When to Use Them and How to Create and Test One

Translucent blue square block resting on stacked diagram papers, with a black pen and lined notebook on a pale desk.

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.

Stack of white grid paper held by a blue binder clip beside a blue pen, black ruler, canvas notebook, and cutting mat.

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.

Person in a gray sweater pointing at hand-drawn box diagrams in an open notebook, with a pen, mug, and diagram sheet nearby.

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

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.