Cursor Rules Best Practices: 7 Habits That Actually Work

· 12 min read

Most teams add a Cursor rule after every review comment, and the folder bloats until the agent ignores half of it. Cursor rules best practices come down to restraint: fewer rules, narrower scope, and a way to check that each one changes the output. My thesis is that a rule earns its place only if it prevents a mistake you can see in a diff.

Key takeaways- Rules are injected as context on every request, so each line has a cost. Keep only guidance the model gets wrong without it.- Split rules into small .mdc files in .cursor/rules, each with a description and globs, and use always-apply for a handful of hard constraints.- Write rules as statements a reviewer can check in a diff. Prefer decisions and forbidden patterns over style, which linters already enforce.- Rules are advisory, not controls. Security rules reduce mistakes up front, but CI scanning, policy checks and code review remain the gate.- Treat rules like code: rerun fixed prompts after each change, review rule edits in pull requests, and prune on a schedule.

The short answer: fewer, scoped, testable rules

Cursor's documentation says rules provide persistent, reusable context at the prompt level, included at the start of the model context. That one sentence explains most good practice. Context is a budget, and every rule line spends it on every request where the rule loads.

So the first filter is simple. Keep a rule only if the model gets something wrong without it. If the agent already writes your test files the way you want, a rule about test files is noise, and noise can crowd out the rules that matter.

Three habits follow from that.

  • Split by concern. Use small .mdc files in .cursor/rules, each with a description and globs, instead of one giant file. Cursor added project rules with descriptions and glob patterns in v0.45.2, according to a community forum announcement thread.
  • Write checkable statements. "Use the shared ApiError type for every non-2xx response" can be verified in a diff. "Write clean error handling" cannot. A rule you cannot verify is a wish.
  • Leave the legacy file behind. Morph's guide describes .mdc as the modern format that replaces .cursorrules, and it has a migration section. I would migrate anyway, because the project folder gives you scoping and version control. Check the current Cursor docs for how your version treats the old file.

One gotcha from the docs: a plain .md file in .cursor/rules is ignored because it has no frontmatter. If you prefer plain markdown, the docs point to AGENTS.md instead.

1. Write one rule per concern, with a narrow scope

One .mdc file per topic works best: testing, API errors, database migrations, Terraform modules. Each file carries frontmatter for description, globs and alwaysApply, which are the properties the Cursor docs list.

Here is a minimal example for a migrations rule.

---
description: Conventions for SQL migrations in the orders service
globs: db/migrations/**/*.sql
alwaysApply: false
---

- Every migration is reversible; include the down script in the same PR.
- Never rename a column in place. Add the new column, backfill, then drop in a later release.
- Reference @db/migrations/0042_add_listing_status.sql as the canonical example.

This matters most in monorepos and mixed stacks. A frontend rule about React hooks should never load while the agent edits Terraform. Scoped rules load only when relevant, which keeps context small and makes contradictory instructions less likely.

The same logic applies to where rules live. Aipress.io's guide points out that user rules are global to your account, and a rule from one client project can surface in another workspace. Keep repo-specific guidance in the repo, and keep user rules to preferences that are true everywhere.

Where it breaks

Glob scoping depends on file patterns. Cross-cutting work, such as renaming a concept across the API, the database and the docs, touches many areas. You can miss rules that should have loaded, or load several you did not need.

A project layout that follows clear boundaries helps here. Rules map cleanly to folders when the folders map cleanly to concerns, which is the argument in my piece on structuring a codebase for scale. If you cannot write a sensible glob for a rule, the rule may be about more than one thing.

2. Pick the right rule type: always, auto-attached, agent-requested, manual

Four different gates filtering streams of document cards, illustrating the four ways a rule can be activated
Four different gates filtering streams of document cards, illustrating the four ways a rule can be activated

Cursor offers four activation modes. The docs and Morph's guide name them Always Apply, Apply Intelligently, Apply to Specific Files and Apply Manually. Choose by two questions: how often is the guidance needed, and how costly is forgetting it?

