How to Write .cursorrules: A Complete Guide for Cursor AI

What Is .cursorrules?

The .cursorrules file is Cursor AI's project-level configuration — a plain text file in your repository root that tells Cursor how to write code for your specific project. It's the Cursor equivalent of CLAUDE.md for Claude Code or .github/copilot-instructions.md for GitHub Copilot.

When you open a project in Cursor, the editor reads .cursorrules before generating any code. Every instruction in the file influences Cursor's completions, chat responses, and code generation for that project. Without it, Cursor falls back to its general training — which may not match your team's conventions.

The file uses a dotfile convention (prefixed with a period), similar to .gitignore or .eslintrc. This means it's hidden by default in most file explorers. You may need to toggle 'show hidden files' in your OS or IDE to see and edit it.

How .cursorrules Differs from CLAUDE.md

Both files serve the same purpose — giving an AI assistant project-specific context — but they differ in scope, hierarchy, and parsing. Understanding these differences matters if you're migrating rules between tools or maintaining both files in the same repo.

Scope: CLAUDE.md supports hierarchical rules — a root file plus subdirectory-specific overrides. Cursor's .cursorrules is a single file per project with no built-in hierarchy. If you need different rules for different parts of a monorepo, you'll need to put everything in one file with clear section headers.

Parsing: Claude Code processes the full markdown specification including tables, code blocks, and conditional rules. Cursor treats .cursorrules primarily as plain text instructions. Markdown headers and bullets work, but complex formatting like tables may not be parsed as structured data. Keep rules as direct statements.

Newer versions of Cursor also support a Cursor Rules directory for organizing rules into multiple files. Check Cursor's documentation for the latest capabilities, as this feature set is evolving rapidly.

• CLAUDE.md: Full markdown, hierarchical (root + subdirectory), conditional rules supported
• .cursorrules: Plain text with markdown basics, single file (or Cursor Rules directory in newer versions)
• Both: Project root location, markdown headers and bullets, code inline references
• Key difference: CLAUDE.md excels at structured rules; .cursorrules works best with direct, concise statements

Writing Effective Cursor Rules

Cursor parses .cursorrules as a sequence of instructions. The most effective format is short, direct statements — one rule per line or one rule per bullet point. Avoid long paragraphs of explanation; Cursor responds better to imperative instructions than to conversational context.

Start rules with action verbs: 'Use TypeScript strict mode', 'Always handle errors with try/catch', 'Prefer named exports over default exports'. This imperative style maps directly to how Cursor interprets instructions internally.

Group related rules under markdown headers. Even though Cursor doesn't parse headers as structured sections the way Claude Code does, headers help the model locate relevant rules when generating code in a specific context. A rule under '# Testing' is more likely to be applied when Cursor is writing test code.

Keep the file under 150 lines. Cursor's rule processing has practical limits — extremely long files may result in later rules being weighted less heavily. If your rules exceed 150 lines, consider splitting into the Cursor Rules directory format.

Examples for Popular Frameworks

Here are the most impactful rules for three popular stacks. These aren't exhaustive templates — they're the rules that eliminate the most common Cursor mistakes for each framework.

For React/Next.js projects, the highest-impact rules are: 'Use React Server Components by default, only add "use client" when the component needs hooks or event handlers', 'Use the App Router, not the Pages Router', and 'Prefer server-side data fetching over useEffect'. These three rules alone prevent the most frequent Next.js generation errors.

For Python projects, focus on: 'Add type hints to every function signature and return type', 'Use Pydantic models for data validation, not raw dictionaries', and 'Handle errors with specific exception types, never bare except'. Python AI output without type hint rules is consistently lower quality than with them.

For Go projects, the critical rules are: 'Always wrap errors with fmt.Errorf and %w for error chains', 'Return errors instead of panicking for recoverable failures', and 'Use table-driven tests with t.Run subtests'. Go's explicit error handling is where AI assistants most frequently deviate from idiomatic patterns.

Common Mistakes with .cursorrules

The most common mistake is writing rules that are too vague. 'Write clean code' tells Cursor nothing actionable. 'Use async/await for all asynchronous operations, never use .then() chains' gives Cursor a concrete decision to make every time it encounters async code.

The second mistake is forgetting the dot prefix. The file must be named .cursorrules (with the leading period), not cursorrules. Without the dot, Cursor won't detect it. This catches more developers than you'd expect — especially on macOS where dotfiles are hidden by default.

Third, don't duplicate your ESLint or Prettier config in .cursorrules. Those tools handle formatting and lint rules at build time. Your .cursorrules should focus on architectural decisions, patterns, and conventions that linters can't enforce: which libraries to prefer, how to structure components, what testing patterns to use.

Finally, avoid contradictory rules. If one line says 'Use default exports for components' and another says 'Prefer named exports', Cursor's behavior becomes unpredictable. Review your rules for conflicts before committing.

• Too vague: 'Write good code' → no actionable guidance for the AI
• Missing dot prefix: cursorrules won't be detected — must be .cursorrules
• Duplicating linter config: focus on decisions linters can't enforce
• Contradictory rules: conflicting instructions produce inconsistent output
• File too long: 200+ lines dilutes the impact of your most important rules

Managing .cursorrules Across Repos

The same drift problem that affects CLAUDE.md affects .cursorrules: copy-pasting across repos leads to divergence within weeks. If your team uses Cursor across multiple projects, you need a centralized way to manage and sync rule files.

The approach is the same as for any AI rule file: define your rules once in a central source, then sync them to every repo. RuleSync supports generating .cursorrules alongside CLAUDE.md — define your rulesets in the dashboard, and the CLI writes the appropriate file for each repo's configured format.

For teams that use both Cursor and Claude Code, maintaining a single canonical rule source is especially valuable. The core rules — code style, testing, security — are the same regardless of which AI tool applies them. Write them once, generate both .cursorrules and CLAUDE.md, and keep them in sync automatically.