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:

description

globs

alwaysApply

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

**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.