Cursor Rules Writing

Purpose

Guide the creation of Cursor IDE rules in .mdc format following best practices for optimal AI context injection and maintainability.

When NOT to Use This Skill

• Writing general documentation (use regular .md files)
• Creating Claude Code skills (use skill-writing skill instead)
• Configuring Cursor IDE settings (not rules)
• Writing code comments or inline documentation

Quick Start Workflow

Step 1: Identify the Context Need

Ask: What specific knowledge does Cursor need for this project?

# Evaluate the gap:
# - What domain knowledge is unique to this project?
# - Which files/patterns need special context?
# - What are developers repeatedly explaining to Cursor?

Only create a rule if:

• ✅ Context is project-specific and non-obvious
• ✅ Applies to multiple files or scenarios
• ✅ Reduces repetitive prompting
• ❌ General programming knowledge (Cursor already knows)
• ❌ One-time context (use chat instead)

Step 2: Choose Rule Type and Trigger

Determine how rule should be applied:

# Always Apply (use sparingly)
alwaysApply: true          # Loaded in every chat session

# File-based triggering (most common)
globs: ["**/*.yaml"]       # Applies when matching files are referenced
alwaysApply: false

# Manual application
# No globs, no alwaysApply  # User invokes with @rule-name.mdc

Step 3: Create MDC File with Frontmatter

# Create rule file in .cursor/rules/ directory
touch .cursor/rules/my-rule.mdc

Start with frontmatter template:

---
description: Brief description of what this rule provides. Include what context it covers and when it applies. Keep under 200 characters for clarity.
globs: ["**/*.ts", "**/*.tsx"]  # Optional: file patterns
alwaysApply: false              # Optional: default false
---

Step 4: Write Focused Content

Keep under 500 lines for optimal performance

# Rule Title

## Overview
One paragraph explaining what context this rule provides.

**Related rules:** See @other-rule.mdc for related context.

---

## Key Concepts
Core information Cursor needs to know.

---

## Examples
Concrete examples with ✅/❌ patterns.

---

## Resources
Links to relevant documentation.

Step 5: Test and Refine

# Test rule application:
# 1. Open file matching glob pattern
# 2. Start Cursor chat
# 3. Verify rule context is loaded
# 4. Check @-mentions work correctly

MDC File Format

Frontmatter Structure

YAML frontmatter with 3 possible fields:

---
description: Clear, concise description of rule context and when to apply it.
globs: ["pattern1", "pattern2"]  # Optional: array of glob patterns
alwaysApply: false               # Optional: boolean (default: false)
---

Field Descriptions:

Field	Required	Type	Description
description	Yes	String	Used by Agent to determine relevance. Be specific about what context is provided and when to use the rule.
globs	No	Array	File patterns for automatic rule application. Omit for manual-only rules.
alwaysApply	No	Boolean	If true, rule loads in every chat. Use sparingly - causes context bloat.

Frontmatter Rules:

• ✅ Description must be clear and specific
• ✅ Use globs for file-based triggering
• ✅ Avoid alwaysApply unless truly universal
• ❌ Don't include title/name field (file name is the identifier)
• ❌ Don't use first or second person in description

Good vs Bad Frontmatter

# ❌ Bad - Vague description, no trigger info
---
description: Helper for working with files.
alwaysApply: true
---

# ❌ Bad - Too broad, will cause context pollution
---
description: Contains all project documentation and guidelines.
alwaysApply: true
---

# ✅ Good - Specific, clear when to apply
---
description: Core guidance for writing production-ready Helm charts including Chart.yaml structure, values.yaml patterns, and template helpers. Apply when creating or modifying Helm chart files.
globs: ["**/Chart.yaml", "**/values*.yaml", "**/templates/**/*.yaml"]
alwaysApply: false
---

# ✅ Good - Manual-only rule, no triggers
---
description: Advanced debugging techniques for React rendering performance issues. Use when diagnosing slow re-renders or unnecessary updates.
---

Glob Patterns

Pattern Syntax

Cursor uses standard glob patterns:

globs:
  - "*.ts"                    # All .ts files in any directory
  - "**/*.tsx"                # All .tsx files recursively
  - "**/tests/**/*"           # All files in tests directories
  - "src/components/*.tsx"    # .tsx files in specific directory
  - "**/{Chart,values}.yaml"  # Multiple specific filenames

Pattern Matching:

• * - Matches any characters except /
• ** - Matches any characters including / (recursive)
• ? - Matches single character
• [abc] - Matches a, b, or c
• {a,b} - Matches pattern a or pattern b

Effective Glob Patterns

# ✅ Good - Specific to chart files
globs: ["**/Chart.yaml", "**/values*.yaml", "**/templates/**/*.yaml"]

# ✅ Good - TypeScript components
globs: ["**/components/**/*.tsx", "**/hooks/**/*.ts"]

# ✅ Good - Configuration files
globs: ["**/*.config.{js,ts}", "**/.*rc", "**/.*rc.json"]

# ❌ Too broad - matches everything
globs: ["**/*"]

# ❌ Too narrow - misses common cases
globs: ["Chart.yaml"]  # Only root, misses nested charts

Testing Glob Patterns

# Use shell glob expansion to test patterns
echo .cursor/rules/*.mdc

# Find files matching pattern
find . -path "**/Chart.yaml"

# Test specific pattern
ls **/values*.yaml

Cross-References

Referencing Other Rules

Use @filename.mdc syntax to reference related rules:

**Related rules:** See @helm-chart-writing.mdc for chart creation, @helm-chart-review.mdc for quality checks, @helm-argocd-gitops.mdc for GitOps integration.

Cross-reference benefits:

• ✅ Keeps rules focused and modular
• ✅ Allows rule composition
• ✅ Reduces duplication
• ✅ User can manually load related context

Best practices:

• Reference related rules at the top (Overview section)
• Use descriptive text: "See @X for Y" not just "@X"
• Don't create circular references
• Test that referenced rules exist

Content Organization

Structure Pattern

---
# Frontmatter
---

# Rule Title

## Overview
Brief introduction paragraph.

**Related rules:** Cross-references here.

---

## Section 1: Core Concepts
Main content with examples.

---

## Section 2: Patterns
Common patterns and anti-patterns.

---

## Resources
External links and documentation.

---

**Maintenance note at bottom**

Section Guidelines

Overview (Required):

• 1-2 sentences explaining rule purpose
• Cross-references to related rules
• Sets expectations for what follows

Core Content (Required):

• Organized into logical sections
• Use --- to separate major sections
• Include concrete examples
• Show good vs bad patterns (✅/❌)

Examples (Highly Recommended):

• Real-world, project-specific examples
• Before/after comparisons
• Common mistakes to avoid

Resources (Optional):

• Links to official documentation
• Internal wiki pages
• Related project files

Content Best Practices

# ✅ Good - Concrete examples
## API Error Handling

All API routes must handle errors consistently:

