# Cursor Rules Maintenance Guide

**Last Updated:** 2026-04-04

Complete guide for maintaining and updating Cursor rule files (`.mdc` files) in `.cursor/rules/`.

## Overview

Cursor rules guide AI agent behavior by providing context-specific instructions. This guide covers:

- How to add new rules
- How to update existing rules
- Glob pattern guidelines
- Cross-reference best practices
- Validation workflow
- Testing new rules

### Rule vs doc vs skill vs subagent (where to put guidance)


| Mechanism                                 | Use for                                                                                    | Ordio examples                                                                       |
| ----------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| **Rule (`.mdc` + globs)**                 | Constraints that must apply when editing matching paths                                    | `comparison-pages-*.mdc`, `blog-json-edit-prohibition.mdc`                           |
| **Rule (no globs, not alwaysApply)**      | Optional “read when relevant” pointers; keep `**description` short** (agent-decided rules) | `mcp-usage.mdc`, `date-management.mdc`                                               |
| **Rule (`alwaysApply: true`)**            | Invariants every chat; **only** `[global.mdc](../../.cursor/rules/global.mdc)`             | Docker, minify, `/kostenlos-testen` links, base-component warning                    |
| **Doc (`docs/`**)**                       | Long playbooks, tables, SEO narratives; attach with `@`                                    | `[agent-workflows.md](agent-workflows.md)`, content hubs                             |
| **Skill (`.cursor/skills/.../SKILL.md`)** | User-invoked or domain routers; link to docs/rules—**no** long policy copies               | `ordio-blog-content-router`                                                          |
| **Subagent (Cursor product)**             | Isolate noisy or parallel work (explore repo, long shell output, browser)                  | Built-in Explore, Bash, Browser — [official docs](https://cursor.com/docs/context/subagents) |


Official product docs: `[CURSOR_OFFICIAL_DOCS_REFERENCE.md](CURSOR_OFFICIAL_DOCS_REFERENCE.md)`.

## Rule File Structure

Each rule file follows this structure:

```yaml
---
description: Brief description of rule purpose
globs:
  - v2/pages/pattern_*.php
  - v2/css/pattern-*.css
alwaysApply: false
relatedRules: []
relatedDocs: []
---

## Rule Purpose
[What this rule covers]

## When This Rule Applies
[File patterns, task types]

## Key Requirements
[Main guidance]

## Examples
[Code examples]

## Related Documentation
[Links to guides, docs]
```

### Required Fields

- **description**: Non-empty string describing the rule's purpose
- **globs**: Array of file patterns (can be empty for system-wide rules)
- **alwaysApply**: Boolean (true only for `global.mdc`)

### Optional Fields

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

## Adding New Rules

### Step 1: Determine Rule Type

**Page-Type Rule**: Applies to specific file patterns (e.g., `v2/pages/product_*.php`)

- Should have globs matching file patterns
- `alwaysApply: false`

**System-Wide Rule**: Applies to all files or specific systems

- Empty globs array `[]`
- `alwaysApply: false` (unless it's the global rule)

**Global Rule**: Always applies to all tasks

- Empty globs array `[]`
- `alwaysApply: true`
- Only `global.mdc` should have this

### Step 2: Create Rule File

1. Copy `.cursor/rules/_TEMPLATE.mdc` as starting point
2. Update frontmatter with correct metadata
3. Add rule content following existing patterns
4. Include examples and related documentation links

### Step 3: Add Glob Patterns

**When to use globs:**

- Rule applies to specific file types (pages, components, APIs)
- Rule targets specific directories or patterns

**When NOT to use globs:**

- Rule applies system-wide (performance, date management)
- Rule is referenced by other rules (shared-patterns)

**Glob Pattern Examples:**

```yaml
# Single pattern
globs:
  - v2/pages/product_*.php

# Multiple patterns
globs:
  - v2/pages/tools_*.php
  - v2/css/tools-pages.css

# Recursive patterns
globs:
  - v2/systems/excel-template-generator/**/*.php
  - v2/systems/excel-template-generator/**/*.json

# Multiple file types
globs:
  - v2/admin/seo-dashboard/**/*.php
  - v2/admin/seo-dashboard/**/*.js
  - v2/admin/seo-dashboard/**/*.css
```

### Step 4: Validate Rule

Run validation scripts:

```bash
# Validate rule metadata
python3 scripts/validate-rules.py --write-report

# Validate glob patterns
python3 scripts/validate-rule-globs.py --write-report

# Validate cross-references
python3 scripts/validate-rule-links.py --write-report

# Test rule discovery
python3 scripts/find-rules-for-file.py v2/pages/your_file.php
```

### Step 5: Regenerate Metadata Index

After adding/updating rules, regenerate the index:

```bash
python3 scripts/generate-rule-metadata.py
```

This updates `docs/ai/METADATA_INDEX.json` with current rule metadata.

## Updating Existing Rules

### When to Update

- Patterns change for existing page types
- New requirements emerge
- Best practices evolve
- Common pitfalls identified

### Update Process

1. **Read existing rule** to understand current guidance
2. **Plan update**: What needs to change and why?
3. **Edit rule file**: Update `.cursor/rules/[rule].mdc`
4. **Validate**: Run validation scripts
5. **Regenerate index**: Update `docs/ai/METADATA_INDEX.json`
6. **Test**: Verify rule discovery works correctly
7. **Document**: Update related documentation if needed

### Common Updates

**Adding new glob patterns:**

```yaml
globs:
  - v2/pages/existing_*.php
  - v2/pages/new_*.php  # Added
```

**Updating description:**

```yaml
description: Updated description with new requirements
```

**Adding related rules:**

```yaml
relatedRules:
  - existing-rule.mdc
  - new-related-rule.mdc  # Added
```

## Glob Pattern Guidelines

### 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
```

### Pattern Testing

Test glob patterns before committing:

```bash
# Test if pattern matches files
python3 scripts/validate-rule-globs.py

# Test rule discovery for specific file
python3 scripts/find-rules-for-file.py v2/pages/product_schichtplan_neu.php
```

### Common Patterns


| Pattern                  | Matches                   | Example                                                                                     |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `v2/pages/*.php`         | All PHP files in pages    | `v2/pages/landingpage.php`                                                                  |
| `v2/pages/product_*.php` | Product pages             | `v2/pages/product_schichtplan_neu.php` (live Schichtplan); archived `product_shiftplan.php` |
| `v2/pages/compare_*.php` | Comparison pages          | `v2/pages/compare_planday.php`                                                              |
| `v2/api/*.php`           | API endpoints             | `v2/api/lead-capture.php`                                                                   |
| `v2/base/*.php`          | Base components           | `v2/base/header.php`                                                                        |
| `v2/**/*.php`            | All PHP files recursively | `v2/pages/deep/nested/file.php`                                                             |
| `v2/css/*-pages.css`     | Page-specific CSS         | `v2/css/product-pages.css`                                                                  |


## Cross-Reference Best Practices

### Linking to Documentation

**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)
```

**From `.cursor/rules/` to project files:**

```markdown
[v2/pages/compare_template.php](../../v2/pages/compare_template.php)
```

### Path Resolution

- **Rule to docs**: `../../docs/` (go up 2 levels from `.cursor/rules/`)
- **Rule to rule**: Same directory, use filename only
- **Rule to project files**: `../../v2/` or `../../scripts/`

### Validating Links

Run link validator regularly:

```bash
python3 scripts/validate-rule-links.py --write-report
```

Fix broken links:

1. Check if file exists at resolved path
2. Update path if incorrect
3. Remove link if file doesn't exist and isn't needed
4. Create missing documentation if needed

## Validation Workflow

### Pre-Push Checklist

**Before pushing** changes to `.cursor/rules/`:

1. Run `make rules` to validate and regenerate `docs/ai/METADATA_INDEX.json`
2. Commit the updated `docs/ai/METADATA_INDEX.json` with your rule changes

The Validate Cursor Rules GitHub Action will fail if the index is out of sync. See `docs/development/DEV_TOOLING.md` for workflow details.

### Pre-Commit Validation

Before committing rule changes:

```bash
# Run all validations and regenerate index (recommended)
make rules

# Or run individually:
# 1. Validate rule metadata
python3 scripts/validate-rules.py --write-report

# 2. Validate glob patterns
python3 scripts/validate-rule-globs.py --write-report

# 3. Validate cross-references
python3 scripts/validate-rule-links.py --write-report

# 4. Regenerate metadata index
python3 scripts/generate-rule-metadata.py

# 5. Test rule discovery
python3 scripts/find-rules-for-file.py v2/pages/example.php
```

### Automated Validation

Use the maintenance script for all validations:

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

This runs all validations and regenerates the index.

### Integrity Command

Use a single command for full integrity checks (rules + skill references):

```bash
make cursor-integrity
```

## Testing New Rules

### Test Rule Discovery

Verify rules apply to intended files:

```bash
# Test specific file
python3 scripts/find-rules-for-file.py v2/pages/product_schichtplan_neu.php

# Should show:
# - global.mdc (always applies)
# - product-pages.mdc (matches glob pattern)
# - shared-patterns.mdc (if referenced)
```

### Test Rule Combinations

When multiple rules apply, verify they combine correctly:

1. Check rule discovery output
2. Verify no conflicting guidance
3. Test with actual Cursor agent
4. Review generated plans

### Test Edge Cases

- Files matching multiple glob patterns
- Files matching no patterns (should only get global.mdc)
- System-wide rules (empty globs)

## Rule Organization

### File Naming

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

### Rule Size

- **Target**: <500 lines per Cursor best practices
- **Split large rules**: Break into core/content/patterns
- **Merge small rules**: Combine if <100 lines and related

### Rule Relationships

Use `relatedRules` to indicate relationships:

```yaml
relatedRules:
  - comparison-pages-core.mdc
  - comparison-pages-content.mdc
```

## Troubleshooting

### Rule Not Applying

**Symptoms**: Rule doesn't appear in discovery output

**Solutions**:

1. Check glob patterns match file path
2. Verify rule file has valid YAML frontmatter
3. Run `validate-rules.py` to check for errors
4. Regenerate `docs/ai/METADATA_INDEX.json`

### Glob Pattern Not Matching

**Symptoms**: Pattern exists but doesn't match files

**Solutions**:

1. Test pattern with `validate-rule-globs.py`
2. Check pattern syntax (use `*` not regex)
3. Verify file paths match expected format
4. Test with `find-rules-for-file.py`

### Broken Cross-References

**Symptoms**: Link validator reports broken links

**Solutions**:

1. Check resolved path exists
2. Fix relative path (use `../../docs/` from `.cursor/rules/`)
3. Remove link if file doesn't exist
4. Create missing documentation if needed

### Metadata Index Out of Sync

**Symptoms**: Index shows different metadata than rule files

**Solutions**:

1. Run `generate-rule-metadata.py` to regenerate
2. Check for YAML parsing errors
3. Verify all rule files have valid frontmatter

## Best Practices Summary

1. **Always validate** before committing rule changes
2. **Test glob patterns** with validation scripts
3. **Keep rules focused** - one purpose per rule
4. **Use descriptive names** - kebab-case, clear purpose
5. **Document relationships** - use relatedRules and relatedDocs
6. **Keep rules concise** - <500 lines when possible
7. **Update index** after changes
8. **Fix broken links** promptly
9. **Test rule discovery** for new patterns
10. **Follow existing patterns** - consistency matters

## Related Documentation

- [Cursor Playbook](cursor-playbook.md) - Complete workflow guide
- [Rule Hierarchy](rule-hierarchy.md) - Rule architecture and decision tree
- [Rule Discovery Patterns](RULE_DISCOVERY_PATTERNS.md) - File path → rule mapping
- [Rule to Documentation Mapping](RULE_TO_DOC_MAPPING.md) - Bidirectional mapping

## Validation Scripts Reference


| Script                                | Purpose                   | Usage                                                                                                    |
| ------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------- |
| `validate-rules.py`                   | Validate rule metadata    | `python3 scripts/validate-rules.py --write-report`                                                       |
| `validate-rule-globs.py`              | Validate glob patterns    | `python3 scripts/validate-rule-globs.py --write-report`                                                  |
| `validate-rule-links.py`              | Validate cross-references | `python3 scripts/validate-rule-links.py --write-report`                                                  |
| `validate-skill-links.py`             | Validate skill references | `python3 scripts/validate-skill-links.py --write-report`                                                 |
| `generate-rule-metadata.py`           | Regenerate index          | `python3 scripts/generate-rule-metadata.py`                                                              |
| `ai/cursor-optimization-benchmark.py` | Baseline KPIs snapshot    | `python3 scripts/ai/cursor-optimization-benchmark.py --output docs/ai/CURSOR_OPTIMIZATION_BASELINE.json` |
| `find-rules-for-file.py`              | Test rule discovery       | `python3 scripts/find-rules-for-file.py <file>`                                                          |
| `maintain-rules.sh`                   | Run all validations       | `bash scripts/maintain-rules.sh`                                                                         |


## Quick Reference

**Add new rule:**

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

**Update existing rule:**

1. Edit rule file
2. Validate
3. Regenerate index
4. Test discovery

**Fix broken links:**

1. Run `validate-rule-links.py`
2. Fix paths or remove links
3. Re-validate

**Test rule:**

1. Use `find-rules-for-file.py`
2. Verify expected rules apply
3. Test with Cursor agent