Cursor Rules: How .mdc Files Work, Three to Copy, and What 498 Public Rules Show

What are Cursor rules, and where do they live?

A Cursor rule is persistent instruction text that Cursor puts into the Agent's context. The rules documentation, read on 26 September 2026, lists four kinds, and the first is the one people mean when they say “cursor rules”:

Creation is two commands. The docs say to “type /create-rule in Agent and describe what you want”, after which “Agent generates the rule file with proper frontmatter and saves it to .cursor/rules”, or to add one from the Customize sidebar. Either way the result is a plain file you can also write by hand, which is what the rest of this guide does.

One thing the page does not contain, as of 26 September 2026, is any mention of the single-file .cursorrules format that older tutorials describe. The collection with the most stars on GitHub, awesome-cursorrules, still carries the old name but has converted all 257 of its files to .mdc. Treat the folder as the format and the root file as history.

How does a .mdc rule file work?

An .mdc file is markdown with a YAML header. The header has three fields, and the docs define them as: alwaysApply, a boolean that “determines if rule applies universally or conditionally”; description, a string that “explains rule purpose for Agent relevance detection”; and globs, comma-separated “file path patterns triggering auto-attachment”. The example the docs give is short enough to quote in full:

---
alwaysApply: true
---

- All source files must include the company copyright header
- When you are unsure about implementation details, read the relevant
  source files before proposing changes
- Never modify generated files in the `dist/` or `build/` directories

The three fields combine into four application modes. The names below are the docs' names, and the trigger column is quoted from the same table:

Three more lines from the docs matter in practice. “Keep rules under 500 lines.” “Split large rules into multiple, composable rules.” And “reference files instead of copying their contents”, which is the @filename.ts syntax that includes a file without pasting it. The next section shows how far public rules sit from those three lines.

What do 498 public Cursor rules actually look like?

Most guides quote the 500-line rule and move on. We cloned the two most-starred public collections and measured every file on 26 September 2026: awesome-cursorrules, community-written and converted to .mdc, and awesome-cursor-rules-mdc, whose README says its files were produced by an LLM from web search results. The script is in the site repository, so the numbers are reproducible.

The two collections disagree by a factor of four on length. Hand-written rules cluster under 100 lines; the generated ones cluster between 100 and 500, because each is a full “best practices” essay for one library. Both stay under the 500-line limit almost everywhere, with 6 exceptions each. Where both fall short of the docs is scoping.

82% of the community rules set globs: **/*, which attaches them to every file and makes them Always Apply rules in everything but name. Only 1 file in 498 uses alwaysApply: true honestly, and 4 reference another file with @path instead of pasting. The four modes exist; the public corpus uses one of them.

Whether any of this helps is a separate question, and it has one controlled answer. Gloaguen, Mündler, Müller, Raychev and Vechev at ETH Zurich tested repository context files (AGENTS.md and equivalents) across coding agents and models on SWE-bench tasks plus a fresh issue set, in Evaluating AGENTS.md (arXiv 2602.11988, revised 23 June 2026). Their abstract: “providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average”, and “while instructions in the context files are well followed by coding agents, repository overviews, although popular and recommended by model providers, are not helpful”. Their conclusion is the design rule for everything below: context files “are useful for specifying non-standard coding practices”. Write prohibitions and conventions the agent cannot infer from the code. Do not write a tour of the codebase.

Which rules should a Lovable export carry?

Lovable's Git sync documentation says you can “clone that repository, edit the code with your own IDE or coding assistant, and push the result back”, one branch at a time. Every export has the same shape, and ours is no exception: this site's previous version was built in Lovable (the current one is Next.js, which is a story for the Lovable vs Cursor page). Reading that repository gives the non-standard facts a rule should state: Vite 5 with React 18 and TypeScript 5, Tailwind 3 and shadcn/ui with 49 generated primitives in src/components/ui, a lovable-tagger plugin in vite.config.ts, a dev server pinned to port 8080, a generated Supabase client and a 332-line types.ts under src/integrations/supabase whose first line reads “This file is automatically generated. Do not edit it directly”, 23 migrations and 12 edge functions under supabase/. Three rules cover it.

1. The project rule, always on

Conventions Cursor cannot infer plus the two Git rules from Lovable's docs, which warn: “Do not force-push, rebase, or squash commits that are already on the synced branch. Lovable keeps its own copy of that branch.”

---
description: Conventions of a project exported from Lovable (Vite, React, TypeScript, Tailwind, shadcn/ui, Supabase), synced two ways with GitHub.
globs:
alwaysApply: true
---
# Lovable export

- Stack: Vite 5, React 18, TypeScript 5, Tailwind 3, shadcn/ui, Supabase JS 2. "@/" maps to "src/".
- Never edit src/integrations/supabase/client.ts or types.ts. Both are generated and say so in their first line. Regenerate types after a migration instead.
- Schema changes are new files in supabase/migrations/, never edits to old ones. Enable RLS in the same migration (see supabase-rls).
- Server-side code lives in supabase/functions/<name>/index.ts and reads secrets with Deno.env.get(). Nothing secret goes under src/.
- src/components/ui/ is shadcn output. Compose new components in src/components/; do not hand-edit the primitives.
- Keep lovable-tagger in vite.config.ts and the dev server on port 8080; Lovable's preview expects both.
- Work on a feature branch. Never force-push, rebase or squash commits already on the synced branch: Lovable keeps its own copy and edits made only in Lovable can be lost.
- After a merge, the first prompt back in Lovable reads: "I changed [files] outside Lovable to [describe the change]."

2. The database rule, scoped to migrations and functions

Row-level security is where generated apps fail. Insufficient RLS in Lovable-generated projects has its own record, CVE-2025-48757, which Lovable disputes on the grounds that customers own their data protection; either way the policy has to be written, and a glob-scoped rule makes Cursor write it every time it touches supabase/. The verification-query habit comes from our build kits, whose schemas ship with the queries that proved their policies.

---
description: Row-level security for every table, and the rules for edge functions that touch data.
globs: supabase/migrations/**/*.sql, supabase/functions/**/*.ts
alwaysApply: false
---
# Database access

