What are Cursor Rules?
Cursor Rules are configuration files that define how AI should interact with your codebase. They provide context-aware assistance by setting guidelines, constraints, and behavioral patterns for AI interactions.
Three Types of Cursor Rules
1. Global AI Rules (Settings)
Located in Cursor Settings -> General, these rules establish core principles for all AI interactions. They define fundamental behavior patterns and are language-agnostic. Here's a powerful example:
<CORE_PRINCIPLES>
1. EXPLORATION OVER CONCLUSION
- Never rush to conclusions
- Keep exploring until a solution emerges naturally
- Question every assumption and inference
2. DEPTH OF REASONING
- Break down complex thoughts into simple steps
- Embrace uncertainty and revision
- Express thoughts in natural conversation
3. THINKING PROCESS
- Show work-in-progress thinking
- Acknowledge and explore alternatives
- Frequently reassess and revise
</CORE_PRINCIPLES>
<OUTPUT_FORMAT>
Responses must follow:
<CONTEMPLATOR>
- Begin with foundational observations
- Question thoroughly
- Show natural progression
</CONTEMPLATOR>
<FINAL_ANSWER>
- Clear, concise summary
- Note remaining questions
</FINAL_ANSWER>
</OUTPUT_FORMAT>
This structure transforms AI from a simple answer generator into a thoughtful collaborator that explores solutions thoroughly and shows its reasoning process.
Example: Advanced Rules for AI with reasoning
2. Project-Wide Rules (.cursorrules)
A single file in your project root that serves as the primary guidebook for project-specific conventions:
# Framework Standards
- Follow Rails architectural patterns
- Use service objects for business logic
- Reference patterns (@service-objects.md)
# Quality Controls
- Follow RuboCop guidelines
- Enforce test coverage minimums
- Ban SQL queries in views
3. Pattern-Specific Rules (.cursor/rules/*.mdc)
Introduced in Cursor v0.45, these Markdown-based Domain Configuration files target specific file patterns:
---
Description: Rails Controller Standards
Globs: app/controllers/**/*.rb
---
# Guidelines
- Keep controllers skinny
- Use before_action for repeating logic
- Follow RESTful conventions
Note: In the current version, those rules are added to prompt only in Agent mode. Chat and Normal compose are still using .cursorrules
Agentic Approach: The Game Changer
Modern Cursor Rules shifted from passive rule listing to active agent instruction. Example:
You are instructa, a senior Rails developer with superpowers! ⚡
# Agent Behavior
- Read Roadmap.md first
- Plan database schema changes
- Use ViewComponents for complex UI
- Write system tests for critical paths
# Code Standards
- Follow Rails conventions
- Use concerns for shared logic
- Tests must pass before merge
Pro Tips
1. Reference Architecture Using "@ syntax"
Instead of writing lengthy explanations, reference your documentation:
# Bad
- Controllers should use service objects for complex business logic...
# Good
- Follow service object patterns defined in @docs/architecture/services.md
- See implementation examples in @docs/examples/service_objects/
2. Strategic Glob Patterns
Create focused, hierarchical patterns:
# Too broad
Globs: **/*.rb
# Better
Globs:
app/services/**/*.rb
app/models/**/*.rb
!app/models/legacy/**/*.rb # Exclude legacy
3. Combining Rules
Create composable rule sets:
# .cursor/rules/base_ruby.mdc
Description: Base Ruby standards
# .cursor/rules/rails_controllers.mdc
@base_ruby.mdc
Description: Controller-specific rules
Globs: app/controllers/**/*.rb
4. Maintainable Organization
Structure rules by domain:
.cursor/rules/
├── rails8.mdc
├── models/
│ ├── active_record.mdc
│ └── postgresql.mdc
├── controllers/
│ ├── api.mdc
│ └── web.mdc
└── views/
├── erb.mdc
└── components.mdc
The power of Cursor Rules lies in their ability to provide contextual guidance while maintaining flexibility. They transform AI from a generic tool into a project-aware coding partner that understands your architecture, conventions, and goals.
Top comments (2)
Thanks for the post! Cursor project rules are one of the most powerful and under-documented features of Cursor.
I came here searching for more information about whether cursor project rules can be placed in subfolders, as you mentioned in number 4, Maintainable Organization. Unfortunately, according to my testing, this is not supported by Cursor, so this suggestion is incorrect. Please see codekiln/cursor-project-rule-test: Testing the Cursor Project Rule feature for the tests in 0.46.11.
UPDATE: this is now working; see Scan for Project Rules in Subdirectories of .cursor/rules - Feature Requests - Cursor - Community Forum
thank you for this post
noting from docs.cursor.com/context/rules-for-...
"For backward compatibility, you can still use a .cursorrules file in the root of your project. We will eventually remove .cursorrules in the future, so we recommend migrating to the new Project Rules system for better flexibility and control."