Free .cursorrules Examples You Can Copy and Paste

# Project Rules

You are a senior engineer working in this repository. Follow the conventions below on every edit.

## General principles
- Write clear, self-documenting code. Prefer readable names over comments.
- Keep changes minimal and scoped to the request. Do not refactor unrelated code.
- Match the existing style of the file you are editing (indentation, quotes, imports).
- If you are unsure about a project convention, look at a nearby file before inventing a new pattern.

## Do
- Handle errors explicitly. Never swallow exceptions silently.
- Validate external input (API params, env vars, user data) at the boundary.
- Add or update tests when you change behavior.
- Keep functions small and single-purpose.

## Do not
- Do not add new dependencies without a clear reason.
- Do not leave commented-out code or debug prints in the final edit.
- Do not change public function signatures without updating all call sites.
- Do not introduce TODO comments as a substitute for finishing the work.

## Output
- When you finish, give a one-line summary of what changed and why.

A safe, stack-agnostic baseline. Drop this in any repo on day one, then layer stack-specific rules on top.

# Git and commit conventions

## Commits
- Use Conventional Commits: feat, fix, docs, refactor, test, chore, perf.
- Format: type(scope): short imperative summary (max 72 chars).
- Example: fix(auth): reject expired refresh tokens
- Keep the subject line under 72 characters. Add a body only when the why is not obvious.

## Branches
- Branch names: type/short-description (e.g. feat/user-invites).
- Never commit directly to main.

## Before proposing a commit
- Group related changes together. Do not mix a refactor and a feature in one commit.
- Do not commit secrets, .env files, or API keys.

Keeps Cursor from writing vague commit messages and mixing unrelated changes into one commit.

# Security rules

## Secrets
- Never hardcode secrets, tokens, passwords, or API keys in source. Read them from environment variables.
- Never log secrets or full tokens. Mask them (e.g. show last 4 only).
- Add any new secret name to .env.example with a placeholder value, never the real value.

## Input handling
- Treat all external input as untrusted. Validate and sanitize at the boundary.
- Use parameterized queries. Never build SQL with string concatenation.
- Escape or encode output rendered into HTML to prevent XSS.

## Auth
- Check authorization on every protected route, not just authentication.
- Fail closed: if a permission check errors, deny access.
- Never roll your own crypto. Use the platform or a vetted library.

A short guardrail block that stops the most common AI mistakes: leaked keys, string-built SQL, and missing auth checks.

# Reviewer persona

When asked to review code, act as a strict but constructive senior reviewer.

## Focus order
1. Correctness: does it do what it claims? Any edge cases missed?
2. Security: input validation, auth, secrets, injection.
3. Error handling: are failures handled or swallowed?
4. Tests: is the new behavior covered?
5. Readability and naming.
6. Performance, only if it matters here.

## How to respond
- List issues grouped by severity: blocking, should-fix, nit.
- For each issue, quote the relevant line and give a concrete fix, not just a complaint.
- If the code is fine, say so plainly instead of inventing problems.
- Do not rewrite the whole file unless asked. Suggest targeted diffs.

Turns Cursor into a focused reviewer that ranks by severity and gives concrete fixes instead of vague praise.

# Next.js (App Router) + TypeScript rules

You are an expert in TypeScript, React, Next.js App Router, and Tailwind CSS.

## Framework
- Use the App Router (app/ directory). Do not use the legacy pages/ router.
- Default to Server Components. Add use client only when you need state, effects, or browser APIs.
- Fetch data in Server Components or route handlers, not in client-side useEffect where avoidable.
- Use Server Actions for mutations instead of ad hoc API routes when it fits.

## TypeScript
- Enable strict mode. No implicit any.
- Never use the any type. Use unknown and narrow it.
- Type function return values for exported functions.

## Components
- One component per file. Name files in PascalCase for components (Button.tsx).
- Keep components small. Extract logic into hooks (use-*.ts) or plain functions.
- Props: destructure in the signature, define a typed Props type above the component.

## Styling
- Use Tailwind utility classes. Avoid inline style objects except for dynamic values.

## Do not
- Do not fetch secrets in client components.
- Do not use default exports for components in shared folders. Use named exports.
- Do not disable eslint rules inline without a comment explaining why.

A complete, opinionated rules file for a modern Next.js App Router codebase with strict TypeScript.

