I Built a Linter for Cursor Rules (Because Nobody Knows If Theirs Are Working)

#webdev #ai #cursor #productivity

There are at least 10 threads on the Cursor forum asking the same question:

"How do I know if my .cursorrules are even being used?"

I counted. Here are a few:

".cursorrules not working - how to know if they are being used?"
"Cursor not following Rules"
"Rules not being applied automatically?"
"Cursor rules not working at all"

The answer is always the same: "Add a test marker like 'always start your response with 🦖' and see if it shows up."

That works, but it's a terrible developer experience. You shouldn't have to debug your config files by hiding easter eggs in your AI responses.

So I built a linter.

What It Does

npx cursor-doctor

That's it. No install, no config. It scans your project and tells you what's wrong:

🔍 cursor-doctor v1.1.1

Scanning /path/to/your/project...

.cursorrules
  ⚠ .cursorrules may be ignored in agent mode
    → Use .cursor/rules/*.mdc with alwaysApply: true

.cursor/rules/code.mdc
  ✗ Missing alwaysApply: true
    → Add alwaysApply: true to frontmatter for agent mode
  ⚠ Vague rule detected: "write clean code"
    → Make rules specific and verifiable

──────────────────────────────────────────────────
1 error, 2 warnings

Exit code 1 on errors, so it works in CI.

What It Catches

These are the actual mistakes that break rules, based on testing and forum complaints:

1. Using `.cursorrules` in Agent Mode

Agent mode ignores .cursorrules entirely. You need .cursor/rules/*.mdc files with alwaysApply: true in the frontmatter. The linter warns you if you're using the wrong format.

2. Missing `alwaysApply: true`

If your .mdc file doesn't have this in the frontmatter, it won't load in agent mode:

---
description: My coding standards
alwaysApply: true  # ← This is required
---

Most people skip it because the docs don't make it obvious. The linter catches it.

3. Vague Rules That Do Nothing

I tested 30+ rules with before/after comparisons. Rules like these don't change Cursor's output:

"Write clean code"
"Follow best practices"
"Be consistent"
"Use proper error handling"

Cursor already tries to do these things. Telling it to "write clean code" is like telling a chef to "make it taste good." The linter flags 20 known vague phrases.

4. Bad YAML Frontmatter

A syntax error in your frontmatter means the whole file fails to parse. The linter catches malformed YAML before Cursor silently ignores your rules.

5. Comma-Separated Globs

This is wrong:

globs: "*.ts, *.tsx"

It should be:

globs: ["*.ts", "*.tsx"]

The linter catches it.

Why I Built This

I spent way too much time debugging rules that weren't working. The failure mode is silent. Cursor doesn't tell you "hey, your rules file has a syntax error" or "this rule is too vague to act on." It just... doesn't follow them. And you're left wondering if you did something wrong or if Cursor is just being Cursor.

A linter solves this. Run it once, fix the errors, move on.

Limitations

This tool catches configuration mistakes: wrong file format, missing frontmatter, vague rules. It doesn't fix:

Cursor bugs where valid rules are ignored
Context window overflow pushing rules out
Model inconsistency between runs

Those are platform issues. But based on forum threads, a solid chunk of "my rules don't work" complaints are actually config mistakes that a linter would catch.