Cursor Rules: How to Configure Cursor AI for Your Codebase

Where Cursor Rules Live and Which Files Still Work

Project rules live in the .cursor/rules directory as .mdc files, version-controlled with your repository. The older .cursorrules file in your project root still works, but Cursor now calls it legacy.

The wording matters, because most guides overstate it.

• Future tense - Cursor says .cursorrules "is legacy and will be deprecated", not that it is deprecated.
• No date, no version - nothing published names a removal release.
• Migration is four steps - create a rule, copy the content, set Always Apply, delete the old file.

There are four places rule content can come from, and mixing them up causes most of the confusion around this feature.

When two sources disagree, Cursor applies Team Rules first, then Project Rules, then User Rules. All applicable rules merge, and earlier sources win the conflict.

Which Rule Type Fires and When

Cursor documents four activation types: Always Apply, Apply Intelligently, Apply to Specific Files, and Apply Manually. You do not set the type directly, because three frontmatter fields decide it for you.

Note the naming. Older guides still say Auto Attached and Agent Requested, and those strings no longer appear anywhere in Cursor's documentation.

Read that table as a checklist when a rule misbehaves. An empty description plus empty globs produces a rule nobody ever invokes.

Why a Passing Rule Is Not a Passing Test

Every troubleshooting guide on this topic teaches you to check whether a rule attached. None of them checks whether the code the rule produced actually runs.

Those are different questions. A rule is an instruction, not a gate.

This is where an external verifier belongs. Kane CLI from TestMu AI validates rendered UI in a real Chrome browser from a natural-language objective, then returns a pass or fail.

• Installs as a skill file - drop one markdown file in place and the agent loads it without restarting.
• Autoheal with confidence scores - cosmetic drift is absorbed, and an ambiguous match is rejected rather than clicked.
• Strictness is per objective - name the exact label when a regression test should fail on any change.
• Exports to Playwright - keep the generated suite in your own repository when you want to own the code.

There is no Cursor-specific skill today. You install the Codex CLI skill file, and Cursor picks it up through AGENTS.md, which keeps the author and the approver separate.

Setup and the full command reference live in the Kane CLI introduction documentation.

What Goes Inside a Rule File

A rule is frontmatter followed by markdown. Cursor documents exactly three frontmatter fields, and there is no fourth.

The example below targets every Playwright spec in a repository, so it loads only when the agent touches test code.

---
description: Playwright test conventions for this repo
globs: tests/**/*.spec.ts, e2e/**/*.spec.ts
alwaysApply: false
---

- Use getByRole and getByLabel locators. Never use CSS or XPath selectors.
- Assert on user-visible state, not on implementation details.
- One behaviour per test. Do not chain unrelated assertions.
- Reuse the fixtures in @tests/fixtures.ts instead of writing new setup.

Two details in that file are easy to miss. Separate multiple glob patterns with commas, and use @filename to pull another file into the rule's context.

The extension is not cosmetic. A plain .md file inside .cursor/rules is ignored, because it carries no frontmatter to specify the three fields.

Globs are where most rules go wrong, so it helps to see the documented patterns rather than guess at them.

Cursor documents three ways to create a rule, and the one you pick makes no difference to the result.

• From chat - run the create-rule command and let the agent scaffold the file.
• From the sidebar - open Customize, go to Rules, then click Add Rule.
• From the command palette - search for New Cursor Rule.

Cursor also publishes what to leave out, which is more useful than most best-practice lists.

• Whole style guides - the docs say use a linter instead, since the agent knows common conventions.
• Every possible command - the agent already knows tools such as npm, git, and pytest.
• Rare edge cases - instructions that seldom apply dilute the rules that always should.
• Facts already in the code - duplicating the codebase adds tokens without adding guidance.

Which Rules Make Cursor Write Tests You Can Trust

Cursor's documentation says almost nothing here. Testing appears twice, once as an example rule topic and once in an argument for writing fewer rules.

So treat what follows as practitioner convention rather than documented guidance. These four constraints do the most work on generated test code.

• Ban brittle locators - forbid CSS and XPath outright, because agents reach for them by default.
• Forbid blind waits - a rule banning fixed sleeps removes the most common source of flake.
• Require one behaviour per test - agents happily chain six assertions into a single unreadable case.
• Point at real fixtures - name the setup file, or the agent invents parallel scaffolding every time.

---
description: Ban flaky patterns in generated tests
globs: **/*.spec.ts, **/*.test.ts
alwaysApply: false
---

