Cursor rule

1---
2description: Use when user asks to create or update *.mdc files
3globs: **/*.mdc
4alwaysApply: false
5---
6# MDC File Format Guide
7 
8MDC (Markdown Configuration) files are used by Cursor to provide context-specific instructions to AI assistants. This guide explains how to create and maintain these files properly.
9 
10## File Structure
11 
12Each MDC file consists of two main parts:
13 
141. **Frontmatter** - Configuration metadata at the top of the file
152. **Markdown Content** - The actual instructions in Markdown format
16 
17### Frontmatter
18 
19The frontmatter must be the first thing in the file and must be enclosed between triple-dash lines (`---`). Configuration should be based on the intended behavior:
20 
21```
22---
23description: Brief description of what the rule does
24globs: **/*.ts, **/*.ts  # Optional: Comma-separated list, not an array
25alwaysApply: false       # Set to true for global rules
26---
27```
28 
29> **Important**: Despite the appearance, the frontmatter is not strictly YAML formatted. The `globs` field is a comma-separated list and should NOT include brackets `[]` or quotes `"`.
30 
31#### Guidelines for Setting Fields
32 
33- **description**: Should be agent-friendly and clearly describe when the rule is relevant. Format as `<topic>: <details>` for best results.
34- **globs**:
35  - If a rule is only relevant in very specific situations, leave globs empty so it's loaded only when applicable to the user request.
36  - If the only glob would match all files (like `**/*`), leave it empty and set `alwaysApply: true` instead.
37  - Otherwise, be as specific as possible with glob patterns to ensure rules are only applied with relevant files.
38- **alwaysApply**: Use sparingly for truly global guidelines.
39 
40#### Glob Pattern Examples
41 
42- `**/*.js` - All JavaScript files
43- `src/**/*.jsx` - All JSX files in the src directory
44- `**/components/**/*.vue` - All Vue files in any components directory
45 
46### Markdown Content
47 
48After the frontmatter, the rest of the file should be valid Markdown:
49 
50```markdown
51# Title of Your Rule
52 
53## Section 1
54- Guidelines and information
55- Code examples
56 
57## Section 2
58More detailed information...
59```
60 
61## Special Features
62 
63### File References
64 
65You can reference other files from within an MDC file using the markdown link syntax:
66 
67```
68[rule-name.mdc](mdc:location/of/the/rule.mdc)
69```
70 
71When this rule is activated, the referenced file will also be included in the context.
72 
73### Code Blocks
74 
75Use fenced code blocks for examples:
76 
77```markdown
78```javascript
79// Example code
80function example() {
81  return "This is an example";
82}
83```
84```
85 
86## Best Practices
87 
881. **Clear Organization**
89   - Use numbered prefixes (e.g., `01-workflow.mdc`) for sorting rules logically
90   - Place task-specific rules in the `tasks/` subdirectory
91   - Use descriptive filenames that indicate the rule's purpose
92 
932. **Frontmatter Specificity**
94   - Be specific with glob patterns to ensure rules are only applied in relevant contexts
95   - Use `alwaysApply: true` for truly global guidelines
96   - Make descriptions clear and concise so AI knows when to apply the rule
97 
983. **Content Structure**
99   - Start with a clear title (H1)
100   - Use hierarchical headings (H2, H3, etc.) to organize content
101   - Include examples where appropriate
102   - Keep instructions clear and actionable
103 
1044. **File Size Considerations**
105   - Keep files focused on a single topic or closely related topics
106   - Split very large rule sets into multiple files and link them with references
107   - Aim for under 300 lines per file when possible
108 
109## Usage in Cursor
110 
111When working with files in Cursor, rules are automatically applied when:
112 
1131. The file you're working on matches a rule's glob pattern
1142. A rule has `alwaysApply: true` set in its frontmatter
1153. The agent thinks the rule's description matches the user request
1164. You explicitly reference a rule in a conversation with Cursor's AI
117 
118## Creating/Renaming/Removing Rules
119 
120- When a rule file is added/renamed/removed, update also the list under [010-workflow.mdc](mdc:.cursor/rules/010-workflow.mdc).
121- When changes are made to multiple `mdc` files from a single request, review also [999-mdc-format.mdc](mdc:.cursor/rules/999-mdc-format.mdc) to consider whether to update it too.
122 
123## Updating Rules
124 
125When updating existing rules:
126 
1271. Maintain the frontmatter format
1282. Keep the same glob patterns unless intentionally changing the rule's scope
1293. Update the description if the purpose of the rule changes
1304. Consider whether changes should propagate to related rules
131 
132```