Cursor rule

1---
2description: Guidelines and best practices for creating .mdc (Markdown Configuration) files in Cursor, including structure, metadata annotations, and formatting rules
3globs: **/*.mdc
4alwaysApply: false
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 
73Example frontmatter:
74```yaml
75---
76description: Guidelines for implementing feature X
77globs: ["**/*.{ts,tsx}"]
78related_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---
170description: Example implementation of feature X
171globs: ["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
204See 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---
244description: A simple example MDC file
245globs: ["**/*.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"
337    ],
338    "recommended": [
339        "Version information",
340        "Last updated date",
341        "Clear examples",
342        "Proper code formatting",
343        "Type definitions",
344        "Validation rules",
345        "Verify file existence before referencing"
346    ]
347}
348 
349@version "1.1.0"
350@last_updated "2024-03-19"