DEV Community: Ned C

How to vet Cursor rules before using them

Ned C — Thu, 05 Mar 2026 22:58:59 +0000

You're browsing awesome-cursorrules, or someone shared a .cursorrules file in Discord, or you found a repo on GitHub with rules that look perfect for your stack.

Before you copy it into .cursor/rules/, check if it actually works. Most community rules have at least one critical issue. Some are completely broken.

I grabbed 4 popular rule sets from awesome-cursorrules and ran them through a linter. 100% were missing frontmatter. 75% were too long. 50% used vague language that Cursor ignores. They're good starting points, but none of them work correctly out of the box.

Here's the checklist i use before adopting any rule set i find online.

the 5-point vetting checklist

Quick version:

✓ Does it have YAML frontmatter? (description, alwaysApply or globs)
✓ Is the body under 2000 characters?
✓ Does it cover one concern, not five?
✓ Are instructions specific and imperative?
✓ Does it conflict with your existing rules?

If any of these fail, the rule either won't work at all, will waste your context window, or will confuse Cursor into ignoring you. Let's go through each one.

check 1: does it have YAML frontmatter?

What to look for: A block at the top of the file between --- markers with at least description and either alwaysApply or globs.

Why it matters: Without frontmatter, Cursor doesn't know when to activate the rule, which files it applies to, or how to prioritize it. The rule might load unpredictably or never load at all.

