Back to Resources

Best Practices for Using MDC Files in Cursor

Learn how to effectively create and use MDC files to enhance your AI development workflow.

What are MDC Files?

MDC files are configuration files that allow you to set rules and guidelines for Cursor's AI. Located in the .cursor/rules directory of your project, they use markdown format with frontmatter to specify metadata like the rule's purpose and scope. MDC files help tailor the AI's suggestions to your codebase, improving its accuracy and relevance.

Why Use MDC Files?

  • Context-Aware Assistance: MDC files provide the AI with project-specific context, leading to better suggestions.
  • Granular Control: Use glob patterns to apply rules to specific file types or directories.
  • Improved Organization: Replace the older .cursorrules system with modular, well-structured files.

Creating and Structuring MDC Files

Step 1: Set Up the .cursor/rules Directory

Create a .cursor/rules directory in your project's root to store MDC files:

mkdir -p .cursor/rules

Step 2: Create a New MDC File

Add a new file with a .mdc extension in .cursor/rules. Use a descriptive name, such as typescript-rules.mdc:

touch .cursor/rules/typescript-rules.mdc

Step 3: Structure of an MDC File

An MDC file has two parts:

  1. Frontmatter: Metadata enclosed in --- defining the rule's purpose and scope.
  2. Rule Content: Markdown-formatted rules for the AI.

Frontmatter Best Practices

Include these fields:

  • description: A concise summary of the rule's purpose.
  • globs: Glob patterns specifying which files the rule applies to.
---
description: TypeScript coding standards
globs: **/*.ts, **/*.tsx
---

Using Glob Patterns Effectively

Glob patterns define which files an MDC rule targets. Follow these tips:

  • Be Specific: Use **/*.ts for TypeScript files or src/*.jsx for React files in a directory.
  • Combine Patterns: List multiple globs (e.g., **/*.ts, **/*.tsx) for broader coverage.
  • Test Patterns: Verify they match the intended files.

Common Glob Examples:

  • **/*.ts: All .ts files in the project.
  • src/components/*.jsx: All .jsx files in src/components.
  • *.md: All markdown files in the root.

How the AI Uses MDC Files

When editing a file, Cursor's AI includes relevant MDC files in its context based on matching glob patterns. For example, editing a .ts file triggers rules from an MDC file with **/*.ts in its globs. This ensures tailored assistance for your current task.

Writing Effective Rules

To make rules impactful:

  • Focus on Key Points: Include only critical guidelines.
  • Use Clear Language: Avoid ambiguity with simple, direct phrasing.
  • Leverage Markdown: Use lists for multiple rules and code blocks for examples.
  • Link to Context: Reference other files with @ for additional details.
---
description: React component guidelines
globs: **/*.jsx, **/*.tsx
---

# React Rules

- Use functional components
- Define prop types
- See @style-guide.md for details

Best Practices for Organizing MDC Files

  • Logical Grouping: Combine related rules (e.g., typescript-rules.mdc) or split by purpose (e.g., testing-rules.mdc).
  • Clear Descriptions: Use meaningful frontmatter descriptions.
  • Regular Updates: Revise rules as your project changes.
  • Avoid Duplication: Keep rules unique across files.

Common Pitfalls and Troubleshooting

Common Issues:

  • Missing Globs: Rules won't apply without proper globs.
  • Overly Long Rules: Too much text can exceed the AI's context limit.
  • Incorrect Globs: Mismatched patterns miss intended files.

Troubleshooting:

  • Ensure files are in .cursor/rules.
  • Validate glob patterns.
  • Align descriptions with rule content.

Real-World Examples

Example 1: TypeScript Rules

---
description: TypeScript coding standards
globs: **/*.ts, **/*.tsx
---

# TypeScript Rules

- Use 'const' for immutable variables
- Prefer arrow functions
- Specify return types
- Use interfaces for types

Example 2: Testing Conventions

---
description: Testing conventions
globs: **/*.test.ts
---

# Testing Rules

- Use Jest for unit tests
- One module per test file
- Aim for 80%+ coverage

Migrating from .cursorrules to MDC Files

To switch from the older .cursorrules system:

  1. Divide .cursorrules content into separate MDC files.
  2. Add frontmatter with description and globs to each file.
  3. Delete .cursorrules after migrating.

MDC files offer greater flexibility and are the preferred method moving forward.

Conclusion

MDC files empower you to customize Cursor's AI for your project's unique needs. By creating concise, well-structured rules and following these best practices, you'll enhance your coding efficiency and accuracy. Keep your MDC files organized and up-to-date to fully harness Cursor's capabilities.