# React + Vite SPA rules

Expert in React 18, TypeScript, Vite, and React Router.

## Structure
- src/components for shared UI, src/features for feature-scoped code, src/lib for helpers.
- Keep feature logic inside its feature folder. Shared code moves to lib only when used by 2+ features.

## Components
- Function components only. No class components.
- Use named exports. Props typed with a Props type. No any.
- Derive state, do not duplicate it. Compute from existing state instead of syncing with useEffect.

## Hooks
- Custom hooks live in the feature or in src/hooks, named use-*.ts.
- Follow the rules of hooks. No conditional hook calls.
- useEffect is a last resort. Prefer event handlers and derived values.

## Data fetching
- Use a query library (e.g. TanStack Query) for server data. Do not hand-roll caching in useEffect.
- Always handle loading and error states in the UI.

## Do not
- Do not mutate state directly. Always create new objects and arrays.
- Do not use index as a React key when the list can reorder.
- Do not put business logic in JSX.

For client-side React apps built with Vite. Stops the classic useEffect-for-everything and state-duplication mistakes.

# Tailwind + accessibility rules

## Tailwind
- Order classes logically: layout, spacing, sizing, color, typography, state.
- Use design tokens from tailwind.config (colors, spacing) instead of arbitrary values.
- Use responsive prefixes (sm:, md:, lg:) rather than duplicated components.
- Dark mode via the dark: variant, not a separate stylesheet.

## Accessibility (non-negotiable)
- Every interactive element must be a real button or a link, not a clickable div.
- All images need alt text. Decorative images use empty alt.
- Form inputs must have associated labels (htmlFor + id).
- Maintain visible focus states. Do not remove outlines without a replacement.
- Use semantic HTML: nav, main, header, footer, section with headings.
- Color is never the only signal. Pair it with text or an icon.

## Do not
- Do not use onClick on a div to fake a button.
- Do not set tabindex above 0.
- Do not hide content screen readers need with display none. Use an sr-only class.

Bakes accessibility and Tailwind hygiene into every component Cursor generates, catching a11y bugs before they ship.

# Python + FastAPI rules

Expert in Python 3.11+, FastAPI, Pydantic v2, and SQLAlchemy 2.0.

## Style
- Follow PEP 8. Format with Black (line length 88). Sort imports with isort or ruff.
- Use type hints on every function signature, including return types.
- Use f-strings for formatting. Never use percent or .format() for new code.

## FastAPI
- Validate request and response bodies with Pydantic models, not raw dicts.
- Use dependency injection (Depends) for db sessions, auth, and settings.
- Group routes with APIRouter, one router per resource.
- Return proper status codes. Raise HTTPException with a clear detail message.
- Use async def for IO-bound endpoints. Do not block the event loop with sync IO.

## Data layer
- Use SQLAlchemy 2.0 style (select(), not query()).
- Never build SQL by string concatenation. Use the ORM or bound parameters.
- Keep db access in a repository or service layer, not in route functions.

## Errors and logging
- Catch specific exceptions, never a bare except.
- Use the logging module, not print, in application code.
- Log context (ids, operation) but never secrets.

## Testing
- Write pytest tests. Use fixtures, not setup boilerplate.
- Every bug fix gets a regression test.

A production-grade rules file for FastAPI services, covering Pydantic v2, async, the data layer, and testing.

# Python data / ML rules

Expert in Python, pandas, NumPy, and scikit-learn.

## Code style
- Type hints on functions. Docstrings on non-trivial functions.
- Prefer vectorized pandas and NumPy operations over Python loops.
- Use meaningful column and variable names, not df1, df2, x, y.

## Data handling
- Never mutate a DataFrame passed as an argument. Return a new one or use .copy().
- Avoid chained indexing that triggers SettingWithCopyWarning. Use .loc.
- Handle missing values explicitly. State the strategy (drop, fill, flag).
- Set random_state on every split, sampler, and model for reproducibility.

## ML workflow
- Split train/validation/test before any fitting. Never fit a scaler on test data.
- Use Pipeline to bundle preprocessing and model so leakage cannot happen.
- Report the metric that matches the problem, not just accuracy on imbalanced data.

## Do not
- Do not hardcode file paths. Use a config or pathlib.
- Do not leak the test set into training or feature selection.

