mdc-files

MDC Files Best Practices

This guide covers conventions and best practices for creating and maintaining .mdc cursor rules files that provide context and guidance to AI assistants.

File Structure

Frontmatter Block

⚠️ ALWAYS include YAML frontmatter at the top of every .mdc file:

---
description: Brief description of what this rules file covers
globs: *.ext,*.pattern
alwaysApply: false
---

Frontmatter Properties:

• ✅ description: Short, clear description of the file's purpose (one line)
• ✅ globs: Comma-separated list of file patterns that trigger this rule (e.g., *.test.ts,*.test.tsx)
• ✅ alwaysApply: Boolean (true or false) - whether this rule applies to all contexts

✅ DO: Use specific glob patterns

---
description: Jest testing best practices and patterns for unit tests
globs: *.test.ts,*.test.tsx
alwaysApply: false
---

❌ DON'T: Use vague descriptions or missing properties

---
description: Some rules
globs:
alwaysApply: false
---

Document Title

✅ ALWAYS start content with a single H1 heading:

# Document Title

Introduction paragraph explaining the document's purpose and scope.

Best practices:

• ✅ Use a clear, descriptive title
• ✅ Match the title to the description in frontmatter
• ✅ Include a brief introduction after the H1
• ❌ Never use multiple H1 headings in a single document

Markdown Structure

Heading Hierarchy

✅ Use proper heading levels (H1 → H2 → H3 → H4):

# Main Title (H1)

## Major Section (H2)

### Subsection (H3)

#### Sub-subsection (H4)

##### Rarely needed (H5)

Best practices:

• ✅ Use H1 for document title only
• ✅ Use H2 for major sections
• ✅ Use H3 for subsections within major sections
• ✅ Maintain consistent nesting (don't skip levels)
• ❌ Never jump from H2 to H4 without H3

Visual Indicators

✅ Use emoji symbols for emphasis and clarity:

• ✅ Checkmark: Recommended patterns, correct examples
• ❌ Cross mark: Anti-patterns, incorrect examples
• ⚠️ Warning: Critical rules, important notes
• 🥇 Medal: Priority or ranking indicators