Cursor rules work best when they tell Cursor how your project actually works: the stack, the folders that matter, the commands to run, and the changes that need extra caution.

The best Cursor rules are short .mdc project rules that describe your stack, folder structure, safety boundaries, and verification commands.

The mistake is using rules like a motivational poster.

Write clean code. Use best practices. Make it scalable.

That does almost nothing. Cursor does not need a pep talk. It needs project context and boundaries.

A better rule says something like:

This is a Next.js app using TypeScript, Tailwind, Supabase, and pnpm. Dashboard routes live in `src/app/dashboard`. Shared UI lives in `src/components`. Before saying a change is done, run `pnpm typecheck` and `pnpm lint`. Ask before changing auth, billing, database policies, or production deployment settings.

That is the difference. One rule gives vibes. The other gives the model concrete handles it can use.

This guide gives you copyable Cursor rules examples for common project types: Next.js, Supabase, content sites, Python automation, generated files, and build checks. Use them as starting points, not sacred text.

If you want the companion templates, fork the open-source AI Coding Workflow Starter Pack and start with the Cursor rules template. The VibeCodeSource starter-pack guide explains how the repo fits into a broader AI coding workflow.

Quick note: where Cursor project rules live

As of the current Cursor docs checked for this draft, Cursor supports project rules in .cursor/rules as .mdc files. Cursor says project rules are version-controlled and scoped to the codebase. Plain .md files inside .cursor/rules are ignored by Cursor’s rules system because project rules need .mdc frontmatter.

Cursor also documents AGENTS.md as a simple markdown alternative to .cursor/rules.

That matters because older guides may mention different patterns. Before publishing or updating a production workflow, check the current Cursor rules docs. Tool behavior changes fast.

A project rule may look like this:

---
description: Rules for frontend components
alwaysApply: false
globs: src/components/**/*.tsx
---

- Use existing components before creating new ones.
- Prefer named exports.
- Keep client components small.
- Run `pnpm lint` after component changes.

Cursor’s rule types include always-applied rules, intelligent rules selected by description, file-pattern rules selected by globs, and manual rules you mention in chat.

For most small projects, start simple:

  • one always-applied project overview rule
  • one or two file-specific rules for areas that matter, such as components, API routes, database code, or content
  • an AGENTS.md if you want repo instructions that other coding agents can also read

Do not build a tiny constitution before you have working code.

What good Cursor rules should include

Good Cursor rules usually answer six questions:

  1. What is this project?
  2. What stack and package manager does it use?
  3. Which folders matter?
  4. What commands prove the change still works?
  5. What files should not be edited?
  6. Which changes require approval or extra care?

That is enough for a strong first version.

Example 1: general project rule

Use this as the rule Cursor sees all the time.

Recommended file:

.cursor/rules/project-overview.mdc

Copyable example:

---
alwaysApply: true
---

# Project overview

This project is [short project description]. The main goal is [business or product goal].

Stack:
- Framework: [Next.js / Astro / Laravel / Django / etc.]
- Language: [TypeScript / JavaScript / Python / etc.]
- Package manager: [pnpm / npm / bun / uv / pip]
- Backend/database: [Supabase / Postgres / Firebase / none]
- Hosting: [Vercel / Netlify / Railway / VPS / etc.]

Important folders:
- `src/app` - routes and pages
- `src/components` - shared UI components
- `src/lib` - shared utilities and clients
- `content` - markdown content
- `scripts` - local automation scripts

How to work:
- Make the smallest useful change.
- Read nearby files before editing.
- Follow existing naming, folder, and component patterns.
- Do not add dependencies unless the task clearly needs them.
- Do not rewrite unrelated code while fixing a narrow issue.

Before reporting success:
- Run the relevant checks listed in `package.json` or project docs.
- If a check cannot run, explain why and what you verified instead.
- Summarize changed files and any remaining risks.

This is the rule that keeps Cursor from guessing basic project shape every time you open a new chat.

Example 2: Cursor rules for a Next.js SaaS app

