How to Use Cursor Rules

Before You Begin: Prerequisites

To follow this guide, you need Cursor IDE installed on your machine. You can download it for free from cursor.com — it is available for macOS, Windows, and Linux. No account is required for basic usage, though signing in enables AI features powered by models like GPT-4 and Claude. You should also have a project open in Cursor — any codebase will work, whether it is a new project or an existing one with hundreds of files.

If you are new to Cursor IDE, spend a few minutes familiarizing yourself with the AI features: inline code completions (triggered automatically as you type), the chat panel (Cmd+L / Ctrl+L), and the inline editor (Cmd+K / Ctrl+K). Understanding these interaction modes will help you appreciate how .cursorrules influences each one differently — from single-line suggestions to multi-file agent operations.

Step 1: Understand What .cursorrules Does

Before writing any rules, it is important to understand what a .cursorrulesfile actually does. In Cursor IDE, the AI assistant reads your project's .cursorrulesfile on every interaction — code completions, inline edits, chat messages, and agent mode actions. The file serves as a persistent system prompt that shapes every AI output to match your team's conventions. Unlike linters or formatters that only validate code after it is written, .cursorrules influences code at the point of generation, preventing inconsistencies before they happen.

A well-crafted .cursorrules file can enforce code style (indentation, quotes, semicolons), naming conventions (camelCase, PascalCase, snake_case), architectural patterns (component structure, error handling idioms), testing requirements, and framework-specific best practices. For teams, it ensures every developer — and every AI interaction — produces code that looks and feels consistent.

Step 2: Generate Your .cursorrules File

The fastest way to create a production-ready .cursorrules file is to use our interactive generator. Select your tech stack — you can pick one or combine multiple frameworks like React with TypeScript and Tailwind CSS. Then configure your style preferences: indentation (tabs or spaces, 2 or 4 width), quote style (single or double), semicolon usage, and naming conventions. Finally, add any custom rules specific to your project, such as file structure requirements, testing mandates, or documentation standards.

After configuring, you will see a real-time preview of your rules. Review it to make sure everything looks correct, then click Download to save the file. The generator produces a clean, well-organized .cursorrules file with sections for code style, naming conventions, framework-specific patterns, architecture guidelines, and testing requirements — all tailored to your stack.

Step 3: Place the File in Your Project

Save the downloaded .cursorrules file in the root directory of your project — the same folder that contains your package.json, go.mod, or Cargo.toml. The leading dot in the filename makes it a hidden file on macOS and Linux, keeping your workspace clean. Cursor IDE automatically detects the file the next time you open the project or reload the window.

There is no configuration panel to visit and no plugin to install. Simply having the file in your project root is enough. If you want to verify that Cursor is reading your rules, open the AI chat panel and ask the assistant about your project conventions — it should reference the rules you defined.

Step 4: Test and Iterate

After placing the file, test it by asking Cursor to generate code in your project. Try generating a new component, function, or module and check whether the output follows your rules. Pay particular attention to indentation, quote style, naming conventions, and import patterns. If the AI produces code that does not match your expectations, review your rules and make them more specific. For example, instead of writing "use functional components," write "always use arrow function components with explicit TypeScript return types."

Iteration is key. The best .cursorrulesfiles evolve with your project. Start with the generated template, use it for a few days, and note any AI behaviors that still need adjustment. Update the file accordingly, commit the changes, and share them with your team. Over time, your rules will become an accurate reflection of your team's actual coding standards.

Step 5: Share with Your Team

Commit your .cursorrulesfile to version control so every team member benefits from the same AI configuration. When someone clones the repository and opens it in Cursor, the AI assistant immediately follows the team's conventions — no manual setup required. This is especially valuable for onboarding new team members, who get AI assistance that already understands your codebase conventions from day one.

For organizations with multiple projects using different tech stacks, create a separate .cursorrules file for each project. Our generator makes it easy to produce unique rules for each codebase, ensuring that your React frontend, Go backend, and Python data pipeline each get AI assistance tuned to their specific ecosystem.

Common Pitfalls to Avoid

