Optimal structure for .mdc rules files

[doug]

@deanrie I’m hoping you can find the best answer for this.

What is the optimal structure within a cursor .mdc rule file?

I ask because I’m seeing 2 very different style/formats for rules floating around right now and they are vastly different.

For instance Geoffrey Huntley has a really good article that has a structure like:

---
description: Cursor Rules Location
globs: *.mdc
---
# Cursor Rules Location

Rules for placing and organizing Cursor rule files in the repository.

<rule>
name: cursor_rules_location
description: Standards for placing Cursor rule files in the correct directory
filters:
  # Match any .mdc files
  - type: file_extension
    pattern: "\\.mdc$"
  # Match files that look like Cursor rules
  - type: content
    pattern: "(?s)<rule>.*?</rule>"
  # Match file creation events
  - type: event
    pattern: "file_create"

actions:
  - type: reject
    conditions:
      - pattern: "^(?!\\.\\/\\.cursor\\/rules\\/.*\\.mdc$)"
        message: "Cursor rule files (.mdc) must be placed in the .cursor/rules directory"

  - type: suggest
    message: |
      When creating Cursor rules:

      1. Always place rule files in PROJECT_ROOT/.cursor/rules/:
         ```
         .cursor/rules/
         ├── your-rule-name.mdc
         ├── another-rule.mdc
         └── ...
         ```

      2. Follow the naming convention:
         - Use kebab-case for filenames
         - Always use .mdc extension
         - Make names descriptive of the rule's purpose

      3. Directory structure:
         ```
         PROJECT_ROOT/
         ├── .cursor/
         │   └── rules/
         │       ├── your-rule-name.mdc
         │       └── ...
         └── ...
         ```

      4. Never place rule files:
         - In the project root
         - In subdirectories outside .cursor/rules
         - In any other location

examples:
  - input: |
      # Bad: Rule file in wrong location
      rules/my-rule.mdc
      my-rule.mdc
      .rules/my-rule.mdc

      # Good: Rule file in correct location
      .cursor/rules/my-rule.mdc
    output: "Correctly placed Cursor rule file"

metadata:
  priority: high
  version: 1.0
</rule>

While @sanjeed5 has posted hundreds of rules that follow a structure like this:

---
description: This rule enforces Next.js App Router best practices in the 'app' directory.
globs: app/**/*.*
---
- Use server components by default
- Implement client components only when necessary
- Utilize the new file-based routing system
- Use layout.js for shared layouts
- Implement loading.js for loading states
- Use error.js for error handling
- Utilize route handlers for API routes

The Cursor team guidance on this would be appreciated.

[deanrie]

Hey, actually, both styles can work well. I believe that we’ll release a guide soon that will help clarify the nuances of project rules.

[tlerbao]

@deanrie Yes, everyone is seeking the best practices for “Project Rule”

[sanjeed5]

@doug thanks for sharing!

i really like the first approach too, going to try it out!

[wsj3]

It would be great if there were some kind of interface for rule entry/edit that optimized the process.

[DelicateAlchemy]

Can confirm

[doug]

@deanrie also, is the cursor dev team aware 2 bugs:

1. the the top section of the .mdc file isn’t visible?

---
description: Cursor Rules Location
globs: *.mdc
---

so if you add a description & glob through the UI, it won’t show up in the file, if you manually add those lines, you have duplicates potentially.

2. Composter agent can’t edit & save .mdc rules. The workaround is to tell it to spit out the entire rule in the chat window and then copy & paste.

[doug]

sharing in this topic @bmadcode topic on creating rules - I’m going to check it out this weekend. After watching his video it appears he’s solved issue #2 that I noted above around properly saving files via the agent which is really exciting.

He’s also extended the filenaming structure that’s become popular and his rules are utilize a 3rd different structure for rule structure/format:

---

description: Use ALWAYS when asked to CREATE A RULE or UPDATE A RULE or taught a lesson from the user that should be retained as a new rule for Cursor
globs: .cursor/rules/*.mdc

Cursor Rules Format

---

description: Use ALWAYS when asked to CREATE A RULE or UPDATE A RULE or taught a lesson from the user that should be retained as a new rule for Cursor
author: BMad
date: 2025-02-17
status: approved
version: 3.1.0

Core Structure

---
description: ACTION when TRIGGER to OUTCOME
globs: *.mdc
tags: [tag1, tag2]  # New: For improved AI categorization
priority: 1-5       # New: For conflict resolution
version: Major.Minor.Patch
---

# Rule Title

## Context
- When to apply this rule
- Prerequisites or conditions

## Requirements
- Concise, actionable items
- Each requirement must be testable

## Examples
<example>
Good concise example with explanation
</example>

<example type="invalid">
Invalid concise example with explanation
</example>

File Organization

Location

• Path: .cursor/rules/
• Extension: .mdc

Naming Convention

PREFIX-name.mdc where PREFIX is:

• 0■■: Core standards
• 1■■: Tool configs
• 3■■: Testing standards
• 1■■■: Language rules
• 2■■■: Framework rules
• 8■■: Workflows
• 9■■: Templates
• _name.mdc: Private rules

Glob Pattern Examples

Common glob patterns for different rule types:

• Core standards: .cursor/rules/*.mdc
• Language rules: src/**/*.{js,ts}
• Testing standards: **/*.test.{js,ts}
• React components: src/components/**/*.tsx
• Documentation: docs/**/*.md
• Configuration files: *.config.{js,json}
• Build artifacts: dist/**/*
• Multiple extensions: src/**/*.{js,jsx,ts,tsx}
• Multiple files: dist//*, docs//*.md

Required Fields

Frontmatter

• description: ACTION TRIGGER OUTCOME format
• globs: glob pattern for files and folders
• tags: Categorization keywords
• priority: 1 (highest) to 5 (lowest)
• version: Semantic versioning

Body

• context: Usage conditions
• requirements: Actionable items
• examples: Both valid and invalid

Formatting Guidelines

• Use Concise Markdown primarily
• XML tags limited to:
• Always indent content within XML or nested XML tags by 2 spaces
• Keep rules as short as possbile
• Use Mermaid syntax if it will be shorter or clearer than describing a complex rule
• Use Emojis where appropriate to convey meaning that will improve rule understanding by the AI Agent
• Keep examples as short as possible to clearly convey the positive or negative example

Version Control when Updating an Existing Rule

• Follow semantic versioning (MAJOR.MINOR.PATCH)
• Document changes in commit messages
• Start at version 1.0.0 for new rule
• Always update the version if modifying an existing rule - use your judgement of the impact of the change to the rule to determin if its a major minor or patch increment.

AI Optimization Tips

1. Use precise, deterministic ACTION TRIGGER OUTCOME format in descriptions
2. Include only essential tags that directly impact rule application
3. Set clear priority levels to resolve conflicts efficiently
4. Provide concise positive and negative example of rule application in practice
5. Optimize for AI context window efficiency
6. Remove any non-essential or redundant information
7. Use standard glob patterns without quotes (e.g., .js, src/**/.ts)

AI Context Efficiency

1. Keep frontmatter description under 120 characters (or less) while maintaining clear intent for rule selection by AI AGent
2. Limit examples to essential patterns only
3. Use hierarchical structure for quick parsing
4. Remove redundant information across sections
5. Maintain high information density with minimal tokens
6. Focus on machine-actionable instructions over human explanations

- NEVER include verbose explanations or redundant context that increases AI token overhead - Keep file as short and to the point as possible BUT NEVER at the expense of sacrificing rule impact and usefulness for the AI Agent.