Your .cursorrules file is probably not working the way you think it is.
Not because Cursor is broken — but because most .cursorrules setups make the same five mistakes. Here is what they are and how to fix them.
Mistake 1: One file, everything in it
The most common .cursorrules antipattern is the monolith: one file at the project root, 300 lines long, covering TypeScript conventions AND API auth patterns AND deployment notes AND "always write clean code."
The problem: Cursor loads this file into every context, regardless of what you are editing. When you are fixing a CSS bug, your SQL query rules are burning token budget for nothing. When context gets long, older rules get compressed out — which means your most important constraints are the ones most likely to disappear.
Fix: Split into scoped rule files.
.cursorrules # 50 lines: project overview, stack, non-negotiables
src/api/.cursorrules # Auth patterns, error format, rate limiting
src/components/.cursorrules # Component conventions, state patterns
scripts/.cursorrules # Env handling, idempotency, logging
Each file loads only when files in that directory are open. Your total in-context rule budget stays tight.
Mistake 2: Vague constraints
"Write clean, readable code."
"Keep functions small."
"Follow best practices."
These are not rules. They are aspirations. The AI already knows what "best practices" means — and it will apply its own interpretation, not yours.
Rules need to be specific enough to fail. If you cannot imagine a concrete code sample that violates the rule, the rule is too vague to enforce.
Vague: "Handle errors properly."
Specific: "All async functions must have a try/catch. Errors must be logged via logger.error() before rethrowing. Never swallow errors silently."
Vague: "Use descriptive variable names."
Specific: "Boolean variables must start with is, has, should, or can. No single-letter names outside of loop indices."
The second versions are automatable. The first versions are vibes.
Mistake 3: No project structure context
The AI does not know your project layout unless you tell it. This leads to imports from wrong paths, new files dropped in wrong directories, and helper functions duplicated because the AI didn't know one already existed.
Add a compact directory map early in your .cursorrules:
Project structure:
src/
api/ # Express routes + middleware
services/ # Business logic (no HTTP)
models/ # Prisma schema types
utils/ # Pure functions, no side effects
types/ # Shared TypeScript interfaces
tests/ # Mirrors src/ structure
scripts/ # One-off automation, not imported by app
Eight lines. Enough to save the AI from putting a database call in a route handler because it didn't know services/ exists.
Mistake 4: Rules that contradict the codebase
If your .cursorrules says "never use any types" but your codebase has 200 any type usages, the rule is fighting the existing code. The AI gets conflicting signals: the rule says one thing, the examples in the codebase say another. The examples usually win.
Your rules should describe what the code already does, not what you wish it did.
If there is a gap — you want to adopt a new pattern but your codebase isn't there yet — say so explicitly:
# Migration in progress: we are removing `any` types.
# New code must not use `any`. Existing `any` usages will be fixed incrementally.
# Do not add new `any` even when refactoring old code.
This gives the AI a clear mandate without creating a contradiction.
Mistake 5: Duplicating rules across tools without a source of truth
If you use Cursor + Claude Code, you end up with .cursorrules and CLAUDE.md saying the same things in slightly different ways. Then one gets updated and the other doesn't. Then they contradict each other. Then neither is trusted.
The fix is a single authoritative source with tool-specific adaptations:
- Keep your core project rules in
CLAUDE.md(it is the most structured format and is loaded by Claude Code as a system prompt prefix). - Have
.cursorrulesimport or reference the same core rules, adding only Cursor-specific formatting/behavior. - When you update the rules, update the source — not each tool's file separately.
For greenfield projects, starting with a production-configured starter that already has both files wired up correctly saves this setup cost entirely. The Vibe Coder Kit includes 12 starters (Next.js SaaS, Express + JWT, FastAPI, Discord Bot, and more) where .cursorrules and CLAUDE.md are already synchronized and match the actual codebase structure.
The test for a good rules file
Read each rule and ask: "Could a developer violate this rule while genuinely trying to follow it?" If yes, the rule is too ambiguous. Make it specific enough that violations are unambiguous.
Then count your lines. If your .cursorrules is over 100 lines, split it. If it is under 20, you probably have not captured your real conventions yet.
Short. Specific. Scoped. Consistent with the codebase.
Those four constraints will make your AI coding setup work the way the demos promise.
BLN Craft builds developer tools for AI-native workflows. Find us at blncraft.com.
