Cursor Rules: كيف تكتب ملفات .cursor/rules التي تعمل فعلاً

كل مستخدم لـ Cursor يصطدم في نهاية المطاف بنفس العقبة. يولّد الذكاء الاصطناعي كوداً يعمل من الناحية التقنية، لكنه يتجاهل تقاليد مشروعك — مسارات استيراد خاطئة، وأنماط قديمة، ومكونات لا تشبه باقي قاعدة الكود الخاصة بك. تحل Cursor Rules هذا الأمر بمنح الذكاء الاصطناعي سياقاً دائماً حول كيفية عمل مشروعك.

ما هي Cursor Rules ولماذا تهم؟

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

كان النهج القديم يعتمد على ملف .cursorrules واحد في جذر المشروع. لا يزال يعمل، لكنه أصبح قديماً. يستخدم النظام الحالي مجلداً .cursor/rules/ مع ملفات .mdc فردية (Markdown Cursor)، كل منها مخصص لحالات محددة. هذا إعداد أفضل بكثير لأنك لست مضطراً لحشر كل التعليمات في ملف ضخم واحد — تقسّم القواعد حسب الاهتمام، ويقوم Cursor بتحميل تلك ذات الصلة بما تفعله الآن فقط.

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

إعداد ملف القواعد الأول

أنشئ مجلد .cursor/rules/ في جذر مشروعك:

mkdir -p .cursor/rules

كل قاعدة هي ملف .mdc مع frontmatter بصيغة YAML يتبعه محتوى Markdown. إليك الهيكل الأساسي:

---
description: "متى يجب تطبيق هذه القاعدة"
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

تعليماتك هنا بصيغة Markdown العادية.

ثلاثة حقول frontmatter تتحكم في كل شيء:

يمكنك أيضاً إنشاء قواعد عبر Cursor نفسه — اكتب /create-rule في الدردشة وصف ما تريد. لكن كتابتها يدوياً يمنحك مزيداً من التحكم.

شرح أنواع القواعد الأربعة

طريقة تفعيل القاعدة تعتمد على تكوين frontmatter. هناك أربعة أوضاع، واختيار الصحيح منها يهم لـ ميزانية نافذة السياق.

تطبيق دائم

---
alwaysApply: true
---

يُحمَّل في كل طلب ذكاء اصطناعي دون استثناء. استخدم هذا بحذر — للأساسيات على مستوى المشروع كإعلان stack التقنية أو الاتفاقيات الحرجة التي تنطبق في كل مكان. كل قاعدة دائمة التشغيل تستهلك رموزاً (tokens) من كل تفاعل، سواء كانت ذات صلة أم لا.

مرفقة تلقائياً (قائمة على glob)

---
globs: ["src/api/**/*.ts", "src/routes/**/*.ts"]
alwaysApply: false
---

تُفعَّل فقط عند تعديل الملفات المطابقة لأنماط glob. هذا هو نوع القاعدة الأساسي. تُحمَّل اتفاقيات مكونات React عند العمل في ملفات المكونات، وأنماط API عند العمل في معالجات المسارات، وقواعد الاختبار عند كتابة الاختبارات.

مطلوبة من العميل (ذكية)

---
description: "أنماط هجرة قاعدة البيانات باستخدام Drizzle ORM"
alwaysApply: false
---

لا glob، لا always-apply — فقط وصف. يقرأ عميل Cursor الوصف ويقرر ما إذا كانت القاعدة ذات صلة بالمهمة الحالية. إذا طلبت منه كتابة هجرة، يجلب هذه القاعدة. إذا كنت تُصمّم زراً، يتجاوزها. يعمل هذا بشكل مذهل للقواعد التي لا تتطابق بوضوح مع مسارات الملفات.

يدوي

---
---

لا توجد حقول frontmatter مُعيَّنة (أو frontmatter فارغ). تُفعَّل هذه القواعد فقط عند الإشارة إليها صراحةً بـ @اسم-القاعدة في الدردشة. جيد للتعليمات نادرة الاستخدام لكنها مهمة — كقوائم التحقق من النشر أو أدلة إعادة البناء التي تحتاجها أحياناً فقط.

أنماط glob التي تعمل فعلاً

تحدد أنماط glob الملفات التي تُشغّل القواعد المرفقة تلقائياً. إذا كانت خاطئة، فإما أن تُشغَّل القواعد أبداً أو في كل مكان. إليك ما يعمل:

# جميع ملفات TypeScript في src
globs: ["src/**/*.ts", "src/**/*.tsx"]

# ملفات المكونات فقط
globs: ["**/components/**/*.tsx"]

