إذا لم يلتزم Cursor بقاعدة مشروعك، فافحص امتداد الملف ونوع تطبيق القاعدة قبل إعادة كتابة التعليمات. قواعد المشروع توجد داخل مجلد .cursor/rules بامتداد .mdc، وقد تعمل دائمًا أو عند وجود ملفات مطابقة أو عند اختيارها يدويًا أو عندما يقرر Agent صلتها بالمهمة. مجرد وضع نص في المجلد لا يعني أن كل محادثة ستستخدمه.
هذا الدليل يخص قواعد Project Rules في Cursor. لا يشرح شراء الاشتراك أو إعداد حساب الفريق، ولا يعد بأن التعليمات ستمنع كل خطأ برمجي. الهدف هو تقليل تكرار التصحيح واختبار أن القاعدة المناسبة تصل إلى المهمة المناسبة.
ما الفرق بين قاعدة المشروع والتفضيل العام؟
قاعدة المشروع تحفظ معرفة مرتبطة بمستودع كود محدد، مثل مكان اختبارات الواجهة أو نمط التعامل مع أخطاء التطبيق. يمكن حفظها مع ملفات المشروع في Git كي يراجعها الفريق ويستخدمها بدل أن يعيد كل مطور كتابة الملاحظة نفسها في المحادثة.
أما User Rules فهي تفضيلات أوسع عبر مشروعاتك. لا تضع فيها قرارًا معماريًا يخص متجرًا واحدًا إذا كان سيضلل العمل في مشروع آخر. وتوجد Team Rules يديرها المسؤول؛ إذا تعارضت التعليمات، تذكر وثائق Cursor أن أولوية قواعد الفريق تسبق المشروع ثم المستخدم. راجع المسؤول بدل محاولة الالتفاف على قاعدة فريق مفروضة.
أنشئ قاعدة صغيرة داخل المشروع
من Customize افتح Rules ثم اختر Add Rule. تذكر صفحة المساعدة أيضًا أمر New Cursor Rule من لوحة الأوامر. سمّ القاعدة بما يوضح غرضها، واكتب سلوكًا واحدًا يمكن مراجعته، ثم اختر نوع التطبيق واحفظها داخل المشروع.
تحقق من أن الملف داخل .cursor/rules وأن امتداده .mdc. توضح الوثائق أن ملفًا عاديًا بامتداد .md في هذا المجلد لا يُعامل كقاعدة مشروع. إذا كنت تريد ملف تعليمات بسيطًا بصيغة Markdown، فوثائق Cursor تقدم AGENTS.md بديلًا، لكنه ليس مجرد تغيير عشوائي لامتداد قاعدة مشروطة.
لا تبدأ بنسخ دليل أسلوب كامل. اكتب ما يميز مشروعك فعلًا، وأشر إلى ملف مثال موجود بدل تكرار كوده. اجعل أسماء الملفات والمسارات صحيحة، وراجع القاعدة مع التغييرات التي تطرأ على بنية المشروع.
اختر وقت التطبيق بدل تفعيل كل شيء دائمًا
نوع Always Apply يضيف القاعدة إلى كل محادثة. يناسب إرشادًا عامًا يحتاجه هذا المشروع باستمرار، لكنه ليس الاختيار الافتراضي لكل تفصيل صغير. في هذا الوضع، توضح صفحة المرجع أن أنماط الملفات والوصف لا يقيّدان التطبيق كما قد تتوقع.
نوع Apply Intelligently يعتمد على وصف يوضح متى تكون القاعدة مفيدة، ثم يقرر Agent مدى صلتها. أما Apply to Specific Files فيربطها بنمط ملفات؛ راجع أن النمط يطابق الملفات الموجودة فعلًا في السياق، لا مجرد اسم مجلد تتخيله.
نوع Apply Manually يستخدم عند الإشارة إلى القاعدة بعلامة @ في المحادثة. اختره لملاحظة تحتاجها في مهمة محددة ولا تريد إضافتها دائمًا. لا تخلط بين قاعدة محفوظة وقاعدة مطبقة، وراجع النوع من الواجهة عند تشخيص المشكلة.
مثال توضيحي لفريق يعمل على واجهة متجر
لنفترض فريقًا خياليًا يضيف حقولًا إلى صفحة منتج. تتكرر مشكلة أن التعديل يصل بلا اختبار لحالة الإدخال الفارغ. بدل قاعدة واسعة عن كتابة كود ممتاز، يجهز الفريق قاعدة قصيرة تشرح مكان أمثلة اختبارات النماذج وما الذي يراجعه المطور قبل تسليم تعديل حقل.
إذا كان الإرشاد يخص الواجهة فقط، يختار الفريق نطاق ملفاتها ويجربه على ملف واجهة صغير. ثم يجرب مهمة خارج هذا النطاق ليتأكد من أن القاعدة ليست مفروضة على كل أجزاء المشروع. هذا اقتراح لطريقة اختبار، وليس تجربة أجريناها على مشروع عميل أو ضمانًا لدقة الاختبار.
يمكن بدء التجربة بطلب شرح خطة التعديل دون تنفيذه، ثم مراجعة الاقتراح والمسارات المذكورة. عند الانتقال إلى الكود، افحص التغييرات والاختبارات الفعلية، ولا تكتفِ بأن الرد قال إنه التزم بالقاعدة.
لماذا لا تظهر نتيجة القاعدة؟
افحص أولًا المكان والامتداد، ثم نوع التطبيق. إذا اخترت Apply Intelligently، فهل الوصف يحدد المهمة المقصودة؟ وإذا اخترت Apply to Specific Files، فهل نمط الملفات يطابق الملف الذي أضفته إلى السياق؟ وإذا كانت يدوية، فهل أشرت إلى اسمها في المحادثة؟
بعد ذلك راجع التعارض والتقادم. قد تشير القاعدة إلى اختبار نُقل أو ملف حُذف، أو تناقض قاعدة أخرى. قلل النص إلى السلوك المطلوب، وبدل تغيير عدة قواعد معًا، اختبر تغييرًا واحدًا حتى تعرف أي جزء أثر في النتيجة.
توضح الوثائق أيضًا أن ذكر ملف مرجعي بمساره لا يدرج محتواه كاملًا تلقائيًا؛ يستطيع Agent قراءته عندما يحتاجه. ضع المعلومة الضرورية دائمًا في نص القاعدة نفسه، واستخدم المراجع للتفاصيل والأمثلة التي قد تتغير.
ما الذي لا تضمنه قواعد Cursor؟
القواعد توجيه للعمل وليست بديلًا عن صلاحيات المستودع أو اختبارات الأمان أو مراجعة التغييرات. وتوضح وثائق Cursor أن هذه القواعد تخص Agent في المحادثة، ولا تضبط Cursor Tab أو مراجعات Bugbot بالطريقة نفسها.
لذلك إذا كان هدفك منع تعديل ملف حساس، فلا تعتمد على جملة داخل قاعدة وحدها. استخدم ضوابط المشروع المناسبة، وراجع أي ملف قواعد قادم من مصدر آخر قبل إضافته. لا تضع كلمات مرور أو مفاتيح أو بيانات عملاء داخل ملف تعليمات سيُحفظ مع الكود.
أسئلة شائعة عن قواعد المشروع
هل تعمل القاعدة مع Cursor Tab؟
لا بحسب وثائق القواعد التي يشرحها هذا الدليل. هي موجهة إلى Agent في المحادثة، فلا تستخدم نجاح الإكمال التلقائي أو فشله للحكم على تفعيل قاعدة المشروع.
هل أكتب كل القواعد في ملف واحد؟
ابدأ بما تحتاجه، ثم قسم الإرشادات المختلفة إلى ملفات قصيرة ذات أغراض واضحة. كثرة النص المكرر لا تعني التزامًا أفضل؛ راجع النطاق والمثال والنتيجة بدل زيادة التعليمات بلا سبب.
هل الإشارة إلى ملف تعني إدراج محتواه كاملًا؟
لا. تشير وثائق Cursor إلى أن الملف المرجعي يُقرأ عند الحاجة، وليس مضمونًا أن يكون نصه كله مضافًا إلى السياق بمجرد ذكر مساره. اكتب الشرط الضروري في القاعدة نفسها.
المصادر والخطوة التالية
لصيغة الملفات وأنواع التطبيق والتشخيص: مرجع Cursor لقواعد المشروع ونطاق تطبيقها
لخطوات الإنشاء وأولوية القواعد وحدود الميزات: مساعدة Cursor لإنشاء القواعد وتشخيصها
ولفهم استخدام الأداة ومراجعة الكود قبل اختيار الاشتراك: دليل المطور العربي لاستخدام Cursor ومراجعة الكود