\`\`\`typescript
// ✅ Good - Proper error handling
app.get('/api/users', async (req, res) => {
  try {
    const users = await db.users.findAll();
    res.json({ data: users });
  } catch (error) {
    logger.error('Failed to fetch users', { error });
    res.status(500).json({ error: 'Internal server error' });
  }
});

// ❌ Bad - No error handling
app.get('/api/users', async (req, res) => {
  const users = await db.users.findAll();
  res.json(users);
});
\`\`\`

# ❌ Bad - Vague instructions
## Error Handling
Make sure to handle errors properly in your code. Always catch exceptions and return appropriate status codes.

File Length Management

500-Line Target

Keep rules under 500 lines for optimal performance:

Rule Size Guide:
├─ Under 300 lines: Ideal (fast loading)
├─ 300-500 lines: Good (acceptable)
├─ 500-700 lines: Consider splitting
└─ Over 700 lines: Must split into multiple rules

Splitting Strategies

Option 1: By topic

helm-expert-skill.mdc (overview, always loaded)
├─ @helm-chart-writing.mdc (creation patterns)
├─ @helm-chart-review.mdc (quality checks)
├─ @helm-argocd-gitops.mdc (GitOps patterns)
└─ @helm-production-patterns.mdc (deployment strategies)

Option 2: By file type

typescript-patterns.mdc
├─ globs: ["**/*.ts"]
├─ Content: General TypeScript patterns

react-components.mdc
├─ globs: ["**/*.tsx"]
├─ Content: React-specific patterns

Option 3: By scenario

database-migrations.mdc
├─ globs: ["**/migrations/**/*"]
├─ Content: Migration patterns

api-testing.mdc
├─ globs: ["**/tests/api/**/*"]
├─ Content: API test patterns

Triggering Mechanisms

Always Apply Rules

---
description: Project architecture and core patterns used across all code.
alwaysApply: true
---

Use when:

• Universal context needed in every chat
• Core architecture principles
• Project-wide conventions

Avoid when:

• Context is file-specific
• Only needed occasionally
• Rule is large (causes bloat)

File-Based Triggering

---
description: Helm chart best practices for Chart.yaml and values.yaml.
globs: ["**/Chart.yaml", "**/values*.yaml"]
alwaysApply: false
---

Use when (most common):

• Context applies to specific file types
• Patterns for certain directories
• Language/framework-specific guidance

Manual Application

---
description: Advanced performance optimization techniques. Use when debugging performance issues.
---

Use when:

• Context only needed on-demand
• Specialized troubleshooting
• Reference documentation
• Rarely needed context

Common Pitfalls

Pitfall 1: Overly Broad Rules

# ❌ Bad - Too much context loaded always
---
description: Everything about the project including architecture, patterns, deployment, testing, and documentation.
alwaysApply: true
---

Solution: Split into focused rules with specific globs.

Pitfall 2: Missing Glob Patterns

# ❌ Bad - Only matches root Chart.yaml
---
globs: ["Chart.yaml"]
---

Solution: Use recursive patterns: ["**/Chart.yaml"]

Pitfall 3: Duplicate Context

# ❌ Bad - Same content in multiple rules
# both-rules.mdc and api-patterns.mdc contain identical API guidelines

Solution: Single source of truth, cross-reference with @.

Pitfall 4: Vague Descriptions

# ❌ Bad
description: Helper for working with files.

# ✅ Good
description: File upload validation patterns including size limits, type checking, and virus scanning. Apply when implementing file upload endpoints.

Pitfall 5: Too Long

# ❌ Bad - 1200 line rule file
# Single file with all project context

Solution: Split into multiple composable rules under 500 lines each.

Quality Checklist

Frontmatter Quality

• Description is clear and specific
• Description explains WHAT context is provided
• Description explains WHEN to apply the rule
• Globs use recursive patterns (**/) where appropriate
• alwaysApply is false unless truly universal
• No unnecessary frontmatter fields

Content Quality

• Under 500 lines (or justified if longer)
• Organized into logical sections with --- separators
• Includes concrete, project-specific examples
• Shows good vs bad patterns (✅/❌)
• Cross-references related rules with @filename.mdc
• No duplicate content from other rules
• Examples use real project code patterns

File Organization

• File stored in .cursor/rules/ directory
• Filename is descriptive and kebab-case
• Filename ends with .mdc extension
• Overview section at top
• Related rules referenced early
• Resources section at bottom

Testing

• Rule loads when expected (check glob patterns)
• @-mention works in chat
• No conflicts with other rules
• Context is relevant and helpful
• File size is reasonable (<500 lines ideal)

Resources

• Cursor Rules Documentation
• Glob Pattern Documentation
• skill-writing skill (for Claude Code skills, not Cursor rules)

Quick Reference

# Create new rule
mkdir -p .cursor/rules
touch .cursor/rules/my-rule.mdc

# Rule template
cat > .cursor/rules/my-rule.mdc << 'EOF'
---
description: Brief description of what this rule provides and when to use it.
globs: ["**/*.ext"]
alwaysApply: false
---

# Rule Title

## Overview
Brief introduction.

**Related rules:** See @other-rule.mdc for related context.

---

## Key Content

Concrete examples and patterns.

---

## Resources

- [Link to docs](https://example.com)
EOF

# Test glob pattern
find . -path "**/Chart.yaml"

# List all rules
ls -la .cursor/rules/*.mdc

---

This skill follows the skill-writing meta skill best practices and should be reviewed quarterly for updates.