Cursor Rules Guide: .cursor/rules Examples and Best Practices

Use rules for facts and constraints that should survive beyond one chat: verified commands, architecture boundaries, file-specific conventions, testing requirements, and restricted changes.

The older .cursorrules file is still supported, but Cursor marks it as legacy and recommends Project Rules.

Cursor Rules at a glance

Cursor rule types

Do not make every rule Always. Always-on content consumes context on unrelated requests and can make conflicts harder to diagnose.

Create a Cursor project rule

In Cursor, open the Command Palette and run New Cursor Rule, or open Cursor Settings → Rules. Cursor creates a file inside .cursor/rules/.

A minimal rule looks like this:

---
description: Testing conventions for TypeScript services
globs: "services/**/*.ts,services/**/*.test.ts"
alwaysApply: false
---

# TypeScript service tests

- Use Vitest and existing test factories.
- Test behavior through exported functions.
- Mock external APIs at the HTTP boundary.
- Run `pnpm vitest run <changed-test>` before completion.

Commit the rule when it should be shared with the team.

Complete Cursor Rules example

Use several small rules instead of one long document:

.cursor/
└── rules/
    ├── project-basics.mdc
    ├── react-components.mdc
    ├── api-services.mdc
    └── database-migrations.mdc

Always-on project basics

Create .cursor/rules/project-basics.mdc:

---
description: Repository structure, commands, and completion requirements
globs:
alwaysApply: true
---

# Project basics

- Use `pnpm`; do not create npm or Yarn lockfiles.
- Run `pnpm lint` and the narrowest relevant test for changed code.
- Do not edit `generated/` or commit `.env` files.
- Ask before adding a runtime dependency.
- Report checks run and checks not run.

## Repository map

- `apps/web/`: React frontend
- `services/api/`: Node.js API
- `packages/ui/`: shared UI components
- `packages/contracts/`: API schemas

Keep an Always rule short. Move detailed frontend or backend requirements to scoped rules.

Auto Attached React rule

Create .cursor/rules/react-components.mdc:

---
description: React and accessibility requirements
globs: "apps/web/**/*.tsx,packages/ui/**/*.tsx"
alwaysApply: false
---

# React components

- Use function components and strict TypeScript.
- Reuse primitives from `packages/ui/` before adding a new one.
- Keep network requests out of presentational components.
- Give icon-only controls an accessible name.
- Test keyboard interaction for dialogs, menus, and popovers.

Agent Requested architecture rule

Create .cursor/rules/api-architecture.mdc:

---
description: API architecture, validation, and data-access boundaries
globs:
alwaysApply: false
---

# API architecture

- Route handlers validate requests and call service functions.
- Business rules belong in `services/`.
- Database queries belong in `repositories/`.
- Do not expose internal database models in API responses.
- Follow the nearest existing endpoint before creating a new pattern.

The description must say when the rule matters. “API rules” is less useful than a description that names architecture, validation, and data access.

Manual release checklist

Create .cursor/rules/release-check.mdc:

---
description: Review a release candidate before deployment
globs:
alwaysApply: false
---

# Release review

When this rule is invoked:

1. Inspect changes since the previous release tag.
2. Identify database, authentication, billing, and configuration changes.
3. Check migrations and rollback steps.
4. Run the repository's release checks.
5. Return blockers, warnings, and checks performed.

Do not deploy or modify production systems.

Invoke it in a Cursor prompt with @release-check.

Reference a file from a rule

Cursor rules can include a file reference such as:

Follow the service structure in @service-template.ts.

Cursor includes the referenced file as additional context when the rule triggers. Reference a small, stable example. Do not point every rule at a large directory or a frequently changing generated file.

Use nested rules in a monorepo

Cursor supports .cursor/rules/ directories inside subdirectories:

project/
├── .cursor/rules/
├── apps/web/.cursor/rules/
└── services/api/.cursor/rules/

Nested rules are automatically associated with their directory and remain available in the rule picker. This is useful when two subprojects use different frameworks, commands, or deployment constraints.

Keep requirements at the narrowest accurate scope:

• repository-wide facts in the root rules directory;
• frontend rules beside the frontend;
• backend rules beside the backend;
• task-specific procedures as Manual rules.

Migrate from .cursorrules

Do not copy one large .cursorrules file into a single large .mdc file without review.

1. List each distinct concern in .cursorrules.
2. Remove stale commands, duplicated advice, and vague statements.
3. Put truly universal constraints in an Always rule.
4. Put language or folder rules behind globs.
5. Put optional procedures in Manual rules.
6. Test the new rules before removing the legacy file.
7. Remove .cursorrules after the team has migrated.

Running both systems during a short migration is reasonable, but duplicated or conflicting instructions can produce inconsistent results.

Cursor Rules versus AGENTS.md

Cursor’s CLI documents support for root-level AGENTS.md and CLAUDE.md. Avoid repeating the same instruction in three places. Define an owner for each rule and keep the files compatible.

Test whether a Cursor rule works

1. Start a fresh Agent conversation.
2. Ask a task that should trigger one rule.
3. Check whether the response follows a distinctive, safe instruction.
4. Test a file that should match the glob.
5. Test a file that should not match it.
6. Mention a Manual rule explicitly.
7. Revise unclear descriptions or patterns.

Do not test with a dangerous instruction. A harmless requirement such as a specific test command or output format is easier to verify.

Fix Cursor Rules that do not apply

The rule never triggers

Check its type. Agent Requested rules need a clear description. Auto Attached rules need a glob that matches the actual file path.

The rule applies too often

Change an Always rule to Auto Attached, Agent Requested, or Manual. Split broad globs into narrower path patterns.

Instructions conflict

Search .cursor/rules/, nested rule folders, user rules, .cursorrules, AGENTS.md, and CLAUDE.md. Remove duplication and assign each rule one authoritative location.

Cursor Tab ignores the rule

That is expected. Cursor’s current documentation says rules apply to Agent chat, not Tab completion or Inline Edit (Cmd/Ctrl+K).

Frequently asked questions

What file extension do Cursor project rules use?

Project rules use .mdc and live under .cursor/rules/.

Is .cursorrules deprecated?

Cursor labels .cursorrules as legacy and recommends Project Rules.

Should Cursor Rules be committed to Git?

Commit project rules that describe shared repository expectations. Keep personal preferences in Cursor User Rules.

How long should a Cursor rule be?

Cursor recommends focused, actionable rules and lists fewer than 500 lines as a good target. Many effective rules are far shorter.

Sources and verification

• Cursor documentation: Rules
• Cursor documentation: Using Agent in CLI

Cursor changes quickly. Verify rule fields and supported features against the current documentation before publishing screenshots or setup steps.

Related Markdific guides

• AGENTS.md guide
• Markdown files for AI agents
• GitHub Copilot instructions guide