# ملفات Python، باستثناء الاختبارات
globs: ["**/*.py", "!**/test_*.py"]

# مجلدات متعددة محددة
globs: ["src/api/**", "src/services/**"]

بعض المشاكل من الاستخدام الفعلي:

• src/* يطابق مستوى مجلد واحد فقط. ستحتاج دائماً تقريباً src/**/* للمطابقة العودية.
• *.js لا يطابق ملفات .jsx أو .ts. كن صريحاً بشأن الامتدادات.
• يجب أن تكون أنماط glob قائمة YAML. صياغة الأقواس مثل {src,lib}/**/*.ts قد تفشل بصمت — استخدم إدخالات قائمة منفصلة.
• البادئة ! تستثني الأنماط، وهو مفيد لتجاهل الملفات المولّدة أو الكود القديم.

أمثلة عملية على القواعد

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

قاعدة أساسية على مستوى المشروع (تطبيق دائم)

---
alwaysApply: true
---

# Project: Acme Dashboard

## Tech Stack
- Next.js 15 (App Router only — no Pages Router)
- TypeScript strict mode
- Tailwind CSS v4
- Drizzle ORM with PostgreSQL
- pnpm for package management

## Critical Conventions
- All components are React Server Components by default
- Use "use client" only when the component needs interactivity
- Import paths use @/ alias mapped to src/
- Error handling: wrap async operations in try/catch, never use .catch()
- No default exports except for pages and layouts

أبق هذا تحت 30 سطراً. يُحمَّل مع كل طلب، لذا كل كلمة تكلف رموزاً.

قاعدة مكونات React (مرفقة تلقائياً)

---
description: "React component patterns and conventions"
globs: ["src/components/**/*.tsx", "src/app/**/*.tsx"]
alwaysApply: false
---

# React Component Rules

## Structure
Every component file follows this order:
1. Imports
2. Type definitions (Props interface)
3. Component function (named export)
4. Sub-components (if any)

## Patterns

Use named exports, not default:
- YES: `export function Button({ label }: ButtonProps)`
- NO: `export default function Button()`

For data fetching in Server Components:
```tsx
// Fetch directly in the component — no useEffect
export async function UserProfile({ id }: { id: string }) {
  const user = await db.query.users.findFirst({
    where: eq(users.id, id)
  });
  return <div>{user.name}</div>;
}

Anti-Patterns (NEVER do these)

• No useEffect for data fetching in Server Components
• No CSS modules — use Tailwind exclusively
• No barrel exports (index.ts re-exports)
• No prop drilling beyond 2 levels — use context or composition

### قاعدة Python API (مرفقة تلقائياً)

```yaml
---
description: "FastAPI endpoint conventions and patterns"
globs: ["src/api/**/*.py", "src/routes/**/*.py"]
alwaysApply: false
---

# FastAPI Conventions

## Endpoint Structure
- Use APIRouter for route grouping
- Type all request/response models with Pydantic v2
- Dependency injection for database sessions

## Pattern
```python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(
    user_id: int,
    db: AsyncSession = Depends(get_db)
) -> UserResponse:
    user = await db.get(User, user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return UserResponse.model_validate(user)

Error Handling

• Always use HTTPException, not raw Response objects
• Log errors with structlog before raising
• Return consistent error shapes: {"detail": "message"}

### قاعدة خدمة Go (مرفقة تلقائياً)

```yaml
---
description: "Go service patterns and error handling"
globs: ["**/*.go", "!**/*_test.go"]
alwaysApply: false
---

# Go Conventions

## Error Handling
- Always handle errors immediately — no _ for error returns
- Wrap errors with fmt.Errorf("context: %w", err)
- Use sentinel errors for expected failure cases

## Project Layout
- cmd/ for entrypoints
- internal/ for private packages
- pkg/ for public libraries