Type

Loads when

Best for

Where it misleads

Always Apply

Every chat session

A few hard constraints, such as security boundaries

Every extra line is paid on every request, so the folder quietly gets expensive

Apply to Specific Files

Files matching the globs are in play

Language, framework or folder conventions

Misses cross-cutting work; a wrong glob means the rule never loads

Apply Intelligently

The agent decides from the description

Occasional playbooks, such as release steps

A vague description means the rule silently never fires

Apply Manually

You invoke it by name

Rare, heavy procedures

Easy to forget it exists; nothing reminds you

This is for anyone whose rules folder has grown past a handful of files and started to feel noisy. Reserve always-apply for a very small set of constraints you would be upset to see violated. Everything else should load on demand.

Where it breaks

Agent-requested rules rely on the model reading your description and judging relevance. "Helpful database tips" tells it nothing. "Use when writing or reviewing SQL migrations for the orders service" gives it a trigger. If a rule never seems to fire, rewrite the description before you blame the model.

Example, with invented numbers for illustration: a repo has 12 rule files. Eight are always-apply and total 900 lines. Moving six of them to file-scoped or intelligent types might leave 150 lines loading on every request. The guidance did not shrink. It just stopped competing for attention when it was irrelevant.

Practical rule: Scope every rule as narrowly as its purpose allows, and make always-apply the exception you justify.

3. Encode what the linter cannot: decisions, not style

If Prettier, ESLint or ruff already enforces formatting, a style rule only wastes tokens. The linter fails the build when the agent drifts. The rule can only ask nicely.

Spend rule lines on decisions that no tool checks. Good candidates are architecture choices, forbidden patterns and the reason behind them. Two examples: "Use the Keycloak admin client wrapper in libs/identity, never raw HTTP calls to the admin API," or "Schema changes ship as expand-then-contract migrations, because releases must stay zero-downtime." The reason is half the value. A model that knows why can apply the rule to a case you did not anticipate.

The AI Signal's short guide suggests three to five constraints in a conventions file is enough to start. That is a one-site recommendation, not a measured threshold. I read it as a useful starting size, and as a signal that lean beats exhaustive.

The strength is on the review side. The agent stops re-litigating decisions you already made. Reviewers stop leaving the same comment on every pull request.

Where it breaks

Decision rules go stale when architecture changes. A rule saying "use service X for notifications" does real harm after you migrate to service Y. Give each decision rule an owner and a date in the file, or it rots quietly. Stale rules are worse than missing ones, because the agent follows them confidently.

4. Show a good and a bad example, and point to real files

Adjectives like clean, idiomatic and robust leave the model guessing. A short before-and-after snippet removes the ambiguity faster. So does an @file reference to a canonical implementation in your repo.

This is most useful for conventions that are hard to describe: error response shape, test naming, service layering. Compare these two lines.

  • Vague: "Handle errors properly."
  • Concrete: "Return { code, message } using ApiError. See @src/api/errors.ts. Do not throw bare strings."

I used this approach when rebuilding an open source package with Cursor and Claude. The lesson that carried over is general: the agent follows a concrete reference file far more reliably than a paragraph of intent.

Where it breaks

Long inlined code bloats context and drifts from the codebase. Link to a living file, and keep any inline snippet under ten lines. A linked file updates when the code does. A pasted copy does not.

There is also a trust issue. Anything you pull into context becomes input to the model. Palo Alto Networks' Unit 42 reported that context attachment features in the code assistants it examined can be vulnerable to indirect prompt injection, where contaminated third-party data hijacks the assistant. Their work covered IDE plugin assistants generally, not Cursor specifically. It shows a risk class, not a measured rate. The practical consequence is simple: point rules at files you own, not at vendored or pasted external content.

Practical rule: Replace every adjective in a rule with an example or a file reference, and keep inline snippets short.

5. Put security and safety constraints in rules, then enforce them elsewhere

