# Cursor Rules Framework

> A Project Organization Guide for Cursor and .mdc files

**Published by:** [Solo Salon](https://solosalon.clinamenic.com/)
**Published on:** 2025-02-15
**URL:** https://solosalon.clinamenic.com/cursor-rules-framework

## Content

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 StructureThe 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 constraintsScope: Entire workspaceContent: Define core architecture, key directories, and main constraintsDescription: Brief overview of project purpose and main functions Globs: /**/*Body text should define:Core project functions/componentsKey directories and their purposesPrimary constraints/rulesKeep under 25 lines, be concise002_cursor_rules.mdc (Required)Purpose: Defines how .mdc files work and should be structuredScope: .cursor/rules directoryContent: 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 documentationScope: .cursor/docs directoryExample Structure:Description: These files contain reference documentation and guides to aid in development efforts Globs: .cursor/docs/**/*Body text should define:Documentation categoriesFile organization rulesCross-referencing conventions004_cursor_tools.mdc (Recommended)Purpose: Manages development tools and scriptsScope: .cursor/tools directoryExample Structure:Description: This folder contains tools and scripts to aid in workspace efforts Globs: .cursor/tools/**/*,.cursor/tools/temp/**/*Detailed Implementation StepsInitial Setup: Create Core Rules:Create each .mdc file through Cursor’s UIStart with 002_cursor_rules.mdc (use template exactly as shown)Then create 001_workspace.mdc (customize to your project)Add 003 and 004 as neededUI Navigation:Access rules through Cursor’s SettingsUse the Description and Globs fields at topUse the larger text editor for body contentSave changes through UI (not direct file edits)Testing Implementation:Verify rules load when accessing relevant filesCheck AI responses reference appropriate rulesEnsure @ tags work for cross-referencesHow Cursor’s AI Uses These RulesHierarchical Understanding:001: Understands overall project scope002: Knows how to interpret other rules003/004: Understands where to find/place resourcesContext Loading:Rules automatically load when relevant files are accessedHigher-numbered rules take precedence@ tags create cross-referencesAI Behavior:Uses rules to guide suggestions and actionsReferences appropriate documentationPlaces new files in correct locationsMaintains project structureBest PracticesKeep rules concise (under 25 lines)Use @ tags for file referencesMake changes through Cursor UI onlyMaintain clear separation of concernsDocument rule changesTest rule effectivenessUse consistent naming conventionsKeep globs specific and targetedTroubleshootingChanges Not Showing:Always make changes through UIIf changes vanish, close CursorSelect “Override” on unsaved changes promptReopen CursorRules Not Loading:Verify file names follow NNN_name.mdc formatCheck glob patterns are correctEnsure no syntax errors in YAMLRemember: 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.ReferencesMy Best Practices for MDC rules and troubleshootingI'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?https://forum.cursor.com

## Publication Information

- [Solo Salon](https://solosalon.clinamenic.com/): Publication homepage
- [All Posts](https://solosalon.clinamenic.com/): More posts from this publication
- [RSS Feed](https://api.paragraph.com/blogs/rss/@solosalon): Subscribe to updates
- [Twitter](https://twitter.com/clinamenic): Follow on Twitter

## Optional

- [Collect as NFT](https://solosalon.clinamenic.com/cursor-rules-framework): Support the author by collecting this post
- [View Collectors](https://solosalon.clinamenic.com/cursor-rules-framework/collectors): See who has collected this post