## Pattern
```go
func (s *UserService) GetByID(ctx context.Context, id string) (*User, error) {
    user, err := s.repo.Find(ctx, id)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
        }
        return nil, fmt.Errorf("fetching user %s: %w", id, err)
    }
    return user, nil
}

## إدارة تكلفة الرموز (Token Tax)

هذا ما تتجاوزه معظم أدلة Cursor: كل قاعدة تكتبها تكلف رموزاً (tokens). مشروع به 20 قاعدة دائمة التشغيل قد يحرق **أكثر من 2000 رمز في كل طلب** على التعليمات فقط — قبل أن يرى الذكاء الاصطناعي كودك أصلاً.

هذا مهم لأن سياق دردشة Cursor يبلغ حوالي 20,000 رمز في الوضع القياسي. إذا استهلكت قواعدك 25% منها، فقدت ربع "مساحة تفكير" الذكاء الاصطناعي لسؤالك الفعلي. ستلاحظ جودة مخرجات أسوأ مع تراكم القواعد، خاصة في المحادثات الطويلة.

ثلاثة مبادئ تحافظ على صحة ميزانية الرموز:

**1. استخدم القواعد المرفقة تلقائياً والمطلوبة من العميل بشكل مكثف.** فقط إعلان stack المشروع يجب أن يكون دائم التشغيل. كل شيء آخر يجب أن يُحمَّل بشكل مشروط. قاعدة مكونات React تلك؟ لا تحتاج أن تكون في السياق عند كتابة هجرات SQL.

**2. اكتب بكثافة، لا بإطناب.** استبدل "يُوصى بشدة أن يستخدم المطورون واجهات TypeScript بدلاً من أسماء الأنواع عند تعريف عقود API العامة" بـ "Prefer `interface` over `type` for public APIs." الذكاء الاصطناعي لا يحتاج إقناعاً — يحتاج تعليمات.

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

يمكنك مراقبة استخدام الرموز في شريط الحالة أسفل لوحة دردشة Cursor. انتبه عند اقترابه من 100% — هذه إشارة التقليم.

## تنظيم القواعد لمشروع حقيقي

يحتاج مشروع الإنتاج عادةً إلى 5-8 ملفات قواعد. إليك هيكلاً يعمل بشكل جيد:

```text
.cursor/rules/
  base.mdc            # Stack التقنية، always-apply (< 30 سطراً)
  components.mdc      # أنماط React/Vue، glob إلى مجلدات المكونات
  api.mdc             # اتفاقيات backend، glob إلى مجلدات API
  database.mdc        # أنماط ORM، glob إلى models/migrations
  testing.mdc         # اتفاقيات الاختبار، glob إلى ملفات الاختبار
  deployment.mdc      # أنماط CI/CD، تشغيل يدوي
  personal.mdc        # تفضيلاتك (gitignored)

احتفظ بكل شيء في التحكم بالإصدارات ما عدا personal.mdc. بهذه الطريقة يحصل فريقك بأكمله على نفس سلوك الذكاء الاصطناعي — وهذا هو المقصود. كما يقول أحد مستخدمي منتدى Cursor، القواعد الجيدة تعني أنك "تقبل المزيد من الاقتراحات كما هي، مع مخرجات تطابق اتفاقياتك من المحاولة الأولى."

إذا كنت تعمل مع أدوات ترميز ذكاء اصطناعي أخرى جانب Cursor، تنتقل المفاهيم مباشرة. Claude Code يستخدم CLAUDE.md، وGitHub Copilot له ملفات تعليمات، وWindsurf له تنسيقه الخاص — لكن المبدأ الأساسي متطابق.

كيف تعمل أولوية القواعد

عندما تنطبق قواعد متعددة على نفس الملف، يتبع Cursor تسلسلاً هرمياً واضحاً:

Team Rules متاحة في خطط Team وEnterprise. يُعيّنها المسؤولون في لوحة تحكم Cursor وتُطبَّق على مستوى المؤسسة — لا يستطيع المطورون الأفراد إيقافها.

ضمن قواعد المشروع، إذا طُبّقت قاعدتان على نفس الملف وتعارضتا، فإن السلوك غير محدد بدقة. عملياً، القواعد المحمَّلة لاحقاً تميل إلى الأولوية. ترقيم ملفاتك (001-base.mdc، 002-components.mdc) يمنحك ترتيباً متوقعاً.

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

الأخطاء الشائعة وكيفية إصلاحها

بعد قراءة عشرات خيوط المجتمع واختبار القواعد عبر مشاريع متعددة، هذه هي الأخطاء التي تعثر فيها الناس أكثر:

كتابة قواعد مبهمة للغاية. "اكتب كوداً نظيفاً" لا يخبر الذكاء الاصطناعي بشيء. "استخدم exports ذات أسماء، لا exports افتراضية. رتّب المكونات كالتالي: imports، أنواع، دالة، مكونات فرعية" يمنحه شيئاً قابلاً للتنفيذ.

جعل كل شيء always-apply. الغريزة الأولى هي ضبط alwaysApply: true على كل قاعدة. قاوم ذلك. راجع قواعدك ربع سنوياً — إذا كان لديك أكثر من 2-3 قواعد دائمة التشغيل، فأنت على الأرجح تهدر الرموز.

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

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

تجاهل مشكلة حفظ القواعد في واجهة المستخدم. خطأ معروف يتسبب في اختفاء تعديلات القواعد. إذا اختفت التغييرات، أغلق Cursor بالكامل، اختر "Override" في نافذة التغييرات غير المحفوظة، وأعد الفتح.