A Next.js SaaS project needs tighter rules because a small mistake can hit auth, billing, routing, or server/client boundaries.

Recommended file:

.cursor/rules/nextjs-saas.mdc

Copyable example:

---
description: Next.js SaaS architecture, routing, auth, and build rules
alwaysApply: false
globs: src/**/*.{ts,tsx}
---

# Next.js SaaS rules

Project context:
- This is a Next.js app using TypeScript.
- Use the existing package manager. Do not switch package managers.
- Marketing pages live in `src/app/(marketing)`.
- Authenticated app pages live in `src/app/dashboard`.
- Shared UI components live in `src/components`.
- Shared server utilities live in `src/lib/server`.

Component rules:
- Prefer server components unless the feature needs browser state, effects, or event handlers.
- Keep client components small and isolated.
- Do not pass server-only secrets or clients into browser components.
- Use existing button, card, form, and layout components before creating new ones.

API and server rules:
- Validate inputs at the server boundary.
- Keep auth checks close to protected data access.
- Preserve public API behavior unless the task explicitly changes it.
- Do not expose server-only environment variables to the client.

Checks:
- Run `pnpm typecheck` after TypeScript changes.
- Run `pnpm lint` after UI or route changes.
- Run `pnpm build` before calling production-facing work done.

Ask first before changing:
- authentication behavior
- payment or subscription logic
- production environment settings
- database schema or permissions
- public API contracts

The important part is not the exact folder names. Change those to match your app. Bad folder context is worse than no folder context because it sends the model hunting in the wrong place.

Example 3: Cursor rules for a Supabase app

Supabase projects need clear boundaries around service-role keys, row level security, and data access. Cursor can write useful code here, but you do not want it casually weakening policy logic because a query failed.

Recommended file:

.cursor/rules/supabase-data.mdc

Copyable example:

---
description: Supabase auth, database, RLS, and server-side data rules
alwaysApply: false
globs: src/**/*.{ts,tsx},supabase/**/*.sql
---

# Supabase rules

Security boundaries:
- Never expose service-role keys in browser code.
- Keep admin/service-role operations server-side only.
- Do not weaken RLS policies to make a query work.
- Do not edit database migrations unless the task is specifically about schema changes.

Data access:
- Use the existing Supabase client helpers.
- Check the current user/session before reading user-owned data.
- For data access changes, explain which table policies protect the data.
- Prefer narrow selects over `select('*')` when the UI only needs a few fields.

Migrations and schema:
- New migrations must be reversible when the project pattern supports it.
- Do not rename or drop columns without calling out the data risk.
- Do not change storage bucket privacy without approval.

Checks:
- Run the project's TypeScript checks after client or server data changes.
- If local Supabase is required and not running, say that instead of pretending tests passed.

Ask first before changing:
- RLS policies
- auth redirects or session handling
- storage bucket permissions
- production database settings

If you only copy one line from this section, copy this one: do not weaken RLS policies to make a query work. That is exactly the kind of fix that looks helpful in the moment and becomes a security mess later.

Example 4: Cursor rules for a content site or SEO blog

A content site has a different failure mode. The model may not break the build. It may quietly invent facts, URLs, pricing, product features, or tool behavior.

Recommended file:

.cursor/rules/content-site.mdc

Copyable example:

---
description: Content, SEO, metadata, internal links, and fact-checking rules
alwaysApply: false
globs: content/**/*.{md,mdx},src/content/**/*.{md,mdx}
---

# Content site rules

Content standards:
- Write for practical search intent, not generic filler.
- Put a direct answer near the top of informational posts.
- Use specific examples, steps, checklists, and tradeoffs.
- Do not invent pricing, dates, tool features, legal claims, or client-specific facts.
- If a claim depends on current tool behavior, verify it against current docs.

SEO basics:
- Include a clear title or H1.
- Suggest a slug, meta title, and meta description when drafting a post.
- Add internal links where they help the reader.
- Include FAQ sections only when they answer real follow-up questions.

Voice:
- Avoid hype phrases like "game-changing," "revolutionary," and "unlock your potential."
- Keep the tone useful, direct, and human.
- Prefer short examples over long abstract explanations.

