I ran cursor-doctor on 50 real projects. Here's what broke.

Source: Dev.to

I wanted to know how healthy Cursor rules are in the wild—outside of tutorials and curated examples, in real GitHub repositories that ship code.

Study Overview

• Cloned 50 random public repos that use Cursor rules.
• Ran npx cursor-doctor scan on each.

Grade Distribution

• Average health score: 67 %
• Median score: 69 % (Grade C)

Only 3 out of 50 projects achieved a healthy score (A).

Deep Dive (15 projects, 998 issues)

1. Overly Long Rules

• ~15 % of issues were rules > 2,000 characters (some > 5,000).
• Each long rule consumes 500–1,250 tokens before Cursor even reads the code.
• Example: one project had 12 rules averaging 4,000 characters → ~12,000 tokens of instructions alone.

Fix:

• Split long rules into focused, shorter ones.
• Remove repetitive parts.
• Limit examples to one or two instead of many.

2. Empty globs Arrays

Rules with a description and instructions but globs: [] leave Cursor unsure which files to apply to.

description: "React component standards"
globs: []

Fix:

• Add an appropriate glob pattern (e.g., **/*.tsx).
• Or set alwaysApply: true if the rule should apply everywhere.

3. Weak Language

Instructions that use tentative wording give the model permission to ignore them.

• Weak: "Try to keep functions small." / "Consider using TypeScript." / "Maybe add error handling."
• Strong: "All new files must use TypeScript. No .js files except config files in the project root."

Fix:

• Use definitive statements without “try,” “consider,” or “maybe.”

4. Commented‑Out Sections & TODOs

Comments and notes consume tokens and confuse the model about what constitutes a rule.

Fix:

• Delete commented‑out rules. Rules are not source code; keep only the active version.

5. Missing Frontmatter or Description

• 28 projects had rules without a description.
• 20 projects lacked YAML frontmatter entirely, preventing proper categorization.

A properly formatted rule file needs at minimum:

---
description: Enforces consistent error handling in API routes
globs: "src/api/**/*.ts"
---
All API route handlers must wrap their body in a try/catch block.
Return a 500 status with a generic error message. Log the full error to the server console.

Characteristics of High‑Scoring Projects (Grade A)

• Short, focused rules: ≤ 1,000 characters, one concern per file.
• Correct frontmatter: Every rule includes a description, appropriate globs, and explicit alwaysApply settings when needed.
• Concrete instructions: No tentative language; direct statements with clear examples.
• No dead weight: No commented code, TODOs, or redundant instructions.

Using cursor-doctor

• Quick health check (≈2 seconds):

  npx cursor-doctor scan

  Returns a grade (A–F) and a list of fixes.

• Detailed issue breakdown (file by file):

  npx cursor-doctor lint

Availability

• Repository:
• Also available as a VS Code and Cursor extension with inline diagnostics.