Skip to content
Back to AI Coding

Cursor Rules and .cursorrules Configuration

Tune Cursor output quality with project rules, ignore patterns, and context scoping.

CursorIntermediate

Why

According to Sacra, Cursor hit $65M ARR in November 2024 (6,400% YoY growth), and JetBrains' January 2026 AI Pulse survey found 18% of professional developers use Cursor at work. .cursorrules is the single highest-leverage Cursor config. It is injected into every prompt, so a few precise lines reshape all completions and chats to match your architecture.

Without it, Cursor defaults to generic Next.js/React patterns that fight your conventions and produce diffs you reject.

When

Add a .cursorrules whenever Cursor suggestions do not match your project conventions: wrong export style, invented data-fetching patterns, or imports from the wrong layer. Also use it when onboarding new devs who use Cursor, so they inherit conventions without a doc hunt.

How

1. Create .cursorrules in the project root (plain text, committed to git). 2. State the stack and version pins first: "Astro 7 static site, React 18 islands, Tailwind 3, TypeScript strict." 3. Add architecture rules that prevent the most common wrong suggestions: - "Data lives in src/data/*.ts. Never inline data in components." - "Components use named exports. Only Astro pages use default exports." - "i18n: 9 locales, en at root, others at /{locale}/. Use the i18n helpers." 4. Add style rules that match your lint config: - "No default exports except pages. No 'any'. Prefer type over interface." 5. Add anti-patterns explicitly (negatives work well): - "Do not use useEffect for data fetching. Data is build-time only." - "Do not import from astro/data/* in components; import from src/data/." 6. Scope context with .cursorignore to keep large generated dirs out of the index: dist_astro/ node_modules/ *.min.js 7. Iterate. When Cursor makes a wrong suggestion, add a one-line rule that prevents it. Treat .cursorrules as a living document, reviewed in PRs.

Example

.cursorrules for an Astro + React monorepo: You are working on an Astro 7 static site with React 18 islands. Build: 'npm run build' (tsc -b && astro build). - Data source of truth: src/data/*.ts. Derived indexes: astro/data/*Index.ts. - Never inline data in components; always import from src/data/. - Named exports for components; default export only for Astro pages. - i18n: 9 locales, en at root, others at /{locale}/. - CSS: Tailwind 3 with spark/ink custom palettes. No CSS modules. - No 'any' types. No useEffect for data fetching (build-time only). - Do not import from astro/data/* in components. .cursorignore: dist_astro/ node_modules/ coverage/ *.min.js

Common Problems

  • ⚠Cursor suggests `import x from 'nonexistent-pkg'` → check package.json; if missing run `npm install <pkg>` and verify the import path resolves.
  • ⚠Error: "Context window exceeded" warning on large files → use @file to scope context, or run Cmd+Shift+P → 'Cursor: Rebuild Index' after structural changes.
  • ⚠Error: Tab completion stops working after branch switch → run `git status` then Cmd+Shift+P → 'Cursor: Rebuild Index'; stale index is the usual cause.
  • ⚠Cursor suggests `import x from 'nonexistent-pkg'` → check package.json; if missing run `npm install <pkg>` and verify the import path resolves.

Best Practices

  • ✓Lead with the stack and version pins; they anchor every other suggestion.
  • ✓Write rules as concrete negatives ('do not X') and concrete positives ('always Y from Z').
  • ✓Keep .cursorrules under 20 lines; move long-form docs to CLAUDE.md or /docs.
  • ✓Commit .cursorrules and review changes in PRs so the team agrees on conventions.
  • ✓Add a rule the moment Cursor repeats a wrong suggestion; fix the root cause, not the symptom.

FAQ

What is .cursorrules and where does it go?

It's a plain-text file in the project root whose contents are injected into every Cursor prompt. A few precise lines reshape all completions and chats to match your architecture. Commit it to git so the whole team shares the same rules.

How is .cursorrules different from CLAUDE.md?

.cursorrules is Cursor-specific and injected into every Cursor prompt. CLAUDE.md is read by Claude Code. They serve the same purpose (project conventions) for different tools — many teams keep both in sync, or generate one from the other.

How long should .cursorrules be?

Keep it under ~20 lines of hard rules. A 50-line file dilutes attention. Lead with the stack and version pins, then concrete positives ('always import from src/data/') and negatives ('do not use useEffect for data fetching'). Move long-form docs to /docs.

What is .cursorignore for?

It lists paths Cursor should not index (dist/, node_modules/, *.min.js, coverage/). Keeping large generated dirs out of the index saves context and speeds indexing. Without it, build artifacts pollute retrieval and waste your context budget.

How do I stop Cursor from suggesting Next.js patterns?

Add explicit stack and anti-pattern rules to .cursorrules: 'Astro 7 static site, no Next.js', 'data is build-time only, no useEffect for fetching', 'named exports except pages'. Cursor defaults to Next.js/React when no rules are set; precise rules override the default.