This guide describes how to implement a structured .mdc rules system in Cursor to enhance AI assistance and project organization.
What Are .mdc Rules?
.mdc files are special configuration files that help Cursor’s AI understand your project structure, conventions, and constraints. They live in the .cursor/rules/ directory and automatically provide context when relevant files are accessed.
Core Framework Structure
The framework consists of four fundamental .mdc files that work together to help Cursor’s AI understand and navigate your project:
001_workspace.mdc (Required)
Purpose: Root-level project definition and constraints
Scope: Entire workspace
Content: Define core architecture, key directories, and main constraints
Description: Brief overview of project purpose and main functions
Globs: /**/*Body text should define:
Core project functions/components
Key directories and their purposes
Primary constraints/rules
Keep under 25 lines, be concise
002_cursor_rules.mdc (Required)
Purpose: Defines how .mdc files work and should be structured
Scope: .cursor/rules directory
Content: Standard template below:
Description: .mdc files describe specific rules for how certain files, file types, and directories are to be understood and used
Globs: .cursor/rules/*.mdcBody text standard template:
.mdc File Structure & Best Practices:
File Naming: NNN_name.mdc (NNN = 001-299)
- 001-099: Core/workspace rules
- 100-199: Integration rules
- 200-299: Pattern rules
Higher numbers take precedence if rules conflict
UI Components:
1. Description (top)
- Brief purpose summary
- Appears in AI context
2. Globs (top)
- Comma-separated list
- Example: /dir1/**/*,/dir2/**/*,/dir3/**/*
- Use standard glob syntax
3. Body Text (this section)
- Keep under 25 lines
- Use concise/shorthand
- Tag files with @
- Focus on key directives
Best Practice: The assistant may propose changes to .mdc files for the user to copy into the UI. The assistant should not attempt direct file edits to .mdc files.003_cursor_docs.mdc (Recommended)
Purpose: Organizes project documentation
Scope: .cursor/docs directory
Example Structure:
Description: These files contain reference documentation and guides to aid in development efforts
Globs: .cursor/docs/**/*Body text should define:
Documentation categories
File organization rules
Cross-referencing conventions
004_cursor_tools.mdc (Recommended)
Purpose: Manages development tools and scripts
Scope: .cursor/tools directory
Example Structure:
Description: This folder contains tools and scripts to aid in workspace efforts
Globs: .cursor/tools/**/*,.cursor/tools/temp/**/*Detailed Implementation Steps
Initial Setup:
Create Core Rules:
Create each .mdc file through Cursor’s UI
Start with 002_cursor_rules.mdc (use template exactly as shown)
Then create 001_workspace.mdc (customize to your project)
Add 003 and 004 as needed
UI Navigation:
Access rules through Cursor’s Settings
Use the Description and Globs fields at top
Use the larger text editor for body content
Save changes through UI (not direct file edits)
Testing Implementation:
Verify rules load when accessing relevant files
Check AI responses reference appropriate rules
Ensure @ tags work for cross-references
How Cursor’s AI Uses These Rules
Hierarchical Understanding:
001: Understands overall project scope
002: Knows how to interpret other rules
003/004: Understands where to find/place resources
Context Loading:
Rules automatically load when relevant files are accessed
Higher-numbered rules take precedence
@ tags create cross-references
AI Behavior:
Uses rules to guide suggestions and actions
References appropriate documentation
Places new files in correct locations
Maintains project structure
Best Practices
Keep rules concise (under 25 lines)
Use @ tags for file references
Make changes through Cursor UI only
Maintain clear separation of concerns
Document rule changes
Test rule effectiveness
Use consistent naming conventions
Keep globs specific and targeted
Troubleshooting
Changes Not Showing:
Always make changes through UI
If changes vanish, close Cursor
Select “Override” on unsaved changes prompt
Reopen Cursor
Rules Not Loading:
Verify file names follow NNN_name.mdc format
Check glob patterns are correct
Ensure no syntax errors in YAML
Remember: This framework is adaptable. While 002-004 can remain fairly standard, 001_workspace.mdc should be thoroughly customized to your project’s specific needs and constraints.
References
My Best Practices for MDC rules and troubleshooting
I've been exploring how Cursor's MDC rules work by experimenting with the AI. I wanted to share what I learned by feeding different files into context and asking the AI what it saw. mdc_rule_system Situation: What's the current state of MDC rules?