Checks:
- Verify markdown code fences are balanced.
- Do not publish editor notes such as "Suggested internal links" unless they are meant for readers.
- Confirm image alt text describes the image and topic honestly.

This is the kind of rule VibeCodeSource benefits from. It pushes the assistant toward useful content and away from AI-blog soup.

For a broader setup, read the VibeCodeSource guide to CLAUDE.md, AGENTS.md, and Cursor rules and the AI coding customization stack.

Example 5: Cursor rules for Python automation

Python automation needs rules for environment variables, logs, cron behavior, and safe failures. This matters even more when scripts run in the background.

Recommended file:

.cursor/rules/python-automation.mdc

Copyable example:

---
description: Python automation, cron scripts, logging, and verification rules
alwaysApply: false
globs: scripts/**/*.py,automations/**/*.py,*.py
---

# Python automation rules

Project behavior:
- Use environment variables for settings and secrets.
- Do not hard-code tokens, passwords, private URLs, or local-only paths unless the project docs require them.
- Scripts used by cron should print nothing when idle.
- Failures should print a clear error and exit non-zero.

Code style:
- Prefer small functions with obvious names.
- Keep side effects inside `main()` or clearly named functions.
- Avoid broad `except Exception` blocks unless the error is logged or re-raised with useful context.
- Do not add a dependency for simple standard-library work.

Verification:
- Run `python -m py_compile` on changed scripts.
- Run `pytest` when tests exist and the change affects logic.
- For cron-style scripts, test both the "nothing new" path and the "work found" path when practical.

Safety:
- Ask before deleting files, changing schedules, sending email, posting externally, or modifying credentials.
- Do not print secrets in logs or summaries.

That “print nothing when idle” rule sounds tiny. It is not. Quiet healthy scripts are what keep automation from turning into notification garbage.

Example 6: do-not-edit boundaries

Every project should tell Cursor what not to touch. Otherwise you can end up reviewing generated files, build output, lockfile noise, or accidental secret changes.

Recommended file:

.cursor/rules/do-not-edit.mdc

Copyable example:

---
alwaysApply: true
---

# Do not edit without explicit approval

Do not edit:
- `.env`, `.env.local`, or other secret files
- private keys, tokens, credentials, or OAuth files
- generated folders such as `.next/`, `dist/`, `build/`, `coverage/`, `.turbo/`, and vendor output
- minified files unless the source file is unavailable and the task requires it
- database migrations unless the task is specifically about schema changes
- lockfiles unless dependency changes require it
- unrelated files outside the requested scope

If a requested change appears to require one of these files, stop and explain why before editing.

This rule is boring. Good. Boring rules prevent exciting accidents.

Example 7: build and test verification rules

Cursor is useful, but it can still say something is done when it only made the edit. A task is not done until the relevant checks pass or the failure is explained.

Recommended file:

.cursor/rules/verification.mdc

Copyable example:

---
alwaysApply: true
---

# Verification rules

Before reporting a task complete:
- Run the narrowest useful check first.
- Run the broader build/test command when the change affects production behavior.
- If a command fails, summarize the failure and whether it appears related to the change.
- If a command cannot run because a service, secret, or dependency is missing, say that clearly.
- Do not claim tests passed unless they actually ran.

Common commands:
- TypeScript project: `pnpm typecheck`
- Lint check: `pnpm lint`
- Unit tests: `pnpm test`
- Production build: `pnpm build`
- Python syntax: `python -m py_compile path/to/script.py`
- Python tests: `pytest`

Definition of done:
- Requested change is complete.
- Relevant checks were run or clearly blocked.
- Files changed are summarized.
- Risks and follow-ups are listed.

This is the rule that fights the classic AI coding failure: confident completion without verification.

The one rule most projects are missing

A verification rule turns “I made the edit” into “I made the edit and the build still passes.” It is the cheapest guardrail you can add and the one that catches the most confident-but-broken changes.

