MDC Simple Example
A practical guide to understanding and implementing MDC rules
What are MDC Rules?
MDC rules are Markdown files (typically with a .mdc extension) that combine:
- Frontmatter: A YAML section at the top with metadata, such as a description and file patterns (globs) the rule applies to.
- Body: Markdown-formatted instructions, guidelines, or context that an AI can use to understand and interact with a codebase or dataset.
Born in the Cursor IDE's .cursor/rules directory, MDC rules are now envisioned as a flexible, tool-agnostic standard for RAG contexts, where AI models retrieve and apply relevant information dynamically.
Why Use MDC Rules?
- Modularity: Break instructions into small, reusable rules instead of relying on monolithic files.
- Context Awareness: Apply rules selectively based on file patterns or project areas, keeping AI responses focused.
- Portability: The Markdown format ensures compatibility with any AI tool supporting RAG.
- Scalability: Ideal for complex projects, enabling tailored instructions for different components.
Example MDC File
Here's an example of a simple .mdc file:
---
description: Guidelines for handling Python utility functions
patterns:
- "**/utils/*.py"
- "**/helpers/*.py"
---
# Python Utility Functions Guide
This document provides instructions for working with utility functions in Python files located in `utils` or `helpers` directories.
## Key Guidelines
1. **Naming**:
- Use snake_case for function names
- Prefix with `util_` for general-purpose utilities
2. **Documentation**:
- Include a docstring for every function
- Use Google-style Python docstrings
3. **Structure**:
- Keep functions short and focused (under 50 lines)
- Group related utilities in the same file
## Example
```python
def util_format_name(first: str, last: str) -> str:
"""Format a full name from first and last name components.
Args:
first: The first name
last: The last name
Returns:
A formatted full name string
"""
return f"{first.title()} {last.title()}"
This .mdc file includes:
- Frontmatter with a description and file patterns using globs
- Markdown-formatted body with guidelines and an example
- Clear instructions that an AI could use to understand or generate code
The file would typically be saved with a .mdc extension, like python_utils.mdc.