❌ No frontmatter (won't work):

Next.js 15, React 19, TypeScript best practices.

Code Style and Structure
- Write concise TypeScript code with accurate examples.

✅ Has proper frontmatter:

---
description: Next.js + React + TypeScript best practices
globs:
  - "**/*.ts"
  - "**/*.tsx"
  - "app/**/*"
alwaysApply: false
---

Code Style and Structure
- Write concise TypeScript code with accurate examples.

What to do: If there's no frontmatter, add it. If you want the rule to apply everywhere, use alwaysApply: true. If you want it scoped to specific files, use globs with patterns like **/*.tsx.

Real data: All 4 rule sets i tested from awesome-cursorrules were missing frontmatter entirely. This was the #1 issue.

check 2: is it under 2000 characters?

What to look for: Open the file in your editor. Check the character count or line count. If it's over 2000 characters (roughly 500+ tokens), it's probably too long.

Why it matters: Every rule with alwaysApply: true gets loaded into Cursor's context window on every request. Long rules waste tokens that could be used for your actual code. One 4,000-character rule burns ~1,100 tokens every time it loads.

What to do: Split long rules into focused ones. If a rule covers "naming conventions, error handling, and file structure," make three separate files: naming.mdc, errors.mdc, structure.mdc. Use globs to scope each one.

Real data:

3 out of 4 rule sets i tested were over 2000 chars
Longest was 3,914 bytes (~1,077 tokens)

Pro tip: If a rule file has more than 50 lines, it's probably mixing concerns.

check 3: does it mix concerns?

What to look for: Read through the instructions. Does it cover naming conventions, types, architecture, styling, and error handling all in one file? That's five different rules pretending to be one.

Why it matters: When a rule tries to do everything, Cursor struggles to apply it correctly. One file covering "use camelCase for variables" and "implement error boundaries" and "structure components as feature folders" is confusing. Each instruction competes for attention.

What to do: One rule, one concern. If you see multiple topics, split the file.

❌ Mixing concerns:

---
description: React standards
globs: ["src/**/*.tsx"]
---

Use PascalCase for components.
Use camelCase for variables.
Wrap route components in error boundaries.
Keep components under 50 lines.
Use CSS modules for styling.
Store reusable logic in hooks/.

✅ Focused on one concern:

// naming.mdc
---
description: React component and variable naming
globs: ["src/**/*.tsx"]
---
Use PascalCase for components.
Use camelCase for variables and functions.

// error-handling.mdc
---
description: Error boundaries for route components
globs: ["src/app/**/*.tsx", "src/pages/**/*.tsx"]
---
Wrap every route-level component in an error boundary.
Provide a fallback UI with a retry button.

Real data: 3 out of 4 rule sets i tested mixed multiple concerns in one file. This makes rules harder to scope with globs and burns tokens on instructions that don't apply to the current file.

check 4: is the language specific?

What to look for: Scan for phrases like "try to," "consider," "you might want to," "follow best practices," "write clean code."

Why it matters: AI models follow imperative commands better than suggestions. "Try to keep functions small" gives Cursor permission to ignore you. "Keep functions under 20 lines, extract helpers for longer logic" is a concrete instruction.

❌ Vague language:

Consider using functional components.
Try to keep functions small.
It's recommended to handle errors properly.
Follow React best practices.

✅ Specific language:

Use functional components with hooks. No class components.
Keep functions under 20 lines. Extract helpers for longer logic.
Wrap all async route handlers in try-catch blocks.
Prefix custom hooks with "use". Prefix utility functions with the module name.

What to do: Replace every "try to" with a direct command. Replace "follow best practices" with the actual practice. Replace "write clean code" with measurable rules like "max 20 lines per function."

Real data: 2 out of 4 rule sets i tested used weak language like "consider" or "try to." These instructions don't change model behavior. They just waste tokens.

check 5: does it conflict with your existing rules?

What to look for: If you already have rules in .cursor/rules/, check for contradictions. Does the new rule say "use semicolons" while your existing rule says "omit semicolons"? Does it say "use double quotes" while you enforce single quotes?

Why it matters: When two rules contradict each other, Cursor picks one unpredictably. You won't get a warning. The AI will just follow whichever rule it loaded first or weighted higher.

What to do: Before adding a new rule, run npx cursor-doctor lint to check for conflicts. If you find one, either delete the conflicting instruction from the new rule or remove the old rule entirely.

Pro tip: This is the hardest check to do manually. Automated linting catches conflicts you'd never spot by reading.

the automated way (10 seconds)

You can check all five of these manually, or you can run one command:

npx cursor-doctor lint

It scans every .mdc file in your project and flags:

Missing or malformed frontmatter
Rules over 2000 characters
Vague language patterns ("try to", "consider", "best practices")
Conflicting instructions between rules (48 semantic patterns)
Empty globs arrays
Windows-style backslashes in globs
YAML syntax errors and boolean strings
100+ other checks

Before you paste a rule you found online, save it to .cursor/rules/test-rule.mdc and run the linter. Fix what it flags, then decide if it's worth keeping.

real example: vetting a rule from awesome-cursorrules

I grabbed the Next.js + React + TypeScript + Tailwind rule from awesome-cursorrules. Here's what cursor-doctor found:

cursor-doctor v1.10.24 -- lint

nextjs-react-tailwind.mdc  (3 warnings)
  ⚠ Missing YAML frontmatter
    → Add description, alwaysApply or globs so Cursor knows
      when to load this rule.
  ⚠ Rule body is very long (3,914 bytes)
    → Shorter, specific rules outperform long generic ones.
      Consider splitting into focused rules.
  ⚠ Rule uses weak language: "try to/maybe/consider"
    → AI models follow commands better than suggestions. Use
      imperative mood: "Do X" instead of "try to do X".

──────────────────────────────────────────────────
3 warnings, 0 passed

Three warnings from one file. And that's just what the linter catches automatically. Reading through the rule manually, i also noticed it mixes naming conventions, architecture patterns, and styling rules all in one file.

After fixing the frontmatter, splitting it into 3 focused rules, and replacing vague language with concrete commands, it passed with no warnings.

when to skip a rule entirely

Some rules aren't worth fixing. Skip the rule if:

It's over 5,000 characters. That's 1,250+ tokens. Not worth it.
It starts with "You are an expert in..." These preambles waste 10-15 tokens and don't improve output.
It's mostly examples. One or two examples are fine. Eight examples are token waste.
It uses JavaScript/JSON syntax instead of markdown. Cursor reads markdown, not code.
It's a list of technologies with no actual instructions. "Next.js 15, React 19, TypeScript, Tailwind" tells Cursor nothing.

If more than half the file is noise, don't bother. Write your own rule from scratch.

rules worth using without modification

A few patterns i've found that usually work out of the box:

Rules under 1,000 characters with proper frontmatter
Rules scoped to a specific framework or library (e.g., "Svelte component conventions")
Rules that provide concrete examples for complex patterns (e.g., "How to structure tRPC routers")
Rules with clear, imperative language and no fluff

These are rare. Most rules need at least some cleanup.

frequently asked questions

How do i know if a Cursor rule set is good?

Check five things: (1) Does it have YAML frontmatter with description, alwaysApply, and globs? (2) Is the body under 2000 characters? (3) Does it cover one concern, not multiple? (4) Are instructions specific and imperative, not vague? (5) Does it conflict with your existing rules? You can check all five automatically with npx cursor-doctor lint.

What's wrong with rules from awesome-cursorrules?

When i tested 4 popular rule sets from awesome-cursorrules, 100% were missing YAML frontmatter, 75% were too long and wasted tokens, 75% mixed multiple concerns in one file, and 50% used weak language like "consider" or "try to." They're good starting points but need fixing before use.

How long should a Cursor rule be?

Under 2000 characters. Rules longer than 2000 chars burn 500+ tokens every time they load. If your rule is longer, split it into multiple focused rules with specific globs instead of one mega-rule with alwaysApply: true.

Should i use alwaysApply true or globs?

Use globs to scope rules to specific file types. Reserve alwaysApply: true for universal rules that apply to every file, like "no console.log in production." Most rules should use globs to avoid wasting tokens on files where the rule doesn't apply.

Can i trust rules from GitHub repos?

Most public Cursor rules have at least one issue. I scanned 50 real GitHub projects and found that 60% had a health score of C or lower. Always run cursor-doctor lint on any rule you find before using it.

Vet your rules in 10 seconds:

npx cursor-doctor lint

Or paste a single rule into the playground for instant feedback.

Full documentation




---

## Success Criteria Verification

✅ **Clearly different from the 50-projects article** (checklist format vs survey format)  
✅ **Actionable** (reader can vet rules after reading with 5-point checklist)  
✅ **Uses research data as supporting evidence** (stats cited as "Real data:" not main story)  
✅ **SEO optimized** (keywords, structured data, FAQPage schema, canonical URL)  
✅ **Lowercase headers** (all headers follow style guide)  
✅ **No em dashes** (used commas, periods, restructured)  
✅ **No buzzwords** (no "game-changer", "deep dive", "level up", etc.)  
✅ **No praise openers** (starts with problem statement)  
✅ **First person, casual** ("i grabbed", "i tested", "here's what")  
✅ **Every claim sourced** (research data cited with specific numbers)  
✅ **No dropped subjects** (all sentences have explicit subjects)  
✅ **Both HTML and Dev.to versions** (separated clearly in output file)

---

## Data Sources

All stats and claims trace to `scratch/overnight/rules-scan-article-result.md`:
- "100% were missing frontmatter" → All 4 rule sets in scan had no YAML frontmatter
- "75% were too long" → 3 out of 4 exceeded 2000 chars
- "75% mixed concerns" → 3 out of 4 flagged for multiple concerns
- "50% used weak language" → 2 out of 4 flagged for weak language
- "3,914 bytes (~1,077 tokens)" → Next.js React Tailwind rule size from scan
- "60% scored C or lower" → Referenced from 50-projects article data

---

**Status:** ✅ COMPLETE  
**Output Location:** `scratch/overnight/vet-cursor-rules-article.md` (this file)  
**Completion Time:** 2026-03-04 12:21 EST

cursor-doctor v1.10: coverage gaps and README badges

Ned C — Wed, 04 Mar 2026 18:08:00 +0000

what's new

I just shipped two features for cursor-doctor. One tells you what your rules are missing. The other gives you a badge to show off your health grade.

coverage gap detection (v1.10.25)

You have rules. But do they cover what matters?

cursor-doctor now scans your package.json or requirements.txt to detect your stack, then checks if your rules cover the categories that matter for that stack. Testing, error handling, accessibility, API patterns, security, performance.

Here's what it looks like:

npx cursor-doctor scan

  ▒▒ Cursor Health: A ▒▒

  █████████████████████████████░  98%

  ✓ Rules exist
  ✓ Rule syntax
  ✓ Token budget
  ✓ Coverage
  ✓ File sizes

  7 passed  

  ▓ Coverage Report

  Detected:  react, nextjs
  Covered:   styling
  Missing:   testing, error-handling, state-management, 
             accessibility, performance, api-data-fetching, 
             security

  Suggestions:
    • testing: Testing rules help maintain code quality 
      and catch bugs early
    • error-handling: Error handling rules ensure robust 
      error management
    • state-management: State management rules prevent 
      common pitfalls
    ... and 4 more

If you're building a React app with no testing rules, it tells you. If you're running Next.js with no API or security rules, it flags that. If you have 12 styling rules but nothing about error handling, you'll see it.

The suggestions are specific to your stack. A Django project gets different recommendations than a React app. A Rust project won't get nagged about CSS.

README badge generator (v1.10.26)

Your Cursor rules have a health grade. Now you can show it.

npx cursor-doctor badge

Output:

cursor-doctor v1.10.26 -- badge generator

Markdown:
  ![Cursor Rules: A (98%)](https://img.shields.io/badge/Cursor%20Rules-A%20(98%25)-brightgreen)

HTML:
  <img src="https://img.shields.io/badge/Cursor%20Rules-A%20(98%25)-brightgreen" alt="Cursor Rules: A (98%)">

Dynamic Badge (shields.io endpoint JSON):
  Save this JSON to your repo and reference it:
  npx cursor-doctor badge --json > cursor-rules-badge.json
  https://img.shields.io/endpoint?url=https://yourrepo/cursor-rules-badge.json

Copy the markdown snippet and paste it in your README. The badge shows your grade (A through F) with color coding. Green for A, yellow for C, red for F.

The badge is static by default. It shows the grade at the time you ran the command. If you want a dynamic badge that updates automatically, use the --json flag to generate a shields.io endpoint file, commit it to your repo, and reference it in your README.

why this matters

Most Cursor rules are written once and never looked at again. You add a rule for React hooks. Then you add Express. Then you add auth logic. The rules grow organically, and gaps emerge.

Coverage gap detection surfaces those gaps. It's not about telling you to write more rules. It's about telling you which rules would actually help.

The badge is a forcing function. If you put it in your README, you'll see when your health grade drops. If you're sharing rules with your team or in open source, it's a signal that someone is paying attention.

try it

Both features are free and available now:

npx cursor-doctor scan    # see coverage gaps
npx cursor-doctor badge   # generate badge snippets

If you find issues in your rules, the Pro version has 34 auto-fixers. $9 one-time at nedcodes.gumroad.com/l/cursor-doctor-pro. If it doesn't find real, fixable problems, email hello@nedcodes.dev for a refund.

Full docs: github.com/nedcodes-ok/cursor-doctor

Add cursor-doctor to your CI pipeline in 2 minutes

Ned C — Wed, 04 Mar 2026 16:55:07 +0000

i built cursor-doctor after watching teams waste hours debugging Cursor rules that "stopped working." The problem is always the same: someone added a rule with broken YAML frontmatter, or two rules contradicted each other, or a glob pattern had a typo. Cursor doesn't warn you. The rule silently fails.

Here's how to catch that in CI.

tl;dr

Add this to .github/workflows/cursor-rules.yml:

- uses: nedcodes-ok/cursor-doctor@v1

Every PR now checks your Cursor rules for errors before merge.

GitHub Actions setup

Create .github/workflows/cursor-rules.yml:

name: Cursor Rules Health Check

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint-cursor-rules:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: nedcodes-ok/cursor-doctor@v1

If cursor-doctor finds issues, the workflow fails and the PR can't merge.

The action handles Node.js setup automatically. No setup-node step needed.

action inputs

Two optional inputs:

- uses: nedcodes-ok/cursor-doctor@v1
  with:
    path: './my-project'       # Path to scan (default: '.')
    fail-on-warning: 'true'    # Fail on warnings too (default: 'false')

only run when rules change

Save CI minutes with a paths filter:

on:
  push:
    branches: [main]
    paths:
      - '.cursor/rules/**'
      - '.cursorrules'
      - 'CLAUDE.md'
      - 'AGENTS.md'
  pull_request:
    branches: [main]
    paths:
      - '.cursor/rules/**'
      - '.cursorrules'
      - 'CLAUDE.md'
      - 'AGENTS.md'

what the output looks like

Here's actual output from cursor-doctor lint on a project with a few issues:

cursor-doctor v1.10.24 -- lint

.cursor/rules/testing.mdc  (3 warnings)
  ⚠ Vague rule detected: "follow best practices" (line 5)
    → Replace with a specific instruction. Say exactly what
      to do: what tool, what pattern, what format.
  ⚠ Description is very short (<10 chars)
    → A descriptive description helps Cursor decide when to
      apply this rule.
  ⚠ Description is identical to filename
    → Describe what the rule does, not just repeat the filename.

.cursor/rules/types.mdc  (1 warning, 1 info)
  ⚠ Rule uses weak language: "try to/maybe/consider"
    → AI models follow commands better than suggestions. Use
      imperative mood: "Do X" instead of "try to do X".

──────────────────────────────────────────────────
4 warnings, 1 info, 1 passed

The check command (default in CI) gives a pass/fail health grade. Grades D and F fail the build.

pre-commit hook

Catch issues before you even push. Create .git/hooks/pre-commit:

#!/usr/bin/env bash

STAGED=$(git diff --cached --name-only --diff-filter=ACM \
  | grep -E '\.mdc$|\.cursorrules$|CLAUDE\.md$|AGENTS\.md$')

if [ -z "$STAGED" ]; then
  exit 0
fi

echo "cursor-doctor: checking staged rule files..."
npx cursor-doctor check
exit $?

Then chmod +x .git/hooks/pre-commit. The hook only runs when you stage rule files.

what it catches

Frontmatter errors: Missing YAML blocks, parse errors, alwaysApply: "true" (string instead of boolean, rule never activates).

Glob mistakes: Windows backslashes that match nothing, typos in extensions, overly broad patterns.

Semantic conflicts: "Use semicolons" vs "omit semicolons." cursor-doctor checks 48 conflict patterns across formatting, imports, error handling, and state management.

Vague instructions: "Write clean code" and "follow best practices" waste tokens without changing model behavior.

Token budget waste: Too many alwaysApply rules burning context window, duplicate content across files, dead rules nobody references.

other CI platforms

The GitHub Action runs npx cursor-doctor check under the hood. Use the same command anywhere:

GitLab CI:

lint-cursor-rules:
  image: node:20
  script:
    - npx cursor-doctor check
  only:
    - merge_requests
    - main

CircleCI:

version: 2.1
jobs:
  lint-cursor-rules:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run: npx cursor-doctor check
workflows:
  check-rules:
    jobs:
      - lint-cursor-rules

Exit code 0 = healthy. Exit code 1 = issues found.

testing locally

Run the same check CI will run:

npx cursor-doctor check

For the detailed breakdown:

npx cursor-doctor lint

Fix issues, push, CI passes on the first try.

npx cursor-doctor fix --preview shows available auto-fixes. Many issues can be fixed automatically. First fix is free.

cursor-doctor on GitHub · Full guide on nedcodes.dev

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

Ned C — Tue, 03 Mar 2026 19:02:52 +0000

I wanted to know: how healthy are Cursor rules in the wild? Not in tutorials or curated examples, but in real GitHub repos where people are actually shipping code.

So I cloned 50 random public repos that use Cursor rules and ran npx cursor-doctor scan on every one of them.

The results: 60% of projects scored a C

A:  3 ███                          (6%)
B: 15 ███████████████              (30%)
C: 30 ██████████████████████████████ (60%)
D:  2 ██                           (4%)

Average health score: 67%. Only 3 out of 50 projects had healthy Cursor rules. The median project scored 69%, which is a C. That means most Cursor setups have enough issues to noticeably affect how well the AI follows instructions.

I dug deeper into 15 of those projects and categorized every issue cursor-doctor flagged. 998 total issues. Here are the five problems that kept showing up.

1. Rules that eat your context window (146 issues)

This was the single most common problem. Nearly 15% of all issues were rules that are too long.

Rules with 2,000+ characters each. Some over 5,000. Each one burns 500 to 1,250 tokens of your context window before Cursor even reads your code.

One project had 12 rules averaging 4,000 characters each. That is roughly 12,000 tokens of instructions alone, leaving less room for the code Cursor needs to work with.

The fix: Split long rules into focused ones. Remove the parts that repeat what Cursor already knows. Cut examples down to one or two instead of eight.

2. Rules that target nothing (36 issues)

Empty globs arrays. The rule exists, has a description, has instructions, but the globs field is []. Cursor doesn't know which files the rule applies to.

---
description: "React component standards"
globs: []
---

The fix: Add the right glob pattern (**/*.tsx) or set alwaysApply: true if the rule should apply everywhere.

3. Vague instructions Cursor ignores (27 issues)

"Try to keep functions small." "Consider using TypeScript." "Maybe add error handling."

Cursor doesn't try, consider, or maybe. It either follows the instruction or it doesn't. Weak language gives the model permission to ignore you.

Compare: "Try to use TypeScript" vs "All new files must use TypeScript. No .js files except config files in the project root."

4. Dead code burning tokens (32 issues)

Commented-out sections, TODO markers, notes-to-self. These all consume tokens and confuse the model about what is actually a rule and what is a draft.

<!-- TODO: add React rules later -->
<!-- OLD: use class components -->

If it is commented out, delete it. Rules are not source code. There is no reason to keep old versions around.

5. Missing or broken frontmatter (48 issues)

28 projects had rules with no description. 20 had rules with no YAML frontmatter at all. Without frontmatter, Cursor cannot properly categorize or prioritize the rule. Without a description, you have no idea what the rule does when you revisit your setup six months later.

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.

What the healthy projects did differently

The 3 projects that scored an A had a few things in common:

Short, focused rules. One concern per file. Under 1,000 characters each.
Correct frontmatter. Every rule had a description, appropriate globs, and explicit alwaysApply settings.
Concrete instructions. No "try to" or "consider." Direct statements with examples.
No dead weight. No commented code, no TODOs, no redundant instructions.

Check your own Cursor rules

npx cursor-doctor scan

Takes about 2 seconds. Gives you a health grade from A through F and tells you exactly what to fix. The scan and lint commands are free, no install needed.

For a detailed breakdown of every issue, file by file:

npx cursor-doctor lint

cursor-doctor on GitHub

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

I Fed My Entire Codebase to Gemini. It Wrote Better Cursor Rules Than I Did.

Ned C — Sat, 28 Feb 2026 14:03:03 +0000

This is a submission for the Built with Google Gemini: Writing Challenge

Most AI rule generators read your package.json and spit out generic templates. "Use TypeScript strict mode." "Follow REST conventions." Thanks, I already knew that.

I wanted something that actually reads code. Not config files, not dependency lists. The actual source files where patterns live. So I built rule-gen, a CLI that feeds your codebase into Gemini and generates coding rules based on what it finds.

The entire thing runs on a Raspberry Pi. Zero dependencies. Free Gemini API tier.

What I Built

rule-gen is a Node.js CLI. You point it at a project directory, it scans your source files, sends them to Gemini, and writes rules in whatever format your AI coding assistant uses.

$ npx rulegen-ai ./my-project

Scanning ./my-project...
  Found 13 files
  Selected 13 files for analysis
  Estimated tokens: ~8,346

Generating rules with gemini-2.5-flash...
  API usage: 11,233 input, 1,699 output tokens
  Generated 8 rules

Written 8 files:
  ✓ .cursor/rules/cli-command-structure.mdc
  ✓ .cursor/rules/new-parser-module-structure.mdc
  ✓ .cursor/rules/new-format-converter-module-structure.mdc
  ✓ .cursor/rules/rule-object-structure.mdc
  ✓ .cursor/rules/error-message-convention.mdc
  ✓ .cursor/rules/single-file-parser-convention.mdc
  ✓ .cursor/rules/cursor-output-directory.mdc
  ✓ .cursor/rules/scoping-loss-warning-convention.mdc

It supports five output formats:

Format	Flag	Output File
Cursor	`--format cursor`	`.cursor/rules/*.mdc`
Claude Code	`--format claude-md`	`CLAUDE.md`
Claude Agents	`--format agents-md`	`AGENTS.md`
GitHub Copilot	`--format copilot`	`.github/copilot-instructions.md`
Windsurf	`--format windsurf`	`.windsurfrules`

The whole thing is about 750 lines across five modules (scanner, budgeter, Gemini client, prompt + parser, writer). No SDK, no node_modules. Just node:https, node:fs, and node:path.

Why Gemini

This is the part where the 1M token context window actually matters.

I looked at existing rule generators before building this. They all do static analysis: read your package.json, check for a tsconfig.json, maybe peek at your directory structure. Then they match against a template library. "You have React? Here's the React rules." That's fine if you want generic framework guidance, but it misses everything specific to YOUR codebase.

Gemini lets me send the actual source files. Not a summary, not an AST. The raw code. For a typical project (15-50 files, ~40K tokens), that's a fraction of the context window. The model reads every file and identifies patterns that span across modules.

Here's a rule it generated for one of my projects:

---
description: New parser modules must be placed in src/parsers/ and export a discover function.
globs: ["src/parsers/**/*.js"]
alwaysApply: false
---

# New Parser Module Structure

Any new parser module must reside within the `src/parsers/` directory. 
Each parser file should export a single `discover(dir)` function.
This function takes the current working directory as its sole argument.
If no relevant file is found, the function should return `null`.
If rules are found, it must return an object with `rules` (array) 
and `skipped` (array of objects with `file` and `reason`).

That rule references actual directory paths, actual function signatures, and actual return types from my code. No template library produces that.

What I Learned

Prompt engineering is 90% of the work

The scanner and writer took maybe an hour each. The prompt went through four rewrites over two days.

My first attempt asked Gemini to "analyze this codebase and generate rules." It came back with 75 rules. Most of them were documentation-style summaries of what each function does, which is useless as a coding rule.

The fix was reframing the task. Instead of "generate rules for this codebase," I needed "write rules that tell an AI coding assistant how to write NEW code in this project." That distinction matters. The model needs to think about what a new developer would get wrong, not what the existing code does.

I also learned that constraints placed AFTER the code files work better than constraints placed before. The model pays more attention to the last thing it reads, especially with long contexts. Moving "generate exactly 5-8 rules" to the end of the prompt (after all the source files) made the difference between 75 rules and 7.

Structured output changes everything

I initially built a text parser to extract rules from Gemini's free-form response. It worked, but the model kept switching formats between runs. Sometimes YAML frontmatter, sometimes markdown bold headers, sometimes a mix.

Switching to Gemini's structured output mode (responseSchema) solved this completely AND made the API calls faster. The thinking model (gemini-2.5-flash) went from 4+ minutes to 24 seconds on the same 52K token input. My guess is the model spends less time on formatting tokens when it knows the exact output schema.

The lesson: if you need structured data from an LLM, don't parse text. Use the API's native structured output.

Post-processing is your safety net

Even with a good prompt, I couldn't guarantee the model would output exactly the right number of rules or use exactly the right format every time. So I added:

A hard cap at 8 rules (truncate if the model overproduces)
A fallback parser that handles both YAML frontmatter and markdown-style output
Filename generation from rule titles

This isn't glamorous, but it's what makes the tool actually reliable. You can't ship a CLI that works 80% of the time.

Gemini Feedback (The Honest Version)

What worked well:

The context window is the killer feature. Being able to send 50 source files in a single request, with no chunking or RAG pipeline, made the architecture dead simple. One prompt, one API call, done. I didn't need to build any summarization, embedding, or multi-step chain. That simplicity is directly because of the 1M token limit.

The free tier is genuinely usable. I built and tested the entire tool without spending a cent on API calls. For a tool that generates 5-8 rules per run using ~50K tokens of input, the free tier rate limits never became an issue.

gemini-2.5-flash is fast enough to run on a Raspberry Pi. 24 seconds for a 52K token codebase. I expected to need a more powerful machine for development, but even the Pi 5 handles it fine.

What didn't work great (and how I fixed it):

My first approach was free-form text output: ask the model to generate rules in a specific YAML format, then parse the text. flash-lite didn't follow structural constraints reliably. "Output exactly 5-8 rules in this YAML format" sometimes became "here's 12 rules in markdown with bold headers." I built a robust fallback parser, but it felt brittle.

Then I discovered Gemini's structured output mode (responseMimeType: "application/json" with a responseSchema). I defined a JSON schema for the rule format and the model returns valid, parseable JSON every time. No text parsing needed. This also made the thinking model (gemini-2.5-flash) dramatically faster, dropping from 4+ minutes to 24 seconds on the same input, probably because it doesn't waste tokens on formatting.

If you're building anything with Gemini that needs structured data back, skip the text-parsing approach and go straight to responseSchema. It saved me an entire class of bugs.

The Ecosystem

rule-gen fits into a pipeline I've been building:

rule-gen generates rules from your codebase
cursor-doctor validates and fixes those rules
rule-porter converts them between formats

Generate, validate, convert. Three tools, zero dependencies each, all on npm.

Try It

export GEMINI_API_KEY=your-key   # free at aistudio.google.com/apikey
npx rulegen-ai ./your-project

It takes about 20-30 seconds. The rules it generates will be specific to your codebase, not generic templates.

GitHub repo | npm | nedcodes.dev

rule-porter: Convert Cursor rules to CLAUDE.md, AGENTS.md, and Copilot

Ned C — Fri, 27 Feb 2026 20:54:59 +0000

This is a submission for the DEV Weekend Challenge: Community

The Community

Cursor AI users who also use Claude Code, GitHub Copilot, or any combination of AI coding tools.

Right now, if you've invested time writing good .mdc rules in Cursor, those rules are locked in. Cursor uses its own format with YAML frontmatter, glob patterns, and alwaysApply flags. None of that translates to Claude Code's CLAUDE.md, Copilot's .github/copilot-instructions.md, or the AGENTS.md format.

People switching between tools (or using more than one) have to manually rewrite everything. I know because someone told me so directly. Matthew Hou left a comment on my cursor-doctor launch post asking:

Have you thought about an export/convert feature? Something that could take validated Cursor rules and output an equivalent AGENTS.md or CLAUDE.md?

That comment kicked this off.

What I Built

rule-porter is a zero-dependency CLI that reads your .cursor/rules/ directory and converts every .mdc file into the format your target tool expects.

Three target formats:

AGENTS.md (global vs conditional sections, glob patterns preserved as comments)
CLAUDE.md (flat markdown with file-specific rules separated)
.github/copilot-instructions.md (merged flat markdown)

It auto-detects your Cursor rules, handles edge cases (empty files, broken frontmatter, missing body content), and warns you about anything that can't convert cleanly. Glob patterns and alwaysApply flags don't have equivalents in flat markdown formats, so rule-porter keeps them as human-readable annotations and tells you exactly what was lost.

npx rule-porter --to agents-md

That's it. No install, no config, no dependencies.

Demo

Here's rule-porter running against a real project with 6 Cursor rules (a Chrome extension with TypeScript, i18n, and UI rules):

  rule-porter v1.2.0

  Source:  .cursor/rules/ (6 rules)
  Target:  AGENTS.md

  ✓ 1 global  5 conditional

  Warnings:
  ⚠  comment: Glob pattern "*.tsx, *.js, *.ts" converted to comment.
     AGENTS.md has no native file scoping.
  ⚠  i18n: Glob pattern "locales/**/*.json" converted to comment.
     AGENTS.md has no native file scoping.
  ⚠  typescript: Glob pattern "*.tsx" converted to comment.
     AGENTS.md has no native file scoping.
  ⚠  ui: Glob pattern "*.tsx" converted to comment.
     AGENTS.md has no native file scoping.
  ⚠  ai: No glob pattern and not alwaysApply.
     This was a manual-attach rule in Cursor — review placement.

  ✓ Written to AGENTS.md

  6 rules converted · 5 warnings

The output preserves your rule structure:

# AGENTS.md

> Generated by rule-porter from .cursor/rules/

## Global Rules

### Chrome extension development standards

You are an expert Chrome extension developer...
[full rule body preserved]

## Conditional Rules

### i18n, internationalization, translation

*Applies to: `locales/**/*.json`*

Internationalization (i18n) Guidelines:
[full rule body preserved]

Global rules (ones marked alwaysApply: true in Cursor) get their own section. Conditional rules keep their glob patterns as readable annotations. Code blocks, markdown formatting, even non-English content all come through intact.

--dry-run lets you preview without writing anything:

npx rule-porter --to claude-md --dry-run

Code

nedcodes-ok / rule-porter

Convert AI IDE rules between Cursor, Windsurf, CLAUDE.md, AGENTS.md, and Copilot. Bidirectional. Zero dependencies.

rule-porter

Switch AI editors without rewriting all your rules.

Convert Cursor rules to Claude Code, GitHub Copilot, Windsurf, or AGENTS.md. And back. Bidirectional. Zero dependencies.

npx rule-porter --to agents-md

The problem

Your rules are locked into one tool's format. Cursor uses .mdc files with YAML frontmatter and glob patterns. Claude Code uses CLAUDE.md. Copilot uses .github/copilot-instructions.md. None of them understand each other.

What you get

$ npx rule-porter --to agents-md

Converting 12 Cursor rules → AGENTS.md

  ✓ 9 rules converted cleanly
  ⚠ 3 rules had glob patterns (preserved as comments)

Written: AGENTS.md

Converting back works too:

npx rule-porter --from agents-md --to cursor
# → 12 individual .mdc files with frontmatter and globs restored

Supported formats

Format	Read	Write	File
Cursor	✅	✅	`.cursor/rules/*.mdc`
Cursor (legacy)	✅	—	`.cursorrules`
AGENTS.md	✅	✅	`AGENTS.md`
Claude Code	✅	✅	`CLAUDE.md`
GitHub Copilot	✅	✅	`.github/copilot-instructions.md`
Windsurf	✅	✅	`.windsurfrules`

Common conversions

…

View on GitHub

475 lines across 5 files. Zero dependencies.

src/parser.js — .mdc frontmatter parser and rule discovery
src/cli.js — argument parsing, output formatting, file writing
src/formats/agents-md.js — AGENTS.md format writer
src/formats/claude-md.js — CLAUDE.md format writer
src/formats/copilot.js — Copilot instructions format writer

How I Built It

I already had a .mdc parser from cursor-doctor (a linter/diagnostic tool for Cursor rules). The parser handles YAML frontmatter extraction, glob pattern reading, and alwaysApply flag detection. I extracted the relevant parts and built the conversion layer on top.

The core problem is that Cursor's .mdc format is the only one with real structure. Every other format is just a flat markdown file. So converting from Cursor to anything else means making decisions about what to preserve and what to lose.

My approach:

Parse all .mdc files into an intermediate representation (name, description, globs, alwaysApply, body)
Split rules into global (alwaysApply) and conditional (everything else)
Each format writer decides how to represent that split
Anything that can't convert 1:1 produces a warning

The tricky part was handling real-world rules honestly. I tested against three actual GitHub repos with .cursor/rules/ directories and found things like: empty description fields, conditional rules with no glob patterns (manual-attach only in Cursor), Chinese content in rule bodies, and files with only frontmatter and no body. All of those needed to either convert cleanly or fail loudly.

Tech stack: Node.js, zero dependencies, var and require (no build step, runs on Node 12+).

🔧 Part of the nedcodes toolkit for Cursor AI developers.

I rewrote my Cursor linter into a full diagnostic tool (and added auto-fix)

Ned C — Fri, 27 Feb 2026 00:04:47 +0000

cursor-lint started as a thing I built because my own .mdc rules kept silently breaking. Missing frontmatter, bad YAML, alwaysApply not set. Cursor doesn't tell you when a rule fails to load. It just... doesn't load it. No error, no warning, nothing.

That tool ended up getting ~1,800 downloads, which was cool, but I kept running into problems it couldn't solve. Like, I had two rules that contradicted each other ("use semicolons" in one file, "avoid semicolons" in another) and the linter had no way to catch that. Or I'd have rules with 80% identical content because I'd copy-pasted and forgotten to clean up. The linter could tell me if individual rules were well-formed, but it couldn't tell me if my setup was healthy.

So I rebuilt it.

cursor-doctor

npx cursor-doctor scan

The free scan gives you a health grade (A through F) based on 8 checks: whether rules exist, legacy .cursorrules conflicts, 20+ lint checks, token budget, file type coverage, file sizes, alwaysApply usage, and whether you have agent skills set up.

It looks like this:

  Cursor Health: C  (62%)
  ──────────────────────────────────

  ✓ Rules exist
  ✗ No legacy .cursorrules
  ! Token budget: ~4,200 tokens — getting heavy
  ✓ Coverage: Rules cover your project file types

Zero dependencies, runs straight from npx.

The stuff that was actually hard to build

Conflict detection. This was the main thing I wanted. The tool extracts directives from your rule bodies ("use X", "prefer X", "never X", "avoid X") and compares them across files. If one rule says "always use trailing commas" and another says "remove trailing commas," it flags it. It's not just 9 hardcoded regex patterns anymore. It understands the intent of the instruction.

Redundancy detection. Compares line overlap between rules. If two files share more than 60% of their content, that's wasted context window. Every redundant token is a token not being used for your actual code.

Stack detection. Reads your package.json, requirements.txt, pyproject.toml, Cargo.toml, etc. and figures out what you're using. Knows about 12+ frameworks (React, Next.js, Django, Express, Vue, Svelte, and more) and 6 languages. If you're running a Next.js project with no Next.js-specific rules, it tells you.

Pro ($9, one-time)

The free scan shows you what's wrong. Pro fixes it.

cursor-doctor audit gives you the full diagnostic: conflicts, redundancy analysis, token budget breakdown (always-loaded vs conditional), stack-specific gap analysis, and concrete fix instructions. audit --md exports it as markdown you can share with your team or drop in a PR.

cursor-doctor fix actually repairs things. It auto-merges redundant rules, fixes broken YAML frontmatter, splits oversized files, and generates starter rules for your detected stack. There are templates for React, Next.js, Python, Django, Go, Rust, Vue, Svelte, Tailwind, Express, and testing. fix --dry-run previews everything before writing.

# Activate after purchase
cursor-doctor activate <your-key>

Get a Pro key · nedcodes.dev

Links

If you've been using cursor-lint, cursor-doctor includes everything it did plus all the diagnostic and repair stuff. Different package name though, so npx cursor-doctor is what you want now.

"This has been the biggest shift in how we build software since the move from Tab autocomplete to working synchronously with agents. More than 30% of the PRs we merge at Cursor are now created by agents operating autonomously in cloud sandboxes." Thoughts?

Ned C — Tue, 24 Feb 2026 21:50:02 +0000

Cursor rules vs skills — what's the actual difference?

Ned C — Tue, 24 Feb 2026 21:34:32 +0000

title: Cursor rules vs skills — what's the actual difference?
published: true
tags: cursor, ai, codequality, productivity

series: cursorrules-that-work

Cursor has two ways to give the agent persistent instructions: rules and skills. The docs explain what each one is, but they don't really explain when you'd pick one over the other. I had about 20 .mdc rules in a project and wasn't sure if I was supposed to migrate, so I ran some tests.

Here's what I found, and what I wish someone had told me before I started.

Rules: the short version

Rules live in .cursor/rules/ as .mdc files. They have YAML frontmatter at the top:

---
description: Use early returns when refactoring
alwaysApply: true
---
When refactoring code, always use early returns (guard clauses)
instead of nested if/else blocks.

The frontmatter gives you control over when the rule loads:

alwaysApply: true — loaded into every prompt, regardless of what you're working on
globs: "*.tsx" — only loads when working on matching files
description — helps the agent decide if the rule is relevant

Without alwaysApply or globs, rules aren't consistently picked up. In a previous test I ran, the agent didn't follow rules that were missing both. It can still find them through description matching or manual invocation, but don't count on it.

Skills: the short version

Skills live in .cursor/skills/<name>/SKILL.md. No frontmatter, no YAML, just markdown:

When refactoring code, always use early returns (guard clauses)
instead of nested if/else blocks.

Each skill gets its own subdirectory. That's it. Simpler setup, less configuration. But also less control over when and where the skill loads.

So what's actually different?

I put the same instruction in both formats and ran them through 15 tests on a real codebase (cursor-lint, ~900 lines across 4 files). Three runs per test, using the Cursor agent CLI.

When the task matches the instruction, they're identical. Rules followed 3/3, skills followed 3/3. Same output quality. The agent cited the rule by filename and the skill as a "system rule," but the generated code was the same.

Neither one fires on unrelated tasks. I kept the refactor instruction loaded but asked the agent to add a --verbose flag instead. Both the rule and the skill stayed in context but the model ignored them. 3/3 runs just added the flag without touching the code structure.

This actually corrects something I said in an earlier article. I claimed alwaysApply: true meant the rule would fire on every task, even unrelated ones. That's not quite right. It means the rule is LOADED into every prompt, but the model is smart enough to skip it when the task doesn't match. Loaded into context isn't the same as applied to output.

When they conflict, rules win. I set up a direct contradiction: the rule said "use early returns," the skill said "use nested if/else." The rule won 3/3. The agent cited the .mdc file in its reasoning and completely ignored the skill.

When I'd use which

Rules if you want control. The frontmatter lets you scope rules to specific file types, decide when they load, and give the agent context about what the rule is for. If you have a team or a big project with different conventions for different parts of the codebase, this matters.

Skills if you want simplicity. No frontmatter to mess up, no alwaysApply footgun, just write your instruction in markdown and drop it in a folder. If you have a small project or you're just starting with Cursor customization, skills are less to think about.

Don't mix them for the same instruction. If you have a rule and a skill that say different things, the rule wins. If they say the same thing, you're just wasting context window space.

I'm sticking with rules because I already have 20+ of them and the frontmatter is useful. But if I were starting fresh today, I'd probably try skills first and only switch to rules if I needed the scoping.

📋 I put together a free Cursor Safety Checklist based on stuff I've run into while testing all of this. Pre-flight checks for AI-assisted coding sessions, basically.

Grab it here if you want →

I loaded 50 rules into Cursor and it followed every single one

Ned C — Mon, 23 Feb 2026 18:52:40 +0000

I keep seeing people online worry about how many .cursorrules they can have before Cursor starts ignoring them. "Don't use too many rules," "keep it under 10," that kind of thing. But where was this coming from? Was there any truth to it?

So I tested it. I made 50 rules, loaded them all at once, and ran the same refactoring task 18 times across different rule counts.

The setup

I created rules for things that are easy to verify. always-semicolons, no-console-log, interface-prefix, early-return, stuff where you look at the output and can immediately tell if it was followed. I started at 1 rule and scaled up: 1, 5, 10, 20, 30, 50. Every rule had alwaysApply: true and proper frontmatter. The same task, 3 runs at each level.

I expected it to start falling off somewhere around 15-20 rules; that's what the online advice implies. Context windows have limits, models forget stuff, right?

What actually happened

Rules	Run 1	Run 2	Run 3
1-50	100%	100%	100%

100% compliance across all 18 runs. At every level. Including 50 rules at once(!)

I honestly thought I'd messed up the test. I checked the output files manually, rule by rule, and every single one was addressed. Some rules got marked "N/A" when they didn't apply to the test file (like cors-explicit when there's no API endpoint), but the model explicitly acknowledged them instead of silently skipping them.

You don't need to keep it under 10

At least for the current version of Cursor with Auto mode. I can't speak for older versions or other tools, but right now, 50 rules with alwaysApply: true and proper frontmatter all fire correctly.

Why I think people are still saying to keep it low

The people warning about "too many rules" are probably running into a different problem. Bad frontmatter, missing alwaysApply, vague rules that the model interprets differently than intended. Those are real issues that look like "the model forgot my rule" but are actually structural failures.

I've seen this pattern a lot. Someone has 15 rules, 3 of them aren't firing, and they assume it's a quantity problem when it's actually a formatting problem. The rule count isn't the bottleneck. The rule quality is.

But that was a toy project

The test above used a single file with a straightforward refactoring task. Real projects are different. You've got thousands of lines across multiple files, complex prompts, and the model has to juggle your project context alongside all those rules.

So I ran the same 50 rules against a real codebase: cursor-lint itself (4 files, ~900 lines). Instead of a simple single-file refactor, I asked Cursor to do a multi-file architectural change.

Test	Run 1	Run 2	Run 3
Single file (50 rules)	50/50	50/50	50/50
Real project (50 rules)	48/50	49/50	48/50

96-98% compliance. Not 100%. One or two rules got silently dropped each run, and here's the interesting part: it wasn't the same rules every time. Different ones fell off in different runs. No pattern I could find.

My read on this: with a toy file, the model has plenty of context budget for rules. In a real project, rules are competing with your actual code for attention. Most of them still fire. But if you're relying on every single rule hitting every single time, you might get surprised.

The actual takeaway

50 rules works. Even in a real project, you're getting 96%+ compliance. The "keep it under 10" advice is still wrong. But "load 50 rules and forget about it" isn't quite right either. If you have rules that absolutely must fire every time, keep them specific, keep the frontmatter clean, and spot-check occasionally.

🔧 Want to check your own setup? Run npx cursor-doctor scan to find broken frontmatter, conflicts, and token waste in your Cursor rules. Free, zero dependencies.

nedcodes.dev →

Just shipped framework detection in cursor-lint — auto-detects your stack and suggests matching rule presets. Different rules for different setups. https://github.com/nedcodes-ok/cursor-lint

Ned C — Mon, 23 Feb 2026 17:08:17 +0000

GitHub - nedcodes-ok/cursor-doctor: Cursor rules linter and auto-fixer. Find out why Cursor ignores your rules. 100+ checks, zero dependencies. · GitHub

Cursor rules linter and auto-fixer. Find out why Cursor ignores your rules. 100+ checks, zero dependencies. - nedcodes-ok/cursor-doctor

github.com

Everything I've learned so far about .cursorrules after mass testing them

Ned C — Sun, 22 Feb 2026 22:34:02 +0000

I've been running experiments on Cursor's rule system for a while now. I started because my rules weren't working and I couldn't figure out why, and I ended up going way deeper than I planned.

So if you're still using a .cursorrules file in your project root, it works, but it's the old way. Cursor moved to .cursor/rules/*.mdc files a while back. The .mdc format lets you scope rules to specific file types, set metadata in frontmatter, and organize rules into separate files instead of one giant blob. I tested both. If you have a .cursorrules AND .mdc files, the .mdc files win. The old file still loads in a clean directory with nothing else, but once you have the new format, that's what Cursor uses.

Migrating takes maybe 10 minutes. I split my monolithic .cursorrules into separate .mdc files by concern. One for TypeScript conventions, one for testing patterns, whatever.

alwaysApply: true or nothing

This one cost me WAY too much time...

Every .mdc file has YAML frontmatter at the top. There's a field called alwaysApply and if you don't set it to true, your rule just doesn't fire. I tested this 13 times because I was convinced something else was wrong. Nope. Without the flag? It got ignored. Every time. With it? It worked every time.

Your frontmatter needs to look like this:

---
description: "TypeScript conventions for this project"
globs: "**/*.ts"
alwaysApply: true
---

Without that last line, Cursor acts like the rule doesn't exist.

Be specific or get ignored

I tested vague rules vs specific ones at different lengths. Length doesn't matter AT ALL.

"Write clean, maintainable code." Longer version? Nah. Shorter version? Nah. Doesn't matter how many paragraphs you write elaborating on it. Your 'clean and maintainable' means the most generic of the generic.

"Use early returns instead of nested if blocks." That one it followed consistently, even as a single line.

Cursor isn't reading between the lines. It's not going to interpret "clean code" (or anything else) the way you mean it. You have to spell out exactly what you want unless what you want is...a universal standard, I guess.

Conflicting rules will stall the agent

I had two rules in separate .mdc files. One said "always add explicit type annotations." The other said "infer types when obvious." I didn't think this would be a big deal, I thought it could pick out the difference in context and use the right one when appropriate.

Cursor couldn't resolve the contradiction. The agent just sat there. It didn't error, it didn't pick one, it didn't try to merge them. Just... nothing. I thought it was a performance issue before I even thought to check if my rules were fighting each other. We just expect this stuff to work and in reality its brain can break as easily as ours when we're frustrated.

"Clean up this code" will delete your comments

This one STILL bothers me. I ran "clean up this code" on 17 different files. Every single comment got stripped. It didn't matter if the comment explained a browser workaround, a compliance requirement, a deprecation timeline. Cursor treated them all as noise.

Zero files kept their comments.

I added a rule that says "preserve all existing comments unless they contain TODO, FIXME, or are clearly outdated" and ran it again. Even then it only kept maybe half of them. Cursor seems to have a strong bias toward "clean = fewer comments" and you have to actively fight it.

I wrote a whole post about this one because I can see a lot of people not catching it in diffs.

Your frontmatter is probably broken

This is what finally pushed me to build something. Malformed YAML in your .mdc frontmatter fails completely silently. Missing colon, bad indentation, unclosed quote. No error, no warning. The rule just doesn't exist as far as Cursor is concerned.

I had rules that looked fine but weren't doing anything, and the reason was a missing colon in the frontmatter. It wasn't a logic problem or a wording problem. It was a typo.

So I built cursor-doctor to catch this stuff. I just run it as a pre-commit hook now so I don't waste another afternoon wondering why a rule isn't firing. It checks frontmatter, validates required fields, flags conflicts between rules.

Rules vs skills

Cursor added "agent skills" (.cursor/skills/*.md) recently. I tested both on the same tasks and they both work.

The difference: rules with alwaysApply: true load on EVERY task, even unrelated ones. You have a TypeScript formatting rule and you ask Cursor to write a Python script? That TS rule still loads and can confuse things. Skills only load when the task is relevant.

Oh and one weird thing. .claude/skills/ files from Claude Code don't get discovered by Cursor's agent at all. Skills have to be in .cursor/skills/.

Model choice doesn't matter for rule compliance

I expected at least one model to be worse at following instructions but nope. I tested the same rules across Sonnet 4.5, Gemini 3 Flash, and GPT-5.1 Codex Mini. All three followed the rules at the same rate. Compliance is about rule quality, not model selection.

Negative vs positive framing doesn't matter either

"Do NOT use nested ternaries" vs "Use if/else blocks instead of nested ternaries." I ran 30 tests on this. No difference. 30/30 compliance both ways.

Write rules however feels natural to you. The framing doesn't matter, that's something that mattered for AIs a few years ago but not now.

What I use now

I have about 8 .mdc files in most projects. TypeScript conventions, comment preservation, testing patterns, a few framework-specific ones. Each file is short and specific. I run cursor-lint as a pre-commit hook and in CI through the GitHub Action.

The whole setup takes maybe 15 minutes for a new project and it saves me from the stuff I spent weeks debugging when I didn't know any of this.

🔧 Want to check your own setup? Run npx cursor-doctor scan to find broken frontmatter, conflicts, and token waste in your Cursor rules. Free, zero dependencies.

nedcodes.dev →