Rules aimed at pandas and scikit-learn work, stopping data leakage, silent DataFrame mutation, and slow Python loops.

# Django rules

Expert in Python and Django 5.

## Structure
- Fat models, thin views. Business logic lives in models or a services.py, not in views.
- One app per bounded domain. Keep apps focused and reusable.
- Use class-based views for CRUD, function views only for simple one-offs.

## Models
- Add a __str__ to every model.
- Use explicit related_name on ForeignKey and ManyToMany.
- Prefer database constraints (unique, check) over validating only in Python.
- Make and review migrations. Never edit an applied migration.

## Queries
- Avoid N+1: use select_related for FK and prefetch_related for M2M.
- Never call the ORM inside a template loop.

## Security
- Never disable CSRF protection.
- Use Django forms or DRF serializers to validate input. Do not trust request.POST directly.
- Keep SECRET_KEY and DB credentials in environment variables.

## Testing
- Use pytest-django. Use factory_boy for test data.
- Test views through the test client, models directly.

A Django-specific ruleset focused on the ORM footguns (N+1, migrations) and the fat-model, thin-view convention.

# Monorepo rules (pnpm workspaces + Turborepo)

## Layout
- apps are deployable applications. packages are shared libraries.
- Apps may depend on packages. Packages must not depend on apps.
- Shared code goes in a package, never copy-pasted between apps.

## Dependencies
- Use the workspace protocol for internal deps (workspace star).
- Add a dependency to the specific package that uses it, not the root, unless it is a repo-wide dev tool.
- Keep versions of shared external deps (react, typescript) aligned across packages.

## Imports
- Import shared code by its package name, never by deep relative paths across package boundaries.
- Each package exposes a clear public API via its exports field. Do not import a package internal files.

## Tooling
- Every task (build, lint, test, typecheck) is defined in turbo.json with correct inputs and outputs for caching.
- Run commands with the workspace filter, not by cd-ing around.

## Do not
- Do not create circular dependencies between packages.
- Do not reach into another package src. Use its exported entry point.

Encodes the rules that keep a pnpm/Turborepo monorepo healthy: no cross-package deep imports, no cycles, correct workspace deps.

# Verification rules (do not hallucinate)

Accuracy matters more than speed. Follow these rules on every task.

## Before you write code
- Do not invent APIs, functions, methods, props, or config keys. If you are not certain something exists, check the actual source in this repo or say you are unsure.
- Read the real file before editing it. Do not assume its contents from its name.
- If a library API is uncertain, look at how it is already used elsewhere in this codebase and match that.
- Prefer patterns already present in the repo over patterns from memory that may be outdated.

## While writing
- Only import what actually exists. Verify the import path resolves in this project.
- Do not reference files, env vars, or scripts you have not confirmed exist.
- If the request needs information you do not have, ask for it or state the assumption explicitly instead of guessing.

## After writing
- Re-read your own diff. Confirm every symbol you used is defined or imported.
- List any assumptions you made and anything you could not verify.

## Honesty
- Never state that code runs, passes tests, or is complete unless you actually verified it.
- If you are guessing, say so. A flagged uncertainty is more useful than a confident wrong answer.
- Do not silently drop parts of the request. If you skipped something, name it.

The single highest-value rule block: forces Cursor to check real files, stop inventing APIs, and admit uncertainty instead of confidently making things up.

# Testing and definition of done

## Definition of done
A task is not done until:
1. The code compiles and type-checks with no new errors.
2. Lint passes with no new warnings.
3. New behavior has tests. Bug fixes have a regression test that fails before the fix.
4. You have re-read the diff and every changed line maps to the request.

## Writing tests
- Test behavior and public contracts, not private implementation details.
- One clear assertion focus per test. Name tests by what they verify.
- Cover the happy path, the boundary cases, and the error path.
- Use the testing framework and helpers already present in the repo.

## Do not
- Do not delete or weaken a failing test to make the suite green. Fix the cause.
- Do not add sleeps to fix flaky async tests. Await the real condition.
- Do not mock the thing you are trying to test.

## Reporting
- State which tests you added or changed and what they cover.
- If you could not run the tests, say so clearly instead of implying they passed.

Gives Cursor a concrete definition of done so it stops declaring victory early and stops gaming the test suite to look green.