Cursor Rules: How to Set Up Project Rules That Actually Work

File Location

For project rules, use a .cursor/rules directory in the repository. A common first file is project.mdc.

.cursor/rules/project.mdc

Working Example

Keep the content direct and operational.

---
description: Project coding rules
globs: ["**/*"]
---
Use TypeScript for app code.
Run npm test before final handoff.
Keep components small and prefer existing UI patterns.

Common Mistakes

Most weak rules are either too broad or too stale.

• Do not duplicate the entire README.
• Do not hide critical test commands in old chat history.
• Do not write rules that conflict with formatter or lint config.

Cursor Rules File Types

A practical Cursor setup usually starts with one project-level rule and grows into focused rules for frameworks, packages, or file types. The goal is not more rules; it is better context at the moment the AI edits a file.

• Project rule: broad architecture, commands, and review expectations.
• Framework rule: Next.js, React, Python, or API-specific patterns.
• Package rule: monorepo conventions for one workspace.
• Test rule: how to write, run, and name tests.

What To Put In Cursor Rules

The strongest Cursor Rules explain concrete repo behavior: where code lives, which commands validate changes, which patterns to reuse, and what mistakes the AI should avoid.

• Architecture notes that are stable across tasks.
• Test, build, lint, and typecheck commands.
• Component, API, database, and styling conventions.
• Review expectations and forbidden shortcuts.

Cursor Rules Template

Use a small rule file first, then split rules by package or file type when a monorepo grows.

---
description: Frontend rules
globs: ["app/**/*", "components/**/*"]
---
Use existing components before creating new ones.
Keep UI accessible and responsive.
Run npm run lint and npm run build before handoff.

Bad Rules To Avoid

Weak rules often sound impressive but do not change output quality. Replace vague preferences with concrete commands, directories, examples, and failure modes the AI can actually follow.

• Avoid: write clean code. Prefer: keep components under 180 lines unless there is a clear reason.
• Avoid: follow best practices. Prefer: use the existing API client in lib/api before adding another fetch wrapper.
• Avoid: test everything. Prefer: run npm test for logic changes and npm run build before release.

Monorepo Cursor Rules

In monorepos, use globs to keep rules specific. A frontend package, API package, and shared library usually need different instructions and different validation commands.

---
description: API package rules
globs: ["packages/api/**/*"]
---
Run pnpm --filter api test for API changes.
Keep database migrations in packages/api/migrations.
Do not change shared types without checking dependent packages.

FAQ