Cursor Rules مقابل CLAUDE.md مقابل AGENTS.md

Cursor ليس الأداة الوحيدة التي تستخدم ملفات التعليمات. إليك مقارنة التنسيقات لمن يعمل مع مساعدات ترميز ذكاء اصطناعي متعددة:

ميزة Cursor هي الدقة. CLAUDE.md وAGENTS.md أبسط — تحمّل كل شيء دائماً. Cursor يتيح لك تحميل القواعد الصحيحة في الوقت الصحيح، وهذا مهم بمجرد أن تتجاوز مجموعة تعليماتك بضعة مئات من الأسطر.

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

الأسئلة الشائعة

هل .cursorrules قديم؟

نعم. ملف .cursorrules الواحد في جذر مشروعك لا يزال يعمل، لكن Cursor يوصي بالانتقال إلى ملفات .cursor/rules/*.mdc. يدعم التنسيق الجديد أنماط glob والتحميل الشرطي والتنظيم الأفضل. قم بالانتقال بتقسيم ملفك الأحادي إلى قواعد مركّزة.

أي امتداد ملف يجب استخدامه — .mdc أم .md؟

استخدم .mdc للملفات التي تتضمن frontmatter بصيغة YAML (description، globs، alwaysApply). ملفات .md العادية تعمل أيضاً في مجلد القواعد، لكنها لا تدعم بيانات frontmatter الوصفية التي تتيح التحميل الشرطي.

كم عدد القواعد التي ينبغي أن يمتلكها المشروع؟

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

هل تؤثر Cursor Rules على الإكمال التلقائي والإكمال بالتبويب؟

تنطبق القواعد على تفاعلات الدردشة والعميل. لا تنطبق User Rules على التعديلات المضمّنة (Cmd/Ctrl+K)، وعادةً لا تؤثر القواعد على اقتراحات الإكمال التلقائي لـ Cursor Tab. هي الأكثر فاعلية في جلسات الدردشة وComposer.

هل يمكنني مشاركة القواعد عبر مشاريع متعددة؟

نعم، عبر ميزة Remote Rules في Cursor. اذهب إلى Cursor Settings > Rules, Commands، اختر "Remote Rule (GitHub)"، والصق رابط مستودع. تُزامَن القواعد تلقائياً عند تحديث المستودع المصدر. بديلاً، احتفظ بمستودع قواعد مشترك وأنشئ روابط رمزية في كل مشروع.

ما الحد الأقصى الموصى به لطول القاعدة؟

تقترح وثائق Cursor الاحتفاظ بالقواعد الفردية تحت 500 سطر. عملياً، استهدف أقل من 100 سطر لكل قاعدة. القواعد الأقصر أسهل في الصيانة وتكلف رموزاً أقل. إذا تجاوزت قاعدة 150 سطراً، قسّمها إلى قاعدتين مركّزتين.

هل تعمل القواعد مع جميع نماذج الذكاء الاصطناعي في Cursor؟

تعمل القواعد مع كل نموذج يدعمه Cursor — Claude وGPT-4o وGemini وغيرها. تُحقن القواعد كسياق على مستوى النظام بغض النظر عن النموذج المحدد. قد يتفاوت سلوك النموذج، لكن القواعد نفسها محايدة تجاه النماذج.

كيف أصحّح قاعدة لا تعمل؟

أولاً، تحقق من تطابق نمط glob مع ملفك — افتح الملف وتحقق من ظهور القاعدة في لوحة السياق. ثانياً، اختبر بسؤال مباشر يجب أن يُشغّل القاعدة. ثالثاً، جرب ضبط alwaysApply: true مؤقتاً للتأكد من أن محتوى القاعدة نفسه يعمل. إذا نجح، فالمشكلة في نمط glob.

هل ينبغي أن أضيف .cursor/rules إلى git؟

بالتأكيد. الغرض الكامل من قواعد المشروع هو الاتساق على مستوى الفريق. أضف كل شيء في .cursor/rules/ ما عدا ملفات التفضيلات الشخصية. أضف personal.mdc إلى .gitignore للإعدادات الفردية التي لا ينبغي أن تنطبق على الجميع.

هل يمكنني استخدام Cursor Rules جنباً إلى جنب مع خوادم MCP؟

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

المصادر

• Cursor Rules Documentation
• Trigger.dev — How to Write Great Cursor Rules
• Cursor Forum — MDC Rules Best Practices and Troubleshooting
• Peakvance — Guide to Cursor Rules: Token Tax
• awesome-cursor-rules-mdc on GitHub