What Is .cursorrules?
.cursorrules is a text file in the root of your project repository that provides instructions to Cursor AI. When you open a project in Cursor: the AI reads this file and follows the rules for all code generation — Tab completions, Cmd+K inline edits, and Cmd+L chat responses. The file: customizes Cursor's AI behavior for your specific project. Without it: Cursor generates generic code. With it: Cursor generates code that follows your team's conventions.
The file format: plain text or Markdown. No special syntax required. Write your conventions as clear statements the AI can follow. Example rules: 'Use TypeScript strict mode. Use async/await for all async operations. Use Vitest for testing. Use Tailwind CSS for styling. Error handling: use the Result pattern for business logic.' The rules: read by Cursor automatically. No configuration needed beyond creating the file in the right location.
The name: .cursorrules (with the leading dot — a hidden file on macOS and Linux). The file: must be in the project root (the directory you open in Cursor). If you open a subdirectory: Cursor may not find the file. The dot prefix: follows the convention of other project configuration files (.gitignore, .eslintrc, .prettierrc). AI rule: 'The file must be named exactly .cursorrules with the leading dot. Case-sensitive on Linux and macOS. In the project root directory.'
What to Write in .cursorrules
The content: identical to what you would write in CLAUDE.md or any AI rule file. Project context (tech stack, architecture), coding conventions (naming, patterns, error handling), testing standards (framework, naming, coverage), security rules (validation, authentication, data handling), and framework-specific patterns (Next.js App Router conventions, NestJS module patterns, etc.). The content: not Cursor-specific. It describes your project's conventions in a way any AI can understand.
Example .cursorrules content: '# Project\nNext.js 16 App Router with TypeScript, Drizzle ORM, and Tailwind CSS.\n\n# Conventions\n- Server Components by default. Add "use client" only when needed.\n- Use async/await. No .then() chains.\n- Error handling: Result<T, E> pattern in services.\n- Named exports only. No default exports.\n\n# Testing\n- Vitest for unit tests. Playwright for E2E.\n- Tests co-located with source files.\n- describe/it naming: it("should [behavior] when [condition]").'
How many rules: start with 15-20 covering your top conventions. Expand to 30-50 as you identify gaps. Keep the file under 3,000 words (Cursor processes the entire file for context — very long files may reduce the effective attention on individual rules). Prioritize: the most impactful rules first (security, error handling, naming) at the top of the file. AI rule: 'Under 3,000 words for optimal Cursor processing. Most important rules first. Expand gradually based on what the AI gets wrong.'
The content of .cursorrules: identical to what you would write in CLAUDE.md (for Claude Code) or .github/copilot-instructions.md (for Copilot). The same project context. The same naming conventions. The same error handling rules. The same testing standards. The only difference: the file name and location. If you already have a CLAUDE.md: copy the content to .cursorrules. Both tools: get the same conventions. Your team: consistent regardless of which AI tool each developer prefers.
Advanced: The .cursor/rules Directory
For projects with multiple tech stacks or complex rule sets: Cursor supports a .cursor/rules/ directory with multiple rule files. Each file: targets a specific area. Examples: .cursor/rules/frontend.md (React conventions), .cursor/rules/backend.md (API conventions), .cursor/rules/testing.md (test patterns), .cursor/rules/security.md (security rules). Cursor: applies the relevant rules based on the file being edited. A .tsx file: gets frontend + testing rules. A route.ts file: gets backend + security rules.
When to use the directory: when the single .cursorrules file exceeds 3,000 words (split into focused files), when the project has distinct frontend and backend conventions (separate files prevent irrelevant rules from cluttering the context), or when different team members maintain different rule areas (the frontend lead maintains frontend.md, the backend lead maintains backend.md). For most projects: the single .cursorrules file is sufficient. The directory: for larger, multi-stack projects.
Priority and composition: when both .cursorrules and .cursor/rules/ exist: Cursor reads both. The .cursorrules file: provides the base rules. The directory files: add context-specific rules. For conflicts: the more specific rule (from the directory) takes precedence. AI rule: '.cursorrules for the base. .cursor/rules/ for context-specific additions. Most projects: .cursorrules alone is enough. Add the directory when the single file becomes too large or too generic.'
A single .cursorrules file: 30 rules mixing React frontend conventions, NestJS backend patterns, and infrastructure rules. When editing a React component: the AI reads all 30 rules, including 15 that are irrelevant (NestJS and infrastructure). The .cursor/rules/ directory: frontend.md (10 rules), backend.md (10 rules), infrastructure.md (10 rules). When editing a React component: Cursor applies frontend.md. The context: focused. The output: more accurate because the AI only sees relevant rules.
How .cursorrules Compares to CLAUDE.md and copilot-instructions
The three rule files: .cursorrules (Cursor), CLAUDE.md (Claude Code), and .github/copilot-instructions.md (GitHub Copilot). All three: serve the same purpose (guide AI code generation with project conventions). The content: can be identical across all three. The file name and location: the only difference. If your team uses multiple AI tools: maintain all three files with the same content. Or: maintain one source file and copy to all three locations.
Key differences: .cursorrules is read by Cursor's Tab completion, Cmd+K edits, AND Cmd+L chat — all three AI features. CLAUDE.md is read by Claude Code's CLI and IDE extension. copilot-instructions.md is read by Copilot Chat and influences inline suggestions. The content format: all three accept Markdown. The content: identical for all three. The file name: the only thing that differs.
Keeping them in sync: if using multiple AI tools, maintain one canonical source file (e.g., RULES.md or ai-rules.md). A build script or pre-commit hook: copies the source to .cursorrules, CLAUDE.md, and .github/copilot-instructions.md. Update one file: all three are updated. No drift between tools. AI rule: 'One source of truth. Three distribution targets. The simplest sync: a shell script in the pre-commit hook. cp RULES.md .cursorrules && cp RULES.md CLAUDE.md && cp RULES.md .github/copilot-instructions.md.'
The file: .cursorrules in the project root (the directory you open in Cursor). Not in: src/.cursorrules (subdirectory — Cursor does not look there), not in: ~/.cursorrules (home directory — that is for global Cursor settings, not project rules), and not in: .cursor/.cursorrules (the .cursor directory is for Cursor's internal settings). Project root only. If Cursor is not following your rules: verify the file location first.
.cursorrules Quick Reference
Quick reference for .cursorrules.
- What: a text file that tells Cursor AI your project's coding conventions
- Where: project root directory (next to package.json). Named .cursorrules with leading dot
- Format: plain text or Markdown. No special syntax. Clear statements the AI can follow
- Content: project context + coding conventions + testing + security. Same as CLAUDE.md
- Size: start with 15-20 rules. Under 3,000 words for optimal processing
- Advanced: .cursor/rules/ directory for multi-file rule sets (frontend.md, backend.md, etc.)
- Multi-tool: same content in .cursorrules, CLAUDE.md, and copilot-instructions.md. One source, three copies
- Impact: Cursor generates project-specific code instead of generic patterns. Immediate improvement