# Cursor Rules Best Practices

**Last Updated:** 2026-01-09

Research findings and best practices for Cursor IDE rule management based on community patterns and official documentation.

## Rule Organization

### File Size Guidelines

- **Target**: <500 lines per rule file (Cursor recommendation)
- **Split large rules**: Break into core/content/patterns when >500 lines
- **Merge small rules**: Combine if <100 lines and closely related

### Naming Conventions

- Use kebab-case: `comparison-pages-core.mdc`
- Be descriptive: `tools-pages-core-design.mdc`
- Group related rules: `tools-pages-*.mdc` for tools page rules

### Rule Structure

**Standard structure:**

1. YAML frontmatter with metadata
2. Rule purpose section
3. When rule applies
4. Key requirements
5. Examples (good/bad)
6. Validation checklist
7. Related documentation

## Glob Pattern Best Practices

### Pattern Specificity

**Too Broad:**

```yaml
globs:
  - v2/**/*.php # Matches ALL PHP files
```

**Too Narrow:**

```yaml
globs:
  - v2/pages/specific_file.php # Only one file
```

**Just Right:**

```yaml
globs:
  - v2/pages/product_*.php # All product pages
  - v2/css/product-pages.css # Related CSS
```

### When to Use Globs

**Use globs when:**

- Rule applies to specific file types
- Rule targets specific directories
- Rule is page-type or component-specific

**Don't use globs when:**

- Rule applies system-wide (performance, date management)
- Rule is referenced by other rules (shared-patterns)
- Rule has `alwaysApply: true` (only global.mdc)

### Pattern Testing

Always test glob patterns:

```bash
python3 scripts/validate-rule-globs.py
python3 scripts/find-rules-for-file.py v2/pages/example.php
```

## Metadata Best Practices

### Required Fields

- **description**: Clear, concise description (10-200 characters)
- **globs**: Array of file patterns (can be empty)
- **alwaysApply**: Boolean (true only for global.mdc)

### Optional Fields

- **relatedRules**: Array of related rule file names
- **relatedDocs**: Array of documentation paths

### Metadata Consistency

- Keep METADATA_INDEX.json in sync with rule files
- Regenerate index after any rule changes
- Validate metadata before committing

## Cross-Reference Best Practices

### Link Paths

**From `.cursor/rules/` to `docs/`:**

```markdown
[docs/ai/cursor-playbook.md](ai/cursor-playbook.md)
```

**From `.cursor/rules/` to other rules:**

```markdown
[comparison-pages-core.mdc](comparison-pages-core.mdc)
```

### Link Validation

- Validate links regularly: `python3 scripts/validate-rule-links.py`
- Fix broken links promptly
- Remove links to non-existent files
- Create missing documentation if needed

## Validation Workflow

### Pre-Commit Checklist

1. Validate rule metadata: `python3 scripts/validate-rules.py`
2. Validate glob patterns: `python3 scripts/validate-rule-globs.py`
3. Validate cross-references: `python3 scripts/validate-rule-links.py`
4. Regenerate index: `python3 scripts/generate-rule-metadata.py`
5. Test rule discovery: `python3 scripts/find-rules-for-file.py <file>`

Or use maintenance script:

```bash
bash scripts/maintain-rules.sh
```

### Automated Validation

- GitHub Action runs on PRs (`.github/workflows/validate-rules.yml`)
- Pre-commit hook validates before commits (optional)
- CI/CD integration for continuous validation

## Rule Discovery Patterns

### How Rules Are Applied

1. **Global rules** (`global.mdc`) always apply
2. **Scoped rules** apply based on file patterns (globs)
3. **Multiple rules** can apply simultaneously (they combine)
4. **More specific rules** take precedence over general ones

### Testing Rule Discovery

```bash
# Test which rules apply to a file
python3 scripts/find-rules-for-file.py v2/pages/compare_planday.php
```

Expected output shows:

- All applicable rules
- Why each rule applies (glob match or alwaysApply)
- Rule combination logic

## Common Patterns

### Page-Type Rules

**Pattern:**

- One core rule for structure/validation
- Optional content/patterns rules for specifics
- Shared patterns referenced by all

**Example:**

- `comparison-pages-core.mdc` - Core structure
- `comparison-pages-content.mdc` - Content patterns
- `shared-patterns.mdc` - Referenced by both

### System Rules

**Pattern:**

- Empty globs array (system-wide)
- Clear description of system scope
- Related rules/docs for navigation

**Example:**

- `performance.mdc` - System-wide performance
- `date-management.mdc` - All files with dates

### Component Rules

**Pattern:**

- Specific glob patterns for components
- HIGH PROTECTION warnings for shared components
- Testing requirements across page types

**Example:**

- `base-components.mdc` - HIGH PROTECTION
- `api-endpoints-core.mdc` - API patterns

## Maintenance Best Practices

### Regular Maintenance

- Run `bash scripts/maintain-rules.sh` weekly
- Review validation reports
- Fix broken links promptly
- Update index after rule changes

### Adding New Rules

1. Copy `_TEMPLATE.mdc`
2. Update frontmatter
3. Add glob patterns
4. Validate
5. Regenerate index
6. Test discovery

### Updating Existing Rules

1. Read existing rule
2. Plan update
3. Edit rule file
4. Validate
5. Regenerate index
6. Test discovery

## Performance Considerations

### Rule File Size

- Keep rules focused (one purpose per rule)
- Split large rules (>500 lines)
- Merge small related rules (<100 lines)

### Glob Pattern Efficiency

- Use specific patterns (avoid `**/*` when possible)
- Test patterns match intended files
- Avoid overlapping patterns unnecessarily

### Index Maintenance

- Regenerate index after changes
- Keep index in sync with files
- Validate index consistency regularly

## Troubleshooting

### Rule Not Applying

**Check:**

1. Glob patterns match file path
2. YAML frontmatter is valid
3. Rule file exists and is readable
4. METADATA_INDEX.json is up-to-date

**Fix:**

```bash
python3 scripts/validate-rules.py
python3 scripts/generate-rule-metadata.py
python3 scripts/find-rules-for-file.py <file>
```

### Glob Pattern Not Matching

**Check:**

1. Pattern syntax (use `*` not regex)
2. File paths match expected format
3. Pattern isn't too specific/narrow

**Fix:**

```bash
python3 scripts/validate-rule-globs.py
# Review output for patterns with no matches
```

### Broken Cross-References

**Check:**

1. Link paths are correct
2. Target files exist
3. Relative paths resolve correctly

**Fix:**

```bash
python3 scripts/validate-rule-links.py
# Fix paths or remove broken links
```

## Related Documentation

- [Rule Maintenance Guide](CURSOR_RULES_MAINTENANCE.md) - Complete maintenance guide
- [Cursor Playbook](cursor-playbook.md) - Workflow guide
- [Rule Hierarchy](rule-hierarchy.md) - Rule architecture