Security bans are the best candidates for always-apply rules. Typical ones: no secrets in code, no disabling TLS verification, no unpinned base images, no wildcard IAM or RBAC permissions, no admin-role grants in Keycloak realm exports.

This suits platform and security-minded teams. In my own setup, identity is managed as code with Keycloak and Terraform, and every container image is scanned with Trivy in CI. Those controls exist whether or not an agent is involved. The rule's job is different: it makes the agent avoid the mistake up front, which is cheaper than catching it at review or in a failed scan.

---
description: Hard security constraints for all code and infrastructure changes
alwaysApply: true
---

- Never write secrets, tokens or passwords into code, manifests or examples.
- Never disable TLS verification, even for local testing.
- Pin base images to a version or digest; never use `latest`.
- No wildcard actions or resources in IAM policies or Kubernetes RBAC roles.

Where it breaks

Rules are advisory, not controls. The AI Signal's guide says plainly that the assistant interprets rules loosely, not deterministically. A rule that works nine times can fail on the tenth. Keep Trivy scans, policy checks and code review as the real gate.

Rules files are also an attack surface. Pillar Security reported in March 2025 a technique it calls "Rules File Backdoor," using hidden unicode characters in configuration files for Cursor and GitHub Copilot to steer generated code. That is a researcher's demonstration, not evidence of how often it happens in the wild. It does prove that a rules file can contain instructions a human reviewer does not see. Coverage of the research describes the mechanism as distributing malicious rule configuration files.

My conclusions are practical. Review rule changes in pull requests like code. Be wary of copying rules files from strangers. Consider a CI check that flags non-ASCII or invisible characters in .cursor/rules. That check is my suggestion, not something the sources prescribe.

6. Test rules like code: run prompts, read diffs, prune

Most rules are written once from intuition and never checked. Treat them like code instead. Keep a small set of fixed prompts, rerun them after each rule change, and compare the output before and after.

Example, with illustrative numbers: five prompts that cover your main conventions, such as "add a delete endpoint," "add a migration for a new column" and "write a test for this service." Run each three times with the rule on and three times with it off. That is 30 runs for one rule. Read the diffs. If the output is the same either way, the rule is not doing work.

The strength is pruning. You learn which rules change behavior and delete the rest, which usually shrinks the folder noticeably. A smaller folder also leaves less room for conflicting instructions.

Where it breaks

Model output is non-deterministic. One run proves little, so repeat each prompt a few times and judge the pattern. A forum user shared a case where an agent summarized a detailed plan despite their expectations, and they then had the agent patch its own rule to close the loophole. It is one user's report, not a benchmark. It shows the iteration loop in practice: observe a miss, tighten the rule, observe again. Their patched rule is also very emphatic, with "CRITICAL" and "MANDATORY" headers. I would try plain, specific wording first, because shouting adds length without adding precision.

Rollback is easy because project rules are version-controlled. If a change makes output worse, revert the commit.

The agent still writes code you must read. My approach to that is in how I review AI-generated code. Rules reduce the volume of review comments. They do not remove the need for review.

Practical rule: Never keep a rule you cannot show changing a diff.

Run this routine every month to keep rules healthy

The seventh habit is a calendar entry. Rules decay as the code, the tools and the models change, so maintenance has to be scheduled. Budget an hour.

  1. List every rule file and note its type, scope and owner. Delete any rule without an owner.
  2. For each rule, ask what mistake it prevents. Remove those the model already gets right unprompted.
  3. Check that always-apply rules total under roughly 500 lines combined. That is my own budget, not a Cursor limit; Morph's guide suggests keeping each rule file under 500 lines. Move the rest to scoped or requested types.
  4. Rerun your fixed test prompts and compare diffs before and after any change.
  5. Turn every repeated review comment from the last month into a rule, or confirm a linter should catch it instead.
  6. Confirm security rules still match CI and policy checks, and commit rule changes through normal pull requests.
Cursor Rules Best Practices: 7 Habits That Actually Work - Ali Hesari