You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Guidelines and best practices for creating .mdc (Markdown Configuration) files in Cursor, including structure, metadata annotations, and formatting rules
3
+
globs: ["**/*.mdc"]
4
+
---
5
+
6
+
# Cursor MDC File Guidelines
7
+
8
+
@context {
9
+
"type": "documentation",
10
+
"purpose": "cursor_rules",
11
+
"format_version": "1.0.0",
12
+
"supported_content_types": [
13
+
"guidelines",
14
+
"api_docs",
15
+
"examples",
16
+
"implementations"
17
+
]
18
+
}
19
+
20
+
@structure {
21
+
"required_sections": [
22
+
"frontmatter",
23
+
"title",
24
+
"context",
25
+
"content_sections"
26
+
],
27
+
"optional_sections": [
28
+
"version",
29
+
"last_updated",
30
+
"examples",
31
+
"implementations",
32
+
"related_files"
33
+
],
34
+
"recommended_sections": [
35
+
"practical_examples",
36
+
"common_patterns",
37
+
"type_definitions"
38
+
]
39
+
}
40
+
41
+
## File Structure
42
+
43
+
### 1. Frontmatter
44
+
45
+
@frontmatter_rules [
46
+
{
47
+
"id": "position",
48
+
"rule": "Must be at the very top of the file",
49
+
"severity": "error"
50
+
},
51
+
{
52
+
"id": "description",
53
+
"rule": "Single sentence, clear purpose",
54
+
"severity": "error"
55
+
},
56
+
{
57
+
"id": "globs",
58
+
"rule": "Array of relevant file patterns",
59
+
"severity": "error"
60
+
},
61
+
{
62
+
"id": "related_docs",
63
+
"rule": "Optional array of related documentation files - MUST only reference existing files",
64
+
"severity": "error"
65
+
},
66
+
{
67
+
"id": "file_validation",
68
+
"rule": "All referenced files must exist in the workspace",
69
+
"severity": "error"
70
+
}
71
+
]
72
+
73
+
Example frontmatter:
74
+
```yaml
75
+
---
76
+
description: Guidelines for implementing feature X
77
+
globs: ["**/*.{ts,tsx}"]
78
+
related_docs: ["docs/architecture/feature-x.md"]
79
+
---
80
+
```
81
+
82
+
### 2. Metadata Annotations
83
+
84
+
@annotations {
85
+
"syntax": "@annotation_name JSON_content",
86
+
"placement": "Before relevant sections",
87
+
"format": "Valid JSON with proper indentation",
88
+
"types": {
89
+
"context": "Project and document context",
90
+
"rules": "List of rules or requirements",
91
+
"format": "Format specifications",
92
+
"options": "Available options",
93
+
"examples": "Implementation examples",
94
+
"implementations": "Full implementation details",
95
+
"related": "Related documentation or code"
96
+
}
97
+
}
98
+
99
+
### 3. Content Structure
100
+
101
+
@content_rules {
102
+
"headings": {
103
+
"h1": "Single main title",
104
+
"h2": "Major sections",
105
+
"h3": "Subsections",
106
+
"h4": "Detailed points"
107
+
},
108
+
"code_blocks": {
109
+
"syntax": "Always specify language",
110
+
"examples": "Include practical examples",
111
+
"formatting": "Use proper indentation",
112
+
"context": "Add explanatory comments"
113
+
},
114
+
"implementation_blocks": {
115
+
"structure": "Group related implementations",
116
+
"documentation": "Include inline documentation",
117
+
"types": "Specify type information",
118
+
"validation": "Include validation rules"
119
+
}
120
+
}
121
+
122
+
## Best Practices
123
+
124
+
@best_practices {
125
+
"organization": {
126
+
"sections": "Use clear hierarchical structure",
127
+
"annotations": "Place before relevant content",
128
+
"examples": "Include practical examples"
129
+
},
130
+
"formatting": {
131
+
"json": "Properly formatted, valid JSON",
132
+
"markdown": "Clean, consistent spacing",
133
+
"code": "Language-specific syntax highlighting"
134
+
},
135
+
"metadata": {
136
+
"annotations": "Use semantic names",
137
+
"context": "Provide clear scope",
138
+
"versioning": "Include version information"
139
+
},
140
+
"implementation": {
141
+
"examples": "Provide complete, working examples",
142
+
"types": "Include type definitions",
143
+
"validation": "Specify validation rules",
144
+
"error_handling": "Document error cases"
145
+
}
146
+
}
147
+
148
+
## Implementation Guidelines
149
+
150
+
@implementation_rules {
151
+
"code_examples": {
152
+
"completeness": "Must be fully functional",
153
+
"types": "Include all necessary type information",
154
+
"imports": "Show all required imports",
155
+
"context": "Provide setup and usage context"
156
+
},
157
+
"documentation": {
158
+
"inline": "Add explanatory comments",
159
+
"types": "Document type constraints",
160
+
"errors": "Document error conditions",
161
+
"usage": "Show usage patterns"
162
+
}
163
+
}
164
+
165
+
## Example Structure
166
+
167
+
### Basic Example
168
+
```markdown
169
+
---
170
+
description: Example implementation of feature X
171
+
globs: ["src/features/**/*.ts"]
172
+
---
173
+
174
+
# Feature X Implementation
175
+
176
+
@context {
177
+
"type": "implementation",
178
+
"feature": "X",
179
+
"version": "1.0.0"
180
+
}
181
+
182
+
## Overview
183
+
[Feature description]
184
+
185
+
## Implementation
186
+
187
+
@implementation {
188
+
"language": "typescript",
189
+
"dependencies": ["dep1", "dep2"],
190
+
"types": {
191
+
"TypeX": "Description of TypeX"
192
+
}
193
+
}
194
+
195
+
```typescript
196
+
// Implementation code with types and validation
197
+
```
198
+
199
+
## Usage Examples
200
+
[Usage examples with code]
201
+
```
202
+
203
+
### Full Implementation Example
204
+
See the `examples` section in related .mdc files for complete implementation examples.
205
+
206
+
## Common Patterns
207
+
208
+
@patterns {
209
+
"rules_section": {
210
+
"format": "array of objects",
211
+
"properties": ["id", "severity", "description"],
212
+
"example": [
213
+
{
214
+
"id": "rule_name",
215
+
"severity": "error",
216
+
"description": "Clear description"
217
+
}
218
+
]
219
+
},
220
+
"implementation_section": {
221
+
"format": "object with implementation details",
222
+
"required": [
223
+
"language",
224
+
"types",
225
+
"validation"
226
+
],
227
+
"example": {
228
+
"language": "typescript",
229
+
"types": {
230
+
"Type1": "Description"
231
+
},
232
+
"validation": {
233
+
"rule1": "Description"
234
+
}
235
+
}
236
+
}
237
+
}
238
+
239
+
## Examples
240
+
241
+
### Minimal Valid MDC File
242
+
```markdown
243
+
---
244
+
description: A simple example MDC file
245
+
globs: ["**/*.example"]
246
+
---
247
+
248
+
# Example Rules
249
+
250
+
@context {
251
+
"type": "example",
252
+
"version": "1.0.0"
253
+
}
254
+
255
+
## Section One
256
+
257
+
@rules [
258
+
{
259
+
"id": "rule_one",
260
+
"severity": "error",
261
+
"description": "Description of rule one"
262
+
}
263
+
]
264
+
```
265
+
266
+
### Common Section Examples
267
+
268
+
#### Rules Section
269
+
```markdown
270
+
@rules [
271
+
{
272
+
"id": "unique_identifier",
273
+
"severity": "error|warning|info",
274
+
"description": "Clear description of the rule"
275
+
}
276
+
]
277
+
```
278
+
279
+
#### Options Section
280
+
```markdown
281
+
@options {
282
+
"option_name": "What this option does",
283
+
"another_option": "Description of another option"
284
+
}
285
+
```
286
+
287
+
#### Format Section
288
+
```markdown
289
+
@format {
290
+
"base": "Template with {placeholders}",
291
+
"options": ["array", "of", "options"],
292
+
"paths": {
293
+
"key": "value"
294
+
}
295
+
}
296
+
```
297
+
298
+
### Common Mistakes to Avoid
299
+
300
+
@mistakes [
301
+
{
302
+
"id": "missing_frontmatter",
303
+
"wrong": "Starting directly with content",
304
+
"correct": "Include frontmatter at top",
305
+
"reason": "Frontmatter is required for Cursor to properly parse the file"
306
+
},
307
+
{
308
+
"id": "invalid_json",
309
+
"wrong": "Malformed JSON in annotations",
310
+
"correct": "Properly formatted JSON with quotes around keys",
311
+
"reason": "Annotations must contain valid JSON for proper parsing"
312
+
},
313
+
{
314
+
"id": "inconsistent_structure",
315
+
"wrong": "Mixed levels of headings",
316
+
"correct": "Clear hierarchical structure",
317
+
"reason": "Consistent structure helps with readability and parsing"
318
+
},
319
+
{
320
+
"id": "nonexistent_files",
321
+
"wrong": "Referencing files that don't exist in the workspace",
322
+
"correct": "Only reference files that exist and have been verified",
323
+
"reason": "Prevents broken links and maintains documentation integrity"
324
+
}
325
+
]
326
+
327
+
## Validation
328
+
329
+
@validation {
330
+
"required": [
331
+
"Frontmatter must be present and valid",
332
+
"All JSON must be properly formatted",
333
+
"Main title must be present",
334
+
"At least one content section",
335
+
"Complete implementation examples when relevant",
336
+
"All referenced files must exist in the workspace"
0 commit comments