Cursor Rules Examples: 9 Copy-Paste .mdc Files for All Four Rule Types

Published 2026-10-22 · 6 min read · by AgentKit Co

A Cursor rule is a small Markdown file that tells Cursor's agent how your project works. Good ones are short, specific and scoped, so they load only when they matter. This page gives nine you can paste in today, grouped by the four rule types, with a note on why each one is set up the way it is.

Everything here was checked against Cursor's Rules docs on 2026-10-20. Cursor changes quickly, so re-check the docs for anything you depend on.

First, where the files go

Project rules live in .cursor/rules/ and must use the .mdc extension. Subfolders are fine. A plain .md file in that folder is ignored, because it has no frontmatter.

.cursor/rules/
  project-basics.mdc
  frontend/
    react-components.mdc
  backend/
    api-endpoints.mdc

Three frontmatter fields decide when a rule loads:

You can also type /create-rule in the agent chat and describe what you want; Cursor writes the file with frontmatter for you. The examples below are a good starting point either way.

Always Apply: keep these tiny

An always-on rule is paid for in every single chat, so it should hold only what the agent truly can't guess.

1. Project basics

---
alwaysApply: true
---

- Package manager is pnpm. Never run npm or yarn.
- Before saying a task is done, run `pnpm lint` and `pnpm test` for the
  packages you changed, and report the result.
- Never edit files in `dist/`, `build/` or `src/generated/`.
- Ask before adding a new dependency.

Why it works: every line is something the agent would plausibly get wrong. It doesn't explain what pnpm is or how git works; Cursor's docs say the agent already knows common tools.

2. Safety boundaries

---
alwaysApply: true
---

- Never read, print or edit `.env` files or anything in `secrets/`.
- Never run commands that delete data outside the repo, push to `main`,
  or change git history (`reset --hard`, `push --force`).
- If a task seems to need one of these, stop and ask first.

Rules are guidance, not enforcement. Keep this rule, but also add a real guard (branch protection, a pre-push hook, tool permissions) for anything that must never happen.

Apply to Specific Files: the workhorse type

Glob rules attach only when a matching file is in the conversation, so they can be detailed without costing you anything elsewhere. Use **/ when you mean "in any folder": *.ts only matches the project root.

3. React components

---
globs: src/components/**/*.tsx
alwaysApply: false
---

- Function components with named exports only. No default exports.
- Props get an interface named `<Component>Props` above the component.
- Styles go in a CSS module next to the file (`Button.module.css`).
- Keep files under 200 lines; split subcomponents into the same folder.
- Copy the structure of `@src/components/Button/Button.tsx` for new
  components.

That @ path isn't pasted into the prompt. It tells the agent where a good example lives, and the agent reads it when it needs to.

4. Tests

---
globs: **/*.test.ts, **/*.test.tsx
alwaysApply: false
---

- Test framework is Vitest. Import `describe`, `it`, `expect` from `vitest`.
- One behavior per test; name tests "does X when Y".
- Mock the network with `msw` handlers in `src/test/handlers.ts`.
  Never call real APIs from tests.
- Don't delete or weaken a failing test to make it pass. Fix the code
  or explain why the test is wrong.

The last line is the one that saves real time: agents under pressure to "make tests pass" love to edit the test.

5. SQL migrations

---
globs: db/migrations/**/*.sql
alwaysApply: false
---

- Never edit a migration that has already been merged. Write a new one.
- Every migration needs a matching down migration.
- Don't change a column type in place: add a new column, backfill,
  then drop the old one in a later migration.
- New tables need a primary key and `created_at timestamptz not null
  default now()`.

6. Python scripts

---
globs: scripts/**/*.py
alwaysApply: false
---

- Python 3.12. Use `uv run scripts/<name>.py` to run scripts.
- Type hints on every function. Use `pathlib`, not `os.path`.
- Scripts must be safe to re-run: check before creating or deleting.
- Print a one-line summary at the end (what changed, how many items).

Apply Intelligently: the description is the trigger

For these, the agent sees only the description when deciding whether to load the rule. Name a concrete situation, not a topic. "Backend stuff" never matches anything; "Adding or changing HTTP endpoints under src/api/" does.

7. API endpoints

---
description: Conventions for adding or changing HTTP endpoints under src/api/, including validation, error responses and route registration
alwaysApply: false
---

- Validate every request body with a zod schema at the route boundary.
- Errors return `{ "error": { "code": string, "message": string } }`
  with a matching HTTP status. Never return raw exception text.
- Register new routes in `src/api/routes.ts`; keep handlers thin and put
  logic in `src/services/`.
- Add or update the endpoint's test in `src/api/__tests__/`.

8. Auth and permissions

---
description: Read before touching login, sessions, tokens, roles or permission checks anywhere in the app
alwaysApply: false
---

- All permission checks go through `can(user, action, resource)` in
  `src/auth/permissions.ts`. Don't write inline role checks.
- Never log tokens, session ids or passwords, even in debug output.
- Any change here needs a test for the denied case, not just the
  allowed one.

Apply Manually: checklists you call by name

A rule with no description, no globs and alwaysApply: false loads only when you mention it. That's perfect for procedures you run now and then.

9. Release checklist

---
alwaysApply: false
---

When I mention this rule, prepare a release:

1. Read `CHANGELOG.md` and list merged changes since the last tag.
2. Propose the next version number (semver) and say why.
3. Draft the changelog entry in the existing style.
4. Run `pnpm build` and `pnpm test` and report the results.
5. Stop before tagging or publishing. Show me the plan and wait.

Use it in chat with @release-checklist (the file name without .mdc).

Five habits that keep rules working

1. Start small. Cursor's own advice is to add a rule only when you see the agent make the same mistake more than once.
2. Stay under 500 lines per rule, and split big ones into smaller scoped files.
3. Point to examples instead of pasting code. A referenced file stays current; a pasted copy goes stale.
4. Don't copy a style guide. Use a linter for formatting and keep rules for decisions a linter can't make.
5. Mind the order. Team rules win over project rules, which win over user rules, when guidance conflicts.

If a rule seems to be ignored, the cause is almost always the extension, the frontmatter or a glob that doesn't match. Our Cursor rules not working guide walks through all eight fixes.

Skip the blank page

Our free AGENTS.md generator builds an AGENTS.md plus an always-on Cursor rule from your real package.json or pyproject.toml, in your browser. For more, the AI Coding Agent Config Kit ($14) has 8 Cursor .mdc rules covering all four rule types, templates for 12 stacks and 12 prompts that draft and audit your own files.

Sources: Cursor Rules docs (checked 2026-10-20). Related: AGENTS.md vs CLAUDE.md vs Cursor rules and how to write an AGENTS.md. AgentKit Co is not affiliated with Cursor or Anysphere. This guide was written with AI assistance and checked against the page above.

Keep reading