Even experienced developers run into a few common issues when setting up .cursorrules. The most frequent mistake is writing rules that are too vague — statements like "write clean code" give the AI no actionable guidance. Instead, be specific: "use 2-space indentation, single quotes, and no semicolons." Another common pitfall is forgetting to add rules for imports and file organization. AI assistants tend to add imports in random order unless you explicitly specify that imports should be grouped and sorted.

Teams sometimes create a single massive .cursorrules file that covers every possible framework they might use. This dilutes the effectiveness of the rules because the AI spends more tokens processing irrelevant instructions. A better approach is to create focused rules for each project — a React frontend gets React rules, a Go backend gets Go rules, and nothing is wasted on irrelevant guidance. Also, do not set the strictness level too high during initial setup. Start with a moderate strictness level and increase it as you confirm the rules produce the right results. Overly strict settings early on can lead to AI refusals for legitimate code patterns.

Advanced Configuration Tips

Once your basic rules are in place, consider these advanced techniques to get even more from your .cursorrules file. Add project-specific context such as your preferred testing framework (Jest, Vitest, pytest), your CI pipeline requirements, and any internal libraries or conventions that your team relies on. You can also include file organization rules — for example, specifying where components, utilities, and tests should live in your directory structure. The more context you provide, the more precisely the AI assistant can generate code that fits your actual workflow rather than a generic template.

For monorepos and multi-package projects, place a separate .cursorrulesfile in each package root. Cursor IDE reads the rules file closest to the file being edited, allowing each package to have its own conventions while sharing a common root-level rules file for cross-cutting standards. This layered approach gives you fine-grained control without duplicating shared rules across every package. You can also reference external documentation or style guides within your rules by including URLs that the AI can follow when generating code, though this depends on Cursor's current web access capabilities.

Troubleshooting: When Rules Do Not Work as Expected

If the AI consistently ignores certain rules, the most common cause is ambiguity. Vague instructions like "write clean code" or "follow best practices" give the AI no concrete direction. Rewrite the rule with explicit, measurable requirements — specify exactly what indentation width, what quote character, and what naming pattern the AI must use. If the AI still does not comply, try reordering your rules: Cursor processes .cursorrules as a single prompt, and instructions near the end can sometimes override earlier ones. Move your most important rules to the top of the file for maximum impact.

Choosing Your Format: .mdc vs AGENTS.md vs .cursorrules

Cursor IDE supports three formats for customizing AI behavior, each with distinct capabilities. Project Rules (.mdc) is the most powerful option — individual .mdc files in the.cursor/rules/ directory with YAML frontmatter that lets you target specific file patterns via globs, togglealwaysApply, and split rules across multiple domain-specific files. This is the recommended format for teams with separate frontend, backend, and infrastructure concerns.

AGENTS.md is a single markdown file at your project root. Simpler than Project Rules — no frontmatter, no glob targeting, no splitting — but excellent for small projects, open-source repos, and quick onboarding. Every contributor can read it immediately.Legacy .cursorrules is the original plain-text format. Still fully supported but offers the least flexibility. Use it for existing projects that already depend on it, or migrate to Project Rules for the benefits of frontmatter metadata and multi-file organization.

You can generate all three formats from the same configuration on our generator. Switch between them at any time without losing your rules — the underlying conventions stay consistent across formats.

Project Rules Frontmatter: A Deep Dive

Every .mdc file starts with YAML frontmatter that tells Cursor exactly when and where to apply its rules. The four key fields are:

• description — A short, human-readable summary of what this rule file covers. Shown in Cursor's rules panel so teammates can understand the purpose at a glance.
• globs — An array of file-matching patterns (e.g., "src/components/**/*.tsx") that determine which files this rule applies to. Leave empty or omit to apply globally.
• alwaysApply — Boolean. When true, Cursor always includes these rules in every AI interaction, regardless of which file you are editing. Ideal for code style rules that should apply everywhere. When false, only applies when editing files matching the globs.
• version — Optional semantic version string (e.g., "1.0.0"). Useful for tracking rule changes over time, especially in teams where rules evolve with the codebase.

A well-structured .cursor/rules/ directory might look like this: react-components.mdc for frontend conventions,go-backend.mdc for API patterns, and testing-standards.mdc with alwaysApply: true for test requirements that span the entire codebase.