- Every "create table" is followed by "alter table ... enable row level security" and at least one policy, in the same migration file.
- Policies compare auth.uid() with an owner column or a membership table. Never "using (true)" on a table that holds user data.
- The service-role key is used only inside edge functions. It never appears under src/ or in a client bundle.
- Edge functions verify the caller's JWT before reading or writing and return 401 otherwise.
- After a migration, add two verification queries to the PR: one as the owner (expects rows) and one as a different user (expects zero rows).

3. The landing page rule, attached by description

The one rule most exports lack. It is the checklist behind every prompt on the landing page prompts page, reduced to five lines Cursor applies when it decides a marketing page is in play.

---
description: Copy and structure rules for landing pages, waitlists and any page a visitor sees before signing up. Use when editing marketing pages under src/pages.
globs:
alwaysApply: false
---
# Landing pages

- One offer and one primary action per page. Secondary links go in the footer.
- No invented proof. No placeholder testimonials, logos or user counts; leave a "proof pending" comment instead.
- Lead capture writes to an insert-only table and stores the UTM parameters from the URL.
- The file starts with a comment naming the traffic source the page was built for.
- The headline says what the product does in plain words. No superlatives.

Total: 39 lines across three files, all under the guidance by a wide margin, one Always Apply, one by glob, one by description. None describes the architecture, because Cursor can read it and the ETH result says the description would not help.

How do Cursor rules compare with Lovable knowledge, CLAUDE.md and AGENTS.md?

Every tool a Lovable builder touches has its own version of the same file. The mechanics rhyme; the limits and the scoping do not. Sources are the Cursor rules page, Lovable's knowledge documentation and Claude Code's memory documentation, all read on 26 September 2026.

The practical consequence for a builder who moves between Lovable and Cursor: the Lovable knowledge file and the Always Apply rule should say the same things, and the file-scoped rules have no Lovable equivalent, so they live only in the repo. If Claude Code is in the mix as well, the memory docs note it reads AGENTS.md “only when you have no CLAUDE.md in your working directory or above it”, which makes AGENTS.md the one file all three tools can share. Our Claude Code commands guide covers the skills side of that setup.

What goes wrong with Cursor rules, and how do you avoid it?

• The rule is a codebase tour. The ETH study found repository overviews “are not helpful” while instructions “are well followed”. Delete the paragraph that explains what the app does and keep the bullets that say what not to do.
• Every rule is attached to every file. 82% of the community rules use globs: **/*. Each one rides along on every request, which is how the cost the ETH study measured accrues, with none of the scoping the format offers. Set globs to the directory the rule is about.
• Vague guidance. The docs' own line is “Avoid vague guidance. Write rules like clear internal docs.” “Write clean code” changes nothing; “never using (true) on a table with user data” changes the migration.
• The rule pastes a file that then drifts. Only 4 of 498 public rules use @path. Reference the schema or the config; do not copy it.
• User Rules expected in Inline Edit. The docs are explicit that User Rules “are only used by Agent (Chat)”. A convention that must hold in Cmd+K edits goes in a project rule.
• Cursor edits break the Lovable sync. A rewrite of the synced branch is the failure Lovable's docs warn about by name. The Git lines in the project rule exist so the agent never proposes one. The rest of the sync workflow is on the app builder guide, and the mistakes that cost rebuild rounds on the Lovable side are on common mistakes.

Sources

All checked on 26 September 2026. Corpus numbers reproducible with scripts/measure-cursor-rules.mjs in the site repository.

• Cursor docs: Rules
• Gloaguen et al., Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (arXiv 2602.11988)
• Lovable docs: Knowledge
• Lovable docs: Sync your Lovable project code with GitHub, GitLab, or Bitbucket
• Claude Code docs: How Claude remembers your project
• CVE record: CVE-2025-48757 (MITRE)
• GitHub: PatrickJS/awesome-cursorrules
• GitHub: sanjeed5/awesome-cursor-rules-mdc