DEV Community

Ned C
Ned C

Posted on • Edited on

How to Lint Your Cursor Rules in CI (So Broken Rules Don't Ship)

#cursor #ai #devops #github

You write a .mdc rule. It looks fine. Cursor ignores it completely.

The problem is usually something small: a missing alwaysApply field, malformed YAML frontmatter, a glob pattern that doesn't match anything. You don't find out until you're mid-session and the AI does whatever it wants.

I built cursor-doctor to catch this stuff before it wastes your time. Here's how to run it locally and in CI.

What it catches

cursor-doctor checks for the things that silently break rules:

  • Missing or malformed YAML frontmatter in .mdc files
  • alwaysApply not set (agent mode won't load the rule)
  • Empty rule bodies (file exists but does nothing)
  • Invalid glob patterns in the globs field
  • .cursorrules files with issues that Cursor won't report

These aren't hypothetical. I tested each failure mode: malformed YAML and missing frontmatter both cause silent failures where Cursor loads zero rules and gives no error. (Full breakdown here)

Run it locally 

npx cursor-doctor
Enter fullscreen mode Exit fullscreen mode

That's it. It scans .cursorrules and .cursor/rules/*.mdc in your project directory. No config needed, no dependencies.

Output looks like this:

.cursor/rules/bad.mdc
  ✗ Missing YAML frontmatter
    → Add --- block with description and alwaysApply: true

.cursor/rules/typescript.mdc
  ✓ All checks passed

1 error, 1 passed
Enter fullscreen mode Exit fullscreen mode

You can also verify a single file:

npx cursor-doctor --verify .cursor/rules/typescript.mdc
Enter fullscreen mode Exit fullscreen mode

Or generate a starter rule:

npx cursor-doctor --init typescript
Enter fullscreen mode Exit fullscreen mode

Add it to CI

If your team shares Cursor rules in the repo, broken rules can ship with any PR. The cursor-doctor GitHub Action runs the linter on every push and PR:

# .github/workflows/lint-cursor-rules.yml
name: Lint Cursor Rules
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: nedcodes-ok/cursor-lint-action@v1
Enter fullscreen mode Exit fullscreen mode

That's the whole workflow file. It fails the check if any rule has issues, so broken .mdc files don't merge.

When this matters

If you're working solo, npx cursor-doctor before committing is probably enough.

If your team checks in .cursor/rules/ (which you should, if you want consistent AI behavior across the team), CI linting prevents the "works on my machine" problem where someone's rule edit breaks the frontmatter and nobody notices for a week.

It also catches the common case where someone copies a .cursorrules example from the internet that's missing alwaysApply: true. Without that field, agent mode won't load it. The file just sits there doing nothing.

Links

If your team's rules are a mess and you want someone to sort it out: I do $50 async setup audits. You send your files, I send back a report with exactly what to fix. Code FIRSTAUDIT for 20% off.

📋 I made a free Cursor Safety Checklist — a pre-flight checklist for AI-assisted coding sessions, based on actual experiments.

Get it free →

Top comments (0)