Back to Resources

Introducing and Using .mdc Files

Learn how to effectively use .mdc files in tools like Cursor to enhance your AI development workflow.

What are .mdc Files?

.mdc files (Markdown Domain Configuration files) are configuration files used in Cursor to define rules and guidelines for the AI to follow when interacting with your codebase. Stored in the .cursor/rules directory within your project, these files provide context-aware assistance by setting conventions, constraints, and behavioral patterns for AI interactions.

Why Use .mdc Files?

  • Context-Aware Assistance: .mdc files help the AI understand your project's structure, conventions, and constraints, leading to more accurate and relevant suggestions.
  • Granular Control: Unlike the older .cursorrules system, .mdc files can target specific file types or directories using glob patterns.
  • Improved Organization: Multiple .mdc files allow you to organize rules by purpose or scope, making them easier to manage and update.

The Shift from .cursorrules to .mdc Files

In earlier versions of Cursor, rules were defined in a single .cursorrules file located in the project root. While functional, this approach lacked flexibility. With the introduction of .mdc files in Cursor v0.45, you can now create multiple rule files that apply to specific parts of your project, offering greater precision and control.

Key Differences:

  • .cursorrules: A single, global rule file for the entire project.
  • .mdc Files: Multiple files with targeted rules based on glob patterns.

Recommendation: If you're still using .cursorrules, consider migrating to .mdc files for enhanced flexibility.

Creating and Structuring .mdc Files

Step 1: Set Up the .cursor/rules Directory

First, create a .cursor/rules directory in your project's root to store your .mdc files:

mkdir -p .cursor/rules

Step 2: Create a New .mdc File

Inside .cursor/rules, create a new file with a .mdc extension. Choose a descriptive name that reflects the rule's purpose, such as typescript-rules.mdc:

touch .cursor/rules/typescript-rules.mdc

Step 3: Structure of an .mdc File

An .mdc file has two main sections:

  • Frontmatter: Metadata defining the rule's purpose and scope.
  • Rule Content: The actual rules written in markdown.

Frontmatter Example

The frontmatter is enclosed in triple dashes (---) and includes:

  • description: A brief 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 determine which files an .mdc rule applies to. Here are some examples:

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

Tip: Combine multiple globs in the globs field with commas (e.g., **/*.ts, **/*.tsx).

How the AI Uses .mdc Files

When you use Cursor's AI features (like chat or composer), relevant .mdc files are automatically included in the AI's context based on the files you're editing. For example:

  • Editing a .ts file triggers any .mdc file with a matching glob (e.g., **/*.ts).
  • In agent mode, the AI may selectively apply rules based on the task.

This ensures the AI provides assistance tailored to your current context.

Writing Effective Rules

To maximize the usefulness of .mdc files:

  • Keep It Concise: Focus on key directives to avoid overwhelming the AI.
  • Leverage Markdown: Use markdown features like lists and code blocks for clarity.
  • Reference Other Files: Use @ to link to additional context (e.g., @style-guide.md).

Example

For a React project:

---
description: React component guidelines
globs: **/*.jsx, **/*.tsx
---

# React Rules

- Use functional components over class components
- Implement proper prop types
- Follow the team's style guide @style-guide.md

Best Practices for .mdc Files

  • Logical Organization: Group related rules in one file or split them across multiple files by purpose.
  • Clear Descriptions: Make the description field meaningful for better AI decision-making.
  • Regular Updates: Revise rules as your project evolves.
  • Avoid Redundancy: Don't duplicate rules across files to prevent confusion.

Common Pitfalls and Troubleshooting

  • Missing Globs: Rules won't apply without proper glob patterns.
  • Verbose Rules: Too much text may exceed the AI's context limit.
  • Incorrect Globs: Test patterns to ensure they match intended files.

Troubleshooting

  • Check that the .mdc file is in .cursor/rules.
  • Verify glob patterns match your files.
  • Ensure the description aligns with your task.

Real-World Examples

Example 1: TypeScript Rules

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

# TypeScript Rules

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

Example 2: Testing Conventions

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

# Testing Rules

- Use Jest for unit tests
- Cover one module per test file
- Target 80%+ code coverage
- Follow TDD where possible

Migrating from .cursorrules

To switch from .cursorrules to .mdc files:

  1. Split your .cursorrules into separate .mdc files by scope.
  2. Add frontmatter with description and globs to each file.
  3. Remove .cursorrules once migrated.

Note: While .cursorrules is still supported, .mdc files are the future.

Conclusion

.mdc files empower you to customize Cursor's AI to your project's needs, offering precise, context-aware assistance. By defining targeted rules, you can enforce standards, guide framework usage, and boost productivity. Follow this tutorial's steps and best practices to get started, and keep an eye on Cursor's documentation for updates as this feature evolves.