The Complete Guide to Cursor Rules
A comprehensive guide to understanding and implementing Cursor Rules for better AI-assisted development workflow.
Quick note: The following guide uses the current date of 31 August 2025. Whenever I mention "today" or "recent," I'm referring to dates relative to that point in time. The Cursor IDE continues to evolve quickly, so always check the official docs for updates.
What is Cursor and why do rules matter?
Cursor IDE combines a traditional code editor with a built‑in AI agent. In a Medium article on building a daily task manager, Roberto Infante describes Cursor as "an always‑on pair programmer" that understands your project and assists with writing, editing and debugging code[1]. Unlike simple autocomplete tools, Cursor can read your entire codebase and follow high‑level instructions. However, large language models do not retain memory between completions; each time you ask a question, the AI starts with a blank slate[2]. That's where rules come in.
A rule is a persistent, system‑level instruction that shapes the agent's behaviour. Whenever a rule is applied, its content is inserted at the start of the model's context, giving the AI consistent guidance[2]. Instead of repeatedly telling the assistant "use React functional components" or "never use any types," you write these preferences once and Cursor will automatically follow them in every session[3]. Rules help you enforce team conventions, automate repetitive patterns and reduce back‑and‑forth corrections. The result is more consistent, maintainable code and less time spent on style reviews[4].
Overview of rule categories
Cursor currently supports several ways to store rules:
| Category | Scope & storage | Typical use |
|---|---|---|
| Project rules[5] | Stored in a .cursor/rules/ directory in your repository. Each rule lives in its own .mdc file. Rules are version‑controlled and can be scoped to specific files via glob patterns. | Encode domain‑specific knowledge, enforce architecture decisions, provide templates or automate workflows within a project. |
| User rules[6] | Defined once in your personal Cursor settings. These apply globally to all projects. | Set personal preferences such as reply style or default libraries. |
| AGENTS.md[7] | A plain markdown file placed at the project root. It lacks metadata and applies globally across the project. | Useful when you need simple, readable instructions without splitting rules across multiple files. |
| Legacy .cursorrules[8] | A single file in the project root. Still supported but deprecated. | Only use if migrating older projects; prefer project rules for more flexibility. |
Types of rule files
Within a project, each rule file includes front‑matter metadata that determines when and how it is applied[9]. The official docs and community discussions describe four types:
| Rule type | How it's triggered | When to use |
|---|---|---|
| Always | alwaysApply: true. The rule is included in every prompt for the project[9]. | For universal policies such as your language style guide. Keep these rules concise to avoid crowding the prompt[10]. |
| Auto attached | Provide globs patterns and set alwaysApply: false. When the AI references files matching the pattern, the rule is automatically loaded[9]. | For section‑specific rules, e.g., apply React standards when editing src/*/.tsx. |
| Agent requested | Include a description field. The rule is stored and the agent decides to fetch it based on the description[11]. | Useful for optional guidelines (e.g., design patterns). Write a clear description so the agent knows when to use it[12]. |
| Manual | Omit metadata or set alwaysApply: false without globs and description. The rule is only loaded when explicitly referenced with @ruleName[9]. | Treat manual rules like macros or templates. Use them when you occasionally need a snippet or procedure[13]. |
Creating rules
- Set up the directory. In your project root, create a .cursor/rules folder (or use AGENTS.md/.cursorrules if you prefer the legacy approach). Each rule file uses the .mdc extension and can have its own name—for example, react.mdc or database.mdc[14].
- Add front‑matter. A rule file starts with a YAML front‑matter block to define metadata. Here's the minimal structure:
---
description: Apply React standards for component structure
globs: ["src/**/*.tsx"]
alwaysApply: true # set to true for Always rules or omit for Auto/Manual
---
- Use functional components
- Separate presentational and logic parts (Smart vs. Dumb)
- Include ARIA attributes for accessibility
- Memoize expensive components
- Export a named component and place styles at the bottom
- Write actionable content. After the front‑matter, list bullet‑point instructions. The docs recommend keeping rules under 500 lines, splitting large rules into composable files, and providing concrete examples or referenced files[15]. Avoid vague statements like "write good code"; instead specify "use explicit return types" or "add loading states for data fetching"[16].
- Create rules using the UI. Cursor includes a New Cursor Rule command in the command palette (Cmd/Ctrl + Shift + P). This generates the .mdc file automatically in .cursor/rules[17]. You can also generate rules from a chat conversation by running /Generate Cursor Rules to capture a set of instructions[18].
- User rules. To set global preferences, go to Cursor Settings → Rules and paste plain‑text instructions. These user rules are applied across all projects and are perfect for setting a consistent communication style or coding convention[19]; for example, "Respond concisely and avoid filler language."
Best practices for writing effective rules
Based on the official documentation and community guidelines:
- Be specific and actionable. Vague guidance is less effective. Tell the AI exactly what to do or avoid[20]. For instance, rather than saying "use best practices," specify "prefer const over let," "use React hooks instead of class components," or "import React explicitly"[21].
- Keep rules concise. Aim for clarity and brevity. The docs suggest keeping each rule file under 500 lines and splitting complex policies into smaller, focused files[15]. A short, well‑scoped rule is easier for the AI to apply.
- Include examples and references. The AI responds better when you show what you mean. Add small code snippets or reference existing files with @FileName.ts[15]. For example, provide a "before/after" snippet illustrating correct TypeScript typing[22]).
- Use glob patterns for context‑aware rules. In advanced techniques, you can apply different rules to different parts of your codebase by specifying glob patterns (e.g., src/*/.tsx for React components)[23].
- Introduce conditional logic when appropriate. Rules can express conditional instructions such as "IF creating a new component, use functional components and include interfaces; IF editing an existing component, maintain current patterns and improve accessibility"[24].
- Write clear descriptions for agent‑requested rules. A good description helps the agent decide when to load the rule[12].
- Iterate and refine. After applying rules, observe how the AI behaves and refine your guidelines. The dev community emphasises starting simple, then expanding and updating rules as your project evolves[25].
- Collaborate with your team. Share rule files in version control and make them part of your onboarding process. Encourage new contributors to understand and contribute to the rules[26].
- Consider reliability of rule types. Forum discussions note that "always" and "manual" rules are currently the most reliable. Auto‑select and agent‑requested rules can be flaky, so keep them minimal[27].
Tips from community rule examples
A blog post on best cursor rules suggests starting the file by describing your project, defining coding standards (e.g., use functional components, prefer const, naming conventions), specifying preferred libraries, explaining file structure, outlining performance and testing guidelines, and clarifying error‑handling and documentation practices[28]. These sections help the AI understand your project's context and avoid generic boilerplate. The same article reminds you to update rules as your project evolves[29].
When should you use rules? Advantages and use cases
- Consistent code quality. Without rules, you may find yourself repeatedly reminding the AI about strict typing or architectural patterns. Rules automatically enforce your coding standards, ensuring consistent code style across the project[4].
- Reduced repetition and fewer code reviews. By encoding standards once, you avoid repeating instructions and reduce time spent on basic style issues[30]. Developers can focus on higher‑level design decisions rather than policing formatting.
- Better AI alignment with project requirements. You can specify library choices (e.g., prefer pnpm over npm, use zod for validation) and architectural patterns (repository pattern, dependency injection). The AI will follow these patterns automatically[31].
- Time savings and ROI. According to real‑world metrics, implementing rules can cut setup time, reduce daily coding time by 30–60 minutes per developer and halve code review overhead[32]. Quality improvements include zero any types, consistent component structures and automatic accessibility features[33].
- Team onboarding and knowledge sharing. Rules serve as a living style guide. New team members can understand conventions quickly and contribute rules themselves[26].
Final thoughts
Cursor rules are a powerful tool to humanise your AI assistant and make it work the way you want. By investing a small amount of time to define and refine rules, you unlock consistent code quality, faster development and better collaboration. Start with one simple rule (for example, enforcing React functional components) and gradually expand your rule set as you notice patterns in your project. Use concise, actionable instructions, provide examples, and treat rules as part of your project's documentation. And remember, while the Cursor AI is clever, rules give it the context it needs to shine.
References
[1] [31] Mastering Cursor IDE: 10 Best Practices (Building a Daily Task Manager App) | by Roberto Infante | Medium
[2] [5] [6] [7] [8] [9] [11] [15] [17] [18] [19] Cursor – Rules
https://docs.cursor.com/en/context/rules
[3] [4] [14] [16] [22] [23] [24] [25] [26] [30] [32] [33] Boost Your Development Productivity with Cursor Rules: A Complete Guide - DEV Community
[10] [12] [13] [27] Understanding and Automatically Generating the 4 New Rule Types is AMAZING - Discussions - Cursor - Community Forum
[20] [21] Awesome Cursor Rules You Can Setup for Your Cursor AI IDE Now
https://apidog.com/blog/awesome-cursor-rules/
[28] [29] Best Cursor Rules: Mastering .cursorrules for Cursor IDE
https://dotcursorrules.com/blog/best-cursor-rules-mastering-cursorrules-for-cursor-ide