- Never use page.waitForTimeout or any fixed sleep. Wait on state.
- Never assert on a CSS class name. Assert on what the user sees.
- Every test must clean up the data it created.

Scope these with globs rather than alwaysApply. Test conventions loaded into every unrelated chat waste context and dilute your other rules.

A packaged alternative exists if you would rather not maintain conventions by hand. Our walkthrough of the Playwright Skill covers installing one into Cursor agent mode.

How Teams Share Rules Without Copy-Paste

Project rules travel in git, so a repository shares them for free. Two other distribution paths exist, and both are easy to miss.

Team Rules are managed from the dashboard on Team and Enterprise plans. They are free-form text rather than files, so they support globs but no folder structure.

• Enforcement toggle - an enforced team rule is required for everyone and cannot be disabled in Customize.
• Highest precedence - team rules are applied before project rules and user rules.
• Not in profile exports - user rules and team rules are both excluded when you export a profile.

The second path is a remote rule pulled from GitHub. Cursor places imported rules in .cursor/rules/imported and names the folder after the source repository.

One behaviour surprises teams that split rules across folders. Cursor identifies a rule by its full file path, not its name.

Two rules with the same filename in different folders both apply when their conditions match. There is no override and no conflict, which means a forgotten duplicate quietly doubles up.

Why Your Rule Stopped Working

Start with the surface you are working on. Rules only apply to Agent chat, and they never reach Tab completion, Inline Edit, or Bugbot pull request reviews.

That single documented sentence explains a large share of the complaints about rules being ignored. The rule was fine, and the surface simply never received it.

Work down this list when a rule misfires in Agent chat itself.

• Wrong extension - a .md file in .cursor/rules is ignored without any warning.
• Missing description - Apply Intelligently cannot work if the agent has nothing to judge.
• Glob never matches - confirm the pattern hits the files you actually have open.
• Scan cache is stale - the SDK reuses a workspace scan for 20 seconds by default.
• Silent duplicates - Cursor identifies rules by full path, so same-named files in two folders both apply.

If none of that explains it, check what the agent actually pulled. Cursor gives the Agent a Fetch Rules tool that retrieves rules by type and description, and its output tells you which rules landed.

What Cursor Has Not Documented

Most guides on this topic fill the gaps with confident guesses. It is more useful to know exactly where the documentation stops.

Each item below was checked against Cursor's published pages and is genuinely absent, not merely hard to find.

• Ask mode and Plan mode - neither page mentions rules at all, so their behaviour is unstated.
• AGENTS.md against project rules - no page gives a precedence order between them inside the editor.
• Rules per monorepo package - only a CLI changelog line implies the editor scans subdirectories.
• Any cap besides line count - no maximum rule count, character limit, or token budget is published.
• A removal date for the legacy file - no release is named anywhere.

Treat advice about any of those as someone's experiment rather than a specification. That includes advice in this article.

One documented caveat deserves repeating, because rules feel more authoritative than they are. Cursor states plainly that AI guidance should not be your only security control.

How to Write It Once and Run It in Four Agents

Rules written as .mdc files are Cursor-specific. Most teams now run more than one agent, so portability has become the real design question.

Cursor reads two portable formats alongside its own, which gives you a genuine choice about where conventions live.

Two behaviours matter before you pick. CLAUDE.md files are always applied to every conversation regardless of any alwaysApply setting, and nested AGENTS.md files let more specific instructions take precedence.

The direction of travel is worth watching. Cursor 2.4 ships a migrate-to-skills command described in the Cursor skills documentation, which converts dynamic rules into skills.

Skills are becoming the shared format across editors. We covered that shift for test work in our guide to agent skills, and compared two harnesses in Claude Code vs Antigravity.

What to Put in Your First Rule File

Resist writing a large rule on day one. Start with the conventions your team already corrects in code review.

• Create one .mdc file scoped with globs to a single directory.
• Write the four or five constraints you repeat most often in review comments.
• Leave alwaysApply false until you can prove the rule earns global load.
• Commit it, so the rest of the team gets the same agent behaviour.
• Add an external verifier before you trust anything the agent generates.

Cursor's own guidance on organisation is in the Cursor rules customization help, which recommends a flat structure over nested folders.

For a wider view of how these editors compare, our roundup of agentic coding CLI tools covers the terminal-native field.

A good rule makes the agent write the code you would have written. It still cannot tell you the code works.