قواعد Cursor: اضبط تعليمات المشروع واختبر أثرها

الفائدة هي تقليل التصحيحات أثناء مراجعة الشيفرة. ولتوضيح حجم الجهد، إذا أجرى أربعة مطورين ثلاثة تصحيحات أسبوعياً لكل منهم، واستغرق كل تصحيح خمس دقائق، فالنتيجة 60 دقيقة تُنفق على تكرار الأعراف نفسها. هذا مثال حسابي، وليس وعداً بتوفير هذا الوقت. احسب التصحيحات التي تختفي بعد الإعداد، ثم اطرح الوقت الذي تقضيه في صيانة القواعد. أما فاتورة الاشتراك فهي مسألة منفصلة يناقشها دليل أسعار Cursor.

أين تضع قواعد Cursor؟

ضع قرارات البرمجة المشتركة بجوار الشيفرة، واحتفظ بتفضيلاتك الشخصية في الردود ضمن إعداداتك الخاصة.

تسري تعليمات AGENTS.md الموجودة في المجلدات الفرعية على المجلد الذي يحتويها وما يتفرع منه، إلى جانب تعليمات المجلدات الأعلى؛ وعند التعارض، تكون الأولوية للتعليمات الأكثر تخصيصاً. أما قواعد الفريق والمشروع والمستخدم، فترتيب الأولوية الموثّق بينها هو Team → Project → User. مرجع قواعد Cursor

بالنسبة إلى فريق صغير، أبدأ عادةً بقواعد المشروع. فتعليمة مثل «استخدم مكوّنات النماذج الموجودة لدينا» مكانها المستودع، أما «اجعل ردّك النهائي قصيراً» فهي تفضيل يخصك. الفصل بين النوعين يمنع تحوّل تفضيل شخصي إلى سياسة للفريق من دون قصد.

متى تُرفق كل قاعدة بسياق المهمة؟

تتحكم الترويسة، أو frontmatter، في إرفاق القاعدة. وهي كتلة الإعدادات الصغيرة التي تسبق نص التعليمات.

«باختيار الوكيل» تعني أنه يختار القاعدة بناءً على وصفها. أما glob فهو نمط لمطابقة مسارات الملفات. آلية الإرفاق وصياغة الإعدادات

تخيّل الإرفاق بوصفه إيصال أمر العمل إلى طاولة العمل المناسبة. فمهما أُحكمت صياغة التعليمة، لن تفيد مهمةً لم تصل إليها. اجعل الحد الأدنى من متطلبات الأمان سارياً دائماً، وأرفق إرشادات أسلوب الشيفرة بالملفات المعنية، واترك الاختيار للوكيل حين تتوقف صلة الإرشادات على طبيعة المهمة.

ثلاث قواعد جاهزة للنسخ لتطبيق ويب بلغة TypeScript

أنشئ الملفات التالية في مستودعك. إنها أعراف عمل مقترحة لفريقك، تستخدم حقول الترويسة وصياغة الأنماط الواردة في مرجع Cursor. والتعليمات داخلها نقطة بداية تعدّلها بحسب حاجتك، وليست معايير برمجة يفرضها Cursor.

أسلوب الشيفرة: أرفق القاعدة بملفات TypeScript

احفظ الملف باسم .cursor/rules/style.mdc:

---
globs: src/**/*.ts, src/**/*.tsx
alwaysApply: false
---

- Follow the nearest existing module's naming and import conventions.
- Prefer named exports unless the framework requires a default export.
- Reuse existing UI components and utilities before adding alternatives.
- Keep formatting in the repository's formatter and linter configuration.

يفترض هذا المثال أن شيفرة التطبيق موجودة داخل src/؛ عدّل المسارات لتطابق مستودعك. ويركّز عمداً على قرارات لا تستطيع أداة التنسيق حسمها، مثل وجود زر مناسب أو دالة مساعدة للتواريخ داخل التطبيق أصلاً. وعدّل تفضيل أسلوب التصدير إذا كان فريقك قد اختار أسلوباً آخر. ينبغي أن تصف القاعدة مستودعك، لا أن تعيد تصميمه من دون أن تنتبه.

الاختبارات: صف المهام التي تحتاج إليها

احفظ الملف باسم .cursor/rules/tests.mdc:

---
description: Testing requirements when adding features, fixing bugs, or changing TypeScript behavior
alwaysApply: false
---