If you are close to launch, pair this with the Vibe Coding Deployment Checklist and the guide on why vibe-coded apps break in production.

Cursor rules vs AGENTS.md vs CLAUDE.md

Use the file your tool reads best, but do not duplicate every rule everywhere.

A simple split:

  • Cursor rules: Cursor-specific behavior, scoped project rules, file-pattern rules, and editor workflow guidance.
  • AGENTS.md: repo-level instructions that multiple AI coding agents can read.
  • CLAUDE.md: Claude Code-specific project context and workflow notes.
  • README: human-facing setup and project documentation.

If the same instruction appears in five places, it will drift. Pick a source of truth. If the rule matters across tools, put it in AGENTS.md or a normal project doc, then use Cursor rules for Cursor-specific behavior.

For a deeper comparison, read CLAUDE.md, AGENTS.md & Cursor Rules: How to Give AI Project Context. If you want a repo-level template, use the AGENTS.md template for AI coding tools.

Common Cursor rules mistakes

Writing vague rules

Bad:

Write clean, scalable, production-ready code.

Better:

Use existing components before creating new ones. Validate inputs in API routes. Run `pnpm typecheck` and `pnpm lint` before reporting success.

Making the rules too long

A giant rule file becomes a junk drawer. Cursor may include it, but that does not mean the model will follow the part you care about.

Keep rules short. Put detailed architecture docs in normal documentation files and reference them when needed.

Hiding project-critical rules in personal settings

User rules are useful for personal preferences. Project rules should live with the repo when the instruction affects how the project should be maintained.

If another developer or AI session needs the same instruction, it belongs in the project.

Putting secrets in rules

Never put tokens, passwords, private keys, customer data, or webhook URLs in Cursor rules. Rules are context. Treat them like something an assistant may read back, summarize, or send into a model context.

Letting commands go stale

If your project moves from npm to pnpm, or your build command changes, update the rule. Stale commands are worse than missing commands because the assistant may waste time debugging the wrong thing.

A simple Cursor rules starter set

If you do not know where to start, create this:

.cursor/rules/
  project-overview.mdc
  do-not-edit.mdc
  verification.mdc

Then add stack-specific rules only when they earn their keep.

For example:

.cursor/rules/
  nextjs-saas.mdc
  supabase-data.mdc
  content-site.mdc
  python-automation.mdc

You do not need all of these in every project. A small static site does not need Supabase rules. A Python script folder does not need Next.js component rules.

Start with the repeated mistakes you actually want to prevent.

FAQ

What are Cursor rules?

Cursor rules are reusable instructions for Cursor’s AI agent. They help Cursor understand project structure, coding conventions, safety boundaries, and verification steps.

Where should Cursor project rules live?

Current Cursor docs say project rules live in .cursor/rules as .mdc files. Cursor also documents AGENTS.md as a simple markdown alternative. Check the current Cursor docs before publishing team-wide guidance because this area changes.

What should I put in Cursor rules?

Put stable project instructions in Cursor rules: stack, package manager, folder map, coding boundaries, commands to run, and areas that require approval. Do not use rules for one-off preferences or long tutorials.

Should Cursor rules include secrets?

No. Do not put secrets, private keys, credentials, tokens, customer data, or private webhook URLs in Cursor rules.

Are Cursor rules the same as AGENTS.md?

No. They overlap, but they are not the same thing. Cursor rules are Cursor-specific and can be scoped. AGENTS.md is a plain repo instruction file that multiple agents and tools may read.

How long should Cursor rules be?

Short enough to stay useful. One or two screens is a good target for most rules. Split rules by area when one file starts turning into a manual.

When should I update Cursor rules?

Update them when the stack changes, folders move, commands change, auth/database/deployment rules change, or Cursor keeps making the same mistake.

Copy the starter pack

If you want a practical baseline, fork the AI Coding Workflow Starter Pack.

Start here:

Cursor rules will not make AI coding magically safe. They just remove avoidable confusion.

That is still worth doing. Most vibe-coded projects do not fail because the idea was impossible. They fail because nobody wrote down the boring rules until after the tool already broke them.