انتقل إلى المحتوى الرئيسي

أفضل الممارسات لقواعد MDC واستكشاف الأخطاء وإصلاحها

تلميح

تساعدك قواعد MDC (الكود المدفوع بالنموذج) على الحفاظ على جودة الكود المتسقة وأتمتة المهام المتكررة في Cursor.

فهم قواعد MDC​

قواعد MDC هي أدوات قوية تتيح لك:

  • فرض معايير الترميز
  • أتمتة تحويلات الكود
  • تنفيذ عمليات التحقق المخصصة
  • إنشاء إرشادات خاصة بالمشروع

إعداد قواعد MDC​

الهيكل الأساسي​

قم بإنشاء دليل .cursor/rules في مشروعك:

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

تكوين القاعدة​

هيكل القاعدة الأساسي:

.cursor/rules/naming.json
{
  "name": "اتفاقيات التسمية",
  "description": "فرض تسمية متسقة عبر المشروع",
  "rules": [
    {
      "pattern": "^[A-Z][a-zA-Z]*Component$",
      "filePattern": "*.component.ts",
      "message": "يجب أن تكون أسماء المكونات بصيغة PascalCase وتنتهي بـ 'Component'"
    }
  ]
}

أنواع القواعد الشائعة​

1. اتفاقيات التسمية​

{
  "rules": [
    {
      "pattern": "^[a-z][a-zA-Z]*Service$",
      "filePattern": "*.service.ts",
      "message": "يجب أن تكون أسماء الخدمات بصيغة camelCase وتنتهي بـ 'Service'"
    },
    {
      "pattern": "^I[A-Z][a-zA-Z]*$",
      "filePattern": "*.interface.ts",
      "message": "يجب أن تبدأ أسماء الواجهات بـ 'I' وتستخدم صيغة PascalCase"
    }
  ]
}

2. هيكل الكود​

{
  "rules": [
    {
      "pattern": "import\\s+{\\s*([^}]+)\\s*}\\s+from",
      "filePattern": "*.ts",
      "message": "يجب ترتيب الاستيرادات أبجديًا"
    },
    {
      "pattern": "^export\\s+class\\s+[A-Z][a-zA-Z]*\\s+{",
      "filePattern": "*.ts",
      "message": "يجب أن تبدأ تعريفات الفئات بـ 'export class'"
    }
  ]
}

3. التوثيق​

{
  "rules": [
    {
      "pattern": "/\\*\\*[\\s\\S]*?\\*/\\s*export",
      "filePattern": "*.ts",
      "message": "يجب توثيق جميع الفئات والوظائف المصدرة"
    },
    {
      "pattern": "@param\\s+{[^}]+}\\s+\\w+",
      "filePattern": "*.ts",
      "message": "يجب توثيق جميع المعلمات بنوع وصفي"
    }
  ]
}

4. أنماط الكود​

{
  "rules": [
    {
      "pattern": "console\\.log\\(",
      "filePattern": "*.ts",
      "message": "لا تترك عبارات console.log في الكود الإنتاجي"
    },
    {
      "pattern": "TODO|FIXME",
      "filePattern": "*.*",
      "message": "يجب معالجة جميع علامات TODO و FIXME قبل الدمج"
    }
  ]
}

استكشاف الأخطاء وإصلاحها​

مشكلات التكوين​

  1. التحقق من بناء الجملة

    {
      "rules": [
        {
          "pattern": "^[A-Z][a-zA-Z]*$", // نمط regex صالح
          "filePattern": "*.ts",         // نمط glob صالح
          "severity": "error"            // مستوى خطورة صالح
        }
      ]
    }

  2. التحقق من مسار الملف

    # تأكد من أن القواعد في المكان الصحيح
    .cursor/
    └── rules/
        └── your-rule.json

مشكلات الأداء​

  1. تحسين الأنماط

    {
      "rules": [
        {
          "pattern": "^[A-Z]\\w*$", // أكثر كفاءة من ^[A-Z][a-zA-Z]*$
          "filePattern": "*.{ts,js}" // تجميع الامتدادات
        }
      ]
    }

  2. استخدام الاستثناءات

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

أفضل الممارسات​

1. التنظيم​

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

2. توثيق القواعد​

{
  "name": "تسمية المكونات",
  "description": "فرض اتفاقيات تسمية متسقة للمكونات",
  "version": "1.0.0",
  "author": "فريقك",
  "rules": [...]
}

3. اختبار القواعد​

إنشاء ملفات اختبار:

test/rules/naming.test.ts
describe('قواعد التسمية', () => {
  it('يجب التحقق من صحة أسماء المكونات', () => {
    // تنفيذ الاختبار
  });
});

التكامل مع CI/CD​

مثال GitHub Actions​

.github/workflows/mdc-validation.yml
name: التحقق من MDC
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: تشغيل التحقق من MDC
        run: cursor validate-rules

المراقبة والصيانة​

إحصائيات القواعد​

cursor rules-stats

التحديثات المنتظمة​

  1. مراجعة فعالية القاعدة
  2. تحديث الأنماط بناءً على التعليقات
  3. مراقبة النتائج الإيجابية الخاطئة
  4. ضبط مستويات الخطورة
تلميح

احتفظ بسجل تغييرات لقواعد MDC الخاصة بك لتتبع التغييرات وتأثيرها.

الموارد ذات الصلة​