أفضل الممارسات واستكشاف أخطاء قواعد MDC في Cursor
قواعد MDC (Markdown Configuration) هي الطريقة القوية التي يستخدمها Cursor لفرض معايير الترميز واتفاقيات المشروع وإرشادات سلوك الذكاء الاصطناعي. عند تكوينها بشكل صحيح، فإنها تحسن جودة واتساق الكود بشكل كبير. يغطي هذا الدليل أفضل الممارسات لإنشاء قواعد MDC وتنظيمها واستكشاف أخطائها.
ما هي قواعد MDC؟
قواعد MDC هي ملفات Markdown مع front matter YAML تخبر Cursor بكيفية التصرف عند العمل مع ملفات محددة أو في سياقات محددة. يمكنها:
- فرض معايير الترميز
- تحديد أنماط بنية المشروع
- تحديد متطلبات الوثائق
- التحكم في سلوك الذكاء الاصطناعي لأنواع ملفات محددة
متطلبات تنسيق الملف
يجب أن تتبع قواعد MDC هذا التنسيق بالضبط:
---
description: 'وصف القاعدة هنا'
globs: ['src/**/*.ts', 'tests/**/*.ts']
alwaysApply: false
---
# عنوان القاعدة
محتوى القاعدة هنا...
## إرشادات محددة
- إرشاد 1
- إرشاد 2
المتطلبات الحرجة
| المتطلب | التفاصيل |
|---|---|
| الامتداد | يجب أن يكون .mdc (وليس .md) |
| الواجهة الأمامية | يجب استخدام تنسيق YAML بين محددات --- |
| الموقع | يجب أن يكون في دليل .cursor/rules/ |
| globs | مصفوفة من أنماط الملفات التي تنطبق عليها هذه القاعدة |
| alwaysApply | قيمة منطقية - ما إذا كانت تنطبق بدون مطابقة الملف |
اتفاقية التسمية
استخدم نظام بادئة مرقم للتنظيم:
.cursor/rules/
001-core-coding-standards.mdc
002-typescript-conventions.mdc
003-react-patterns.mdc
100-api-design.mdc
101-database-models.mdc
200-testing-requirements.mdc
201-documentation-rules.mdc
نظام الترقيم
| النطاق | الفئة | مثال |
|---|---|---|
001-099 | القواعد الأساسية (تنطبق على جميع الملفات) | معايير الترميز، التنسيق |
100-199 | قواعد التكامل (مجالات محددة) | API، قاعدة البيانات، المصادقة |
200-299 | قواعد الأنماط/الأدوار | الاختبار، الوثائق |
300-399 | خاصة بالتقنية | React، Vue، Angular |
كتابة قواعد فعالة
كن محددًا وقابلًا للتنفيذ
سيء:
اكتب كودًا جيدًا.
جيد:
## معالجة الأخطاء
يجب أن تستخدم جميع الوظائف غير المتزامنة كتل try/catch:
```typescript
async function fetchUser(id: string): Promise<User> {
try {
const response = await api.get(`/users/${id}`);
return response.data;
} catch (error) {
logger.error(`Failed to fetch user ${id}`, error);
throw new UserNotFoundError(id);
}
}
### قم بتضمين أمثلة
أظهر دائمًا الأمثلة الصحيحة والخاطئة:
```markdown
## إدارة الحالة
✅ افعل: استخدم React Query لحالة الخادم
```typescript
const { data, isLoading } = useQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId)
});
❌ لا تفعل: استخدم useEffect لجلب البيانات
// تجنب هذا النمط
useEffect(() => {
fetchUser(userId).then(setUser);
}, [userId]);
### استخدم أنماط Glob بفعالية
```yaml
# تطبيق على جميع ملفات TypeScript
globs: ['**/*.ts', '**/*.tsx']
# تطبيق فقط على كود الواجهة الخلفية
globs: ['src/server/**/*.ts', 'src/api/**/*.ts']
# تطبيق على ملفات اختبار محددة
globs: ['**/*.test.ts', '**/*.spec.ts']
# استبعاد ملفات معينة
globs: ['src/**/*.ts', '!src/generated/**']
فئات القواعد الشائعة
1. قواعد نمط الكود
---
description: 'فرض نمط كود متسق'
globs: ['src/**/*.ts', 'src/**/*.tsx']
alwaysApply: true
---
# معايير نمط الكود
## الاستيرادات
- تجميع الاستيرادات: React، المكتبات الخارجية، الوحدات الداخلية، الأنواع
- استخدام الاستيرادات المطلقة لوحدات src/
- الفرز أبجديًا داخل المجموعات
## التسمية
- المكونات: PascalCase (UserProfile)
- الخطافات: camelCase تبدأ بـ 'use' (useAuth)
- الثوابت: UPPER_SNAKE_CASE
- الملفات: kebab-case (user-profile.tsx)
2. قواعد البنية
---
description: 'فرض أنماط بنية نظيفة'
globs: ['src/**/*.ts']
alwaysApply: false
---
# إرشادات البنية
## تبعيات الطبقة
- طبقة المجال: لا توجد تبعيات خارجية
- طبقة التطبيق: تعتمد فقط على المجال
- طبقة البنية التحتية: تعتمد على التطبيق
## تنظيم الملفات
src/ domain/ # منطق الأعمال، الكيانات application/ # حالات الاستخدام، DTOs infrastructure/ # قاعدة البيانات، API، الخدمات الخارجية presentation/ # مكونات واجهة المستخدم
3. قواعد الاختبار
---
description: 'متطلبات وأنماط الاختبار'
globs: ['**/*.test.ts', '**/*.test.tsx']
alwaysApply: true
---
# معايير الاختبار
## الاختبارات المطلوبة
- اختبارات وحدة لجميع الوظائف المساعدة
- اختبارات المكونات لجميع مكونات React
- اختبارات التكامل لنقاط نهاية API
- اختبارات E2E لتدفقات المستخدم الحرجة
## هيكل الاختبار
اتبع نمط AAA:
1. Arrange: إعداد بيانات الاختبار والمحاكاة
2. Act: تنفيذ الوظيفة قيد الاختبار
3. Assert: التحقق من النتائج
استكشاف أخطاء المشكلات الشائعة
المشكلة 1: عدم حفظ التغييرات
العرض: تقوم بتحرير ملف .mdc وحفظه، لكن Cursor لا يطبق التغييرات.
الحل:
- أغلق Cursor تمامًا (ليس فقط النافذة - أغلق التطبيق)
- أعد فتح Cursor
- يجب تطبيق التغييرات الآن
سبب حدوث ذلك: يتم تخزين قواعد MDC مؤقتًا عند بدء تشغيل Cursor. لا يتم إعادة تحميلها ديناميكيًا.
المشكلة 2: عدم تطبيق القواعد
العرض: يتجاهل Cursor قواعدك عند تحرير الملفات.
قائمة التحقق:
- امتداد الملف هو
.mdc(وليس.md) - الملف موجود في دليل
.cursor/rules/ - الواجهة الأمامية لها بناء YAML صالح
- نمط
globsيطابق ملفاتك المستهدفة - لا توجد أخطاء بناء في محتوى Markdown
أمر التصحيح:
# التحقق مما إذا كان Cursor يتعرف على قواعدك
ls -la .cursor/rules/
# التحقق من امتدادات الملفات
file .cursor/rules/*
المشكلة 3: قواعد متعارضة
العرض: تعطي قواعد متعددة تعليمات متضاربة.
ترتيب الحل:
- القواعد ذات أنماط glob الأكثر تحديدًا لها الأسبقية
- يتم تقييم القواعد ذات
alwaysApply: trueأولاً - القواعد اللاحقة بالترتيب الأبجدي تتجاوز السابقة
أفضل ممارسة: استخدم حقل priority (إذا كان مدعومًا):
---
description: 'قاعدة ذات أولوية عالية'
globs: ['src/**/*.ts']
priority: 100
---
المشكلة 4: القواعد طويلة جدًا
العرض: لا يتبع Cursor جميع التعليمات في قاعدة طويلة.
الحل: قسّمها إلى قواعد متعددة مركزة:
.cursor/rules/
001-general-style.mdc # إرشادات قصيرة وعامة
002-error-handling.mdc # خاص بمعالجة الأخطاء
003-performance.mdc # تحسينات الأداء
تقنيات متقدمة
قواعد مشروطة
استخدم globs لتطبيق قواعد مختلفة على أجزاء مختلفة من قاعدة الكود:
# قواعد الواجهة الأمامية
globs: ['src/components/**/*.tsx', 'src/pages/**/*.tsx']
---
استخدم نمط React hooks. فضّل المكونات الوظيفية.
# قواعد الواجهة الخلفية
globs: ['src/server/**/*.ts', 'src/api/**/*.ts']
---
استخدم حقن التبعية. اتبع مبادئ SOLID.
وراثة القواعد
أنشئ قاعدة أساسية وقم بتوسيعها:
---
description: 'معايير TypeScript الأساسية'
globs: ['**/*.ts', '**/*.tsx']
alwaysApply: true
---
# قواعد TypeScript الأساسية
- استخدام تكوين TypeScript الصارم
- لا أنواع `any` بدون تعليق توضيحي
- فضّل `interface` على `type` لأشكال الكائنات
---
description: 'امتدادات خاصة بـ React'
globs: ['src/**/*.tsx']
alwaysApply: false
---
# قواعد React
بالإضافة إلى قواعد TypeScript الأساسية:
- استخدم المكونات الوظيفية مع الخطافات
- يجب تصدير واجهات الخصائص
- استخدم React.FC باعتدال (فضّل كتابة الخصائص بشكل صريح)
قواعد ديناميكية بمتغيرات
تدعم بعض الإعدادات المتقدمة متغيرات القوالب:
---
description: 'اتفاقيات خاصة بالمشروع'
globs: ['**/*.ts']
---
# اتفاقيات المشروع
## عنوان URL الأساسي لواجهة برمجة التطبيقات
استخدم: {{API_BASE_URL}}
## المصادقة
رأس الرمز: {{AUTH_HEADER_NAME}}
مرجع سريع: قالب قاعدة MDC
---
description: ''
globs: ['']
alwaysApply: false
---
# العنوان
## القسم 1
- إرشاد 1
- إرشاد 2
## القسم 2
```typescript
// مثال على الكود
المراجع
## الموارد ذات الصلة
- [استخدام قواعد Cursor بفعالية](using-cursor-rules-effectively.mdx)
- [أفضل الممارسات لقواعد Cursor](best-practices-for-cursor-rules.mdx)
- [دليل إعداد CursorRules](cursorrules-setup-guide.mdx)