Cursor Rules

The payoff is less review cleanup. As an illustrative budget, four developers making three five-minute corrections each week spend 60 minutes repeating conventions. That is not a promised saving. Count which corrections disappear after setup, and subtract the time you spend maintaining the rules. Your subscription bill is a separate question, covered in Cursor pricing.

Where Cursor Rules Go

Put shared coding decisions beside the code. Keep personal reply preferences personal.

Nested AGENTS.md instructions apply to their directory and its children, combining with parent guidance; more specific instructions take precedence. For Team, Project and User Rules, the documented conflict order is Team → Project → User. Cursor's rules reference

My default for a small team is project rules. An instruction such as “use our existing form components” belongs to the repository. “Keep your final reply short” belongs to you. Separating those decisions prevents a personal preference from becoming accidental team policy.

Choose When Each Rule Attaches

The frontmatter, the small settings block above a rule's text, controls attachment.

“Agent-requested” means the agent selects the rule from its description. A glob is a file path pattern. Attachment behavior and syntax

Think of attachment as delivering a work order to the right bench. A beautifully written instruction is useless on a task that never receives it. Make the security baseline universal, send style guidance to the relevant files, and reserve discretionary selection for guidance whose relevance depends on the task.

Three Copy-Paste Rules for a TypeScript Web App

Create the following files in your repository. These are suggested house conventions, using the frontmatter fields and pattern syntax in Cursor's reference. The instructions inside are starting points to adapt, not Cursor's prescribed coding standards.

Style: Attach to TypeScript Files

Save as .cursor/rules/style.mdc:

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

- Follow the nearest existing module's naming and import conventions.
- Prefer named exports unless the framework requires a default export.
- Reuse existing UI components and utilities before adding alternatives.
- Keep formatting in the repository's formatter and linter configuration.

This example assumes application code lives under src/; adjust the paths to match your repository. It is deliberately about choices a formatter cannot settle, such as whether the app already has a suitable button or date helper. Adjust the export preference if your team has made a different decision. A rule should describe your repository, not quietly redesign it.

Tests: Describe the Tasks That Need Them

Save as .cursor/rules/tests.mdc:

---
description: Testing requirements when adding features, fixing bugs, or changing TypeScript behavior
alwaysApply: false
---

- Cover changed behavior with a focused regression test.
- Use the existing test runner, fixtures, and file naming conventions.
- Read package.json for the relevant test script; do not invent a command.
- Report the command and actual result, or explain why tests were not run.

The intended outcome is a useful test and an honest result. A bug fix should leave evidence that the original failure is covered. A refactor should preserve the relevant behavior. Neither needs a second testing framework or a report that confuses “test written” with “test passed.”

For work where you want this checklist explicitly, include @tests in your request. If your team wants it on every task, change its attachment to Always Apply. Treat that as a deliberate policy choice; the description alone leaves selection to the agent.

Security: Keep the Baseline Short

Save as .cursor/rules/security.mdc:

---
alwaysApply: true
---

- Never put secrets in source code, test fixtures, or application logs.
- Use existing server-side authentication and authorization helpers.
- Validate untrusted input at server boundaries with the existing schemas.
- Do not remove permission checks to make a feature or test pass.

Replace “existing helpers” with your repository's actual module paths when you know them. Keep the baseline understandable during an ordinary feature task. “Make it secure” gives a reviewer little to inspect; “preserve the authorization check” identifies a concrete requirement.

This file is an instruction, not a security boundary. Continue enforcing access checks in code and reviewing sensitive changes. Cursor itself cautions against relying on AI guidance as the only security control. Team Rules guidance

Verify the Setup on a Real Change

Use a small task that previously caused repeated corrections. A form validation change is a useful candidate: it touches a component, changes behavior and accepts user input.

1. Write down the expected outcome. Name the existing component to reuse, the behavior to test and the validation boundary to preserve.
2. Save the three files and inspect their status. Cursor exposes rules under Customize → Rules; /create-rule is also available in Agent. Creating a rule
3. Ask for the change with the relevant files in context. Keep the request realistic. A task that restates every rule cannot tell you whether the setup helped.
4. Review the diff and reported checks. Look for the actual convention, not an assurance that the rules were followed. If the test checklist matters for this trial, explicitly request @tests.
5. Commit the useful rules with the change. Give the team a reviewable starting point. Amend a vague sentence before adding another file.

If a convention is missed, separate two failures: the rule did not reach the task, or the instruction reached it but was ineffective. The first calls for an attachment fix. The second calls for a clearer instruction, an example, or an automated check.

The Few Conventions Worth Keeping

Start where repeated mistakes cost your team the most. These are practical uses to consider, ranked by the review burden they could remove.

Do not turn these into a mandate to create five more files. If a problem has not occurred, leave it out. If a machine can check the requirement precisely, prefer that check. A useful rule fills a gap between the task request and the repository's existing tooling.

What About the Old .cursorrules File?

Use .cursor/rules/*.mdc for the current documented project setup. As of October 11, 2026, the rules page does not mention .cursorrules, so it does not confirm whether the legacy file still works. Current reference

For a repository that still carries the old file, my recommendation is to move its useful instructions into focused project rules, using the three files above as a starting point. Choose their triggers, and verify a real task before retiring the old copy. Do not preserve obsolete conventions simply because they were already written down.

How This Maps to CLAUDE.md and AGENTS.md

The shared idea is a standing project brief: Claude Code has CLAUDE.md, and Codex reads AGENTS.md working agreements. Cursor's plain Markdown option serves that same simple use case, while its .mdc files expose attachment choices. Keep the underlying conventions consistent, but configure each tool's loading behavior deliberately; copying prose is not the same as copying settings. For teams using several agents, nominate one owner for the shared conventions so the files do not become competing sources of truth.

Two Small Tools Worth Building After Setup

A repository rule checker is the stronger opportunity for an engineering lead: check file extensions, recognized frontmatter fields and patterns that match no tracked files. Its smallest useful version is a local report run during review. The demand signal is modest: DataForSEO returned 140 estimated monthly searches for “cursor rules examples” in this article's research. That is adjacent interest, not evidence people will pay. The catch is clear: a structurally valid rule can still be poor guidance. Metric definition

A team convention review packet could help a lead maintaining several repositories. Turn recurring review comments and approved examples into a proposed rules diff, with a named reviewer for each change. DataForSEO returned 70 estimated monthly searches for “cursor team rules”. Start as an internal utility; native Team Rules already handle distribution, so another storage dashboard is a weak product. The useful work is deciding what deserves to become a standing instruction. Metric definition

Questions That Come Up During Setup

Next week, pick one recurring correction, make the corresponding rule precise, and try it on the next ordinary pull request. For the broader product decision, read the Cursor review or best Cursor alternatives.

If you want this wired into a team's development workflow, AI production systems is where that work fits.