- Cover changed behavior with a focused regression test.
- Use the existing test runner, fixtures, and file naming conventions.
- Read package.json for the relevant test script; do not invent a command.
- Report the command and actual result, or explain why tests were not run.

النتيجة المطلوبة هي اختبار مفيد وتقرير صادق عن نتيجته. ينبغي أن يترك إصلاح العطل دليلاً على تغطية الحالة التي تسببت فيه، وأن تحافظ إعادة هيكلة الشيفرة على السلوك المعني. ولا يستدعي أيّ منهما إضافة إطار اختبارات ثانٍ، أو كتابة تقرير يخلط بين «كُتب الاختبار» و«نجح الاختبار».

إذا أردت استخدام هذه القائمة صراحةً في مهمة، فأدرج @tests في طلبك. وإذا أراد فريقك تطبيقها على كل مهمة، فغيّر وضع الإرفاق إلى Always Apply. اتخذ هذا القرار بوصفه سياسة مقصودة؛ فوجود الوصف وحده يترك اختيار القاعدة للوكيل.

الأمان: اكتفِ بأساسيات موجزة

احفظ الملف باسم .cursor/rules/security.mdc:

---
alwaysApply: true
---

- Never put secrets in source code, test fixtures, or application logs.
- Use existing server-side authentication and authorization helpers.
- Validate untrusted input at server boundaries with the existing schemas.
- Do not remove permission checks to make a feature or test pass.

استبدل عبارة «الدوال المساعدة الموجودة» بمسارات الوحدات الفعلية في مستودعك متى عرفتها. واجعل المتطلبات الأساسية سهلة الفهم أثناء العمل المعتاد على ميزة. فعبارة «اجعله آمناً» لا تعطي المراجع شيئاً محدداً يفحصه، بينما تحدد عبارة «حافظ على التحقق من الصلاحيات» مطلباً واضحاً.

هذا الملف مجموعة تعليمات، وليس حاجزاً أمنياً. واصل فرض التحقق من صلاحيات الوصول داخل الشيفرة ومراجعة التغييرات الحساسة. ويحذّر Cursor نفسه من الاعتماد على إرشادات الذكاء الاصطناعي بوصفها الضابط الأمني الوحيد. إرشادات Team Rules

كيف تتحقق من الإعداد على تغيير فعلي؟

اختر مهمة صغيرة كانت تستدعي تصحيحات متكررة. وتعديل التحقق من صحة مدخلات نموذج مثال مناسب: فهو يمسّ مكوّناً، ويغيّر سلوكاً، ويتعامل مع مدخلات المستخدم.

1. دوّن النتيجة المتوقعة. حدّد المكوّن الموجود الذي ستعيد استخدامه، والسلوك الذي ستختبره، وموضع التحقق من صحة المدخلات الذي يجب الحفاظ عليه.
2. احفظ الملفات الثلاثة وافحص حالتها. يعرض Cursor القواعد ضمن Customize → Rules؛ ويتوفر أيضاً الأمر /create-rule داخل Agent. إنشاء قاعدة
3. اطلب التغيير مع تضمين الملفات المعنية في السياق. اجعل الطلب واقعياً؛ فالمهمة التي تعيد سرد كل قاعدة لا تكشف لك إن كان الإعداد قد أفاد فعلاً.
4. راجع الفروق في الشيفرة ونتائج الفحوص المبلّغ عنها. ابحث عن تطبيق العرف نفسه، لا عن تأكيد لفظي بأن القواعد اتُبعت. وإذا كانت قائمة الاختبارات مهمة في هذه التجربة، فاطلب @tests صراحةً.
5. سجّل القواعد المفيدة مع التغيير في المستودع. امنح الفريق نقطة بداية قابلة للمراجعة. ونقّح الجملة المبهمة قبل إضافة ملف آخر.

إذا لم يُطبَّق أحد الأعراف، فميّز بين احتمالين: إما أن القاعدة لم تصل إلى المهمة، وإما أنها وصلت لكن التعليمة لم تكن فعّالة. الأول يتطلب إصلاح الإرفاق، والثاني يتطلب تعليمة أوضح، أو مثالاً، أو فحصاً آلياً.

ما الأعراف التي تستحق الاحتفاظ بها؟

ابدأ بالأخطاء المتكررة الأعلى كلفة على فريقك. فيما يلي استخدامات عملية تستحق النظر، مرتبة بحسب عبء المراجعة الذي قد تخففه.

لا تجعل هذه الأمثلة مبرراً لإضافة خمسة ملفات أخرى. إذا لم تقع المشكلة، فلا تضف لها قاعدة. وإذا أمكن لأداة أن تتحقق من المطلب بدقة، فامنح ذلك الفحص الأولوية. القاعدة المفيدة تسد فجوة بين طلب المهمة والأدوات الموجودة في المستودع.

ماذا عن ملف .cursorrules القديم؟

استخدم .cursor/rules/*.mdc لإعداد المشروع وفق التوثيق الحالي. حتى 11 أكتوبر 2026، لا تذكر صفحة القواعد ملف .cursorrules، ولذلك لا تؤكد ما إذا كان الملف القديم لا يزال يعمل. المرجع الحالي

إذا كان مستودعك لا يزال يحتوي على الملف القديم، فأوصي بنقل تعليماته المفيدة إلى قواعد مشروع محددة الغرض، مستعيناً بالملفات الثلاثة أعلاه كنقطة بداية. حدّد شروط إرفاقها، وتحقق من عملها على مهمة فعلية قبل الاستغناء عن النسخة القديمة. لا تحتفظ بأعراف لم تعد صالحة لمجرد أنها موثّقة بالفعل.

ما العلاقة بملفّي CLAUDE.md وAGENTS.md؟

الفكرة المشتركة هي تعليمات ثابتة للمشروع: يستخدم Claude Code ملف CLAUDE.md، ويقرأ Codex اتفاقات العمل في AGENTS.md. ويؤدي خيار Markdown العادي في Cursor الغرض البسيط نفسه، بينما تتيح ملفات .mdc خيارات الإرفاق. حافظ على اتساق الأعراف الأساسية، لكن اضبط آلية تحميل التعليمات في كل أداة عن قصد؛ فنسخ النص لا يعني نسخ الإعدادات. وإذا كان فريقك يستخدم عدة وكلاء، فعيّن مسؤولاً واحداً عن الأعراف المشتركة حتى لا تصبح الملفات مراجع متنافسة.

أداتان صغيرتان تستحقان البناء بعد الإعداد

يمثّل فاحص قواعد المستودع الفرصة الأقوى لقائد هندسي: يفحص امتدادات الملفات، وحقول الترويسة المعتمدة، والأنماط التي لا تطابق أي ملف متتبَّع في المستودع. وأبسط نسخة مفيدة منه تقرير محلي يُشغّل أثناء المراجعة. أما إشارة الطلب فمحدودة: أعاد DataForSEO في البحث الخاص بهذا المقال تقديراً يبلغ 140 عملية بحث شهرية عن “cursor rules examples”. هذا اهتمام بموضوع قريب، وليس دليلاً على استعداد الناس للدفع. والقيد واضح: قد تكون القاعدة سليمة البنية، ومع ذلك تقدّم إرشادات ضعيفة. تعريف المقياس

وقد تفيد حزمة لمراجعة أعراف الفريق قائداً يشرف على عدة مستودعات. اجمع ملاحظات المراجعة المتكررة والأمثلة المعتمدة في مقترح لتعديل القواعد، مع تحديد مراجع لكل تغيير. أعاد DataForSEO تقديراً يبلغ 70 عملية بحث شهرية عن “cursor team rules”. ابدأ بأداة داخلية؛ فقواعد Team Rules المدمجة تتولى التوزيع بالفعل، لذا فإن لوحة أخرى لتخزين القواعد ليست فكرة منتج قوية. العمل المفيد هو تحديد ما يستحق أن يتحول إلى تعليمة ثابتة. تعريف المقياس

أسئلة شائعة عند إعداد القواعد

في الأسبوع المقبل، اختر تصحيحاً يتكرر، وأحكم صياغة القاعدة الخاصة به، ثم جرّبها على طلب الدمج المعتاد التالي. ولتقييم اختيار الأداة على نطاق أوسع، اقرأ مراجعة Cursor أو دليل أفضل بدائل Cursor.

وإذا أردت دمج هذا الإعداد في سير التطوير لدى فريقك، فهذا ما تتناوله خدمة أنظمة الذكاء الاصطناعي للإنتاج.