Skip to main content

Best Practices for MDC Rules and Troubleshooting

tip

MDC (Model-Driven Code) rules help you maintain consistent code quality and automate repetitive tasks in Cursor.

Understanding MDC Rules​

MDC rules are powerful tools that allow you to:

  • Enforce coding standards
  • Automate code transformations
  • Implement custom validations
  • Create project-specific guidelines

Setting Up MDC Rules​

Basic Structure​

Create a .cursor/rules directory in your project:

.cursor/
└── rules/
    ├── naming.json
    ├── formatting.json
    └── custom-rules.json

Rule Configuration​

Basic rule structure:

.cursor/rules/naming.json
{
  "name": "Naming Conventions",
  "description": "Enforces consistent naming across the project",
  "rules": [
    {
      "pattern": "^[A-Z][a-zA-Z]*Component$",
      "filePattern": "*.component.ts",
      "message": "Component names must be PascalCase and end with 'Component'"
    }
  ]
}

Common Rule Types​

1. Naming Conventions​

{
  "rules": [
    {
      "pattern": "^[a-z][a-zA-Z]*Service$",
      "filePattern": "*.service.ts",
      "message": "Service names must be camelCase and end with 'Service'"
    },
    {
      "pattern": "^I[A-Z][a-zA-Z]*$",
      "filePattern": "*.interface.ts",
      "message": "Interface names must start with 'I' and use PascalCase"
    }
  ]
}

2. Code Structure​

{
  "rules": [
    {
      "pattern": "^import.*from",
      "location": "top",
      "message": "Imports must be at the top of the file"
    },
    {
      "maxLines": 300,
      "filePattern": "*.ts",
      "message": "Files should not exceed 300 lines"
    }
  ]
}

3. Documentation Requirements​

{
  "rules": [
    {
      "pattern": "^\\/\\*\\*[\\s\\S]*?\\*\\/",
      "filePattern": "*.ts",
      "message": "All files must have JSDoc documentation"
    }
  ]
}

Advanced Rule Configuration​

Using Variables​

{
  "variables": {
    "COMPONENT_PREFIX": "App",
    "MAX_FILE_SIZE": 500
  },
  "rules": [
    {
      "pattern": "^${COMPONENT_PREFIX}[A-Z][a-zA-Z]*$",
      "filePattern": "*.component.ts",
      "message": "Components must start with '${COMPONENT_PREFIX}'"
    }
  ]
}

Nested Rules​

{
  "rules": {
    "naming": {
      "components": [
        {
          "pattern": "^[A-Z][a-zA-Z]*Component$",
          "severity": "error"
        }
      ],
      "services": [
        {
          "pattern": "^[a-z][a-zA-Z]*Service$",
          "severity": "warning"
        }
      ]
    }
  }
}

Troubleshooting Common Issues​

Rule Not Triggering​

  1. Check Rule Syntax

    {
      "rules": [
        {
          "pattern": "^[A-Z][a-zA-Z]*$", // Valid regex pattern
          "filePattern": "*.ts",         // Valid glob pattern
          "severity": "error"            // Valid severity level
        }
      ]
    }

  2. Verify File Path

    # Ensure rules are in the correct location
    .cursor/
    └── rules/
        └── your-rule.json

Performance Issues​

  1. Optimize Patterns

    {
      "rules": [
        {
          "pattern": "^[A-Z]\\w*$", // More efficient than ^[A-Z][a-zA-Z]*$
          "filePattern": "*.{ts,js}" // Group extensions
        }
      ]
    }

  2. Use Exclusions

    {
      "exclude": [
        "node_modules/**",
        "dist/**",
        "build/**"
      ],
      "rules": [...]
    }

Best Practices​

1. Organization​

.cursor/
└── rules/
    ├── naming/
    │   ├── components.json
    │   └── services.json
    ├── formatting/
    │   ├── spacing.json
    │   └── indentation.json
    └── documentation/
        └── jsdoc.json

2. Rule Documentation​

{
  "name": "Component Naming",
  "description": "Enforces consistent component naming conventions",
  "version": "1.0.0",
  "author": "Your Team",
  "rules": [...]
}

3. Testing Rules​

Create test files:

test/rules/naming.test.ts
describe('Naming Rules', () => {
  it('should validate component names', () => {
    // Test implementation
  });
});

Integration with CI/CD​

GitHub Actions Example​

.github/workflows/mdc-validation.yml
name: MDC Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run MDC Validation
        run: cursor validate-rules

Monitoring and Maintenance​

Rule Statistics​

cursor rules-stats

Regular Updates​

  1. Review rule effectiveness
  2. Update patterns based on feedback
  3. Monitor false positives
  4. Adjust severity levels
tip

Keep a changelog for your MDC rules to track changes and their impact.