دليل Cursor الشامل — للاستخدام الاحترافي في المشاريع

1. الأساس

Cursor هو fork من VS Code، بس معاد بناؤه حول الـ AI بدل ما يكون extension مركّب فوقه. الفرق الجوهري: عنده vector index لكامل الـ repo — يعني يعرف عن الـ function اللي على بعد 3 ملفات، مش بس السطر اللي تكتب عليه.

أهم شي تفهمه: Cursor ما عنده "undo للـ AI" خاص فيه — بيعتمد على Git. أي جلسة Composer/Agent جدّية = branch جديد. هذا أهم guardrail عملي.

git checkout -b feat/mutliq-profile
# ... جلسة Composer ...
git diff main..HEAD     # راجع كل التغييرات قبل ما تـ commit

2. الأسطح الأربعة

السطح الاختصار متى تستخدمه Tab (تلقائي) autocomplete متعدد الأسطر أثناء الكتابة Inline Edit Cmd/Ctrl + K تعديل مركّز على دالة/بلوك محدد Chat Cmd/Ctrl + L أسئلة وفهم، بدون تعديل مباشر Composer Cmd/Ctrl + I تعديل multi-file في pass واحد Agent toggle داخل Composer Composer + استقلالية (terminal, tests, loop)

Tab — السطح الأكثر استخداماً

يشتغل على موديل Cursor الخاص (Sonic) بـ latency تحت 100ms. يستخدم 3 إشارات: تعديلاتك الأخيرة في الملفات المجاورة + السياق المحلي للملف + الـ project index.

أنماط شغّالة:

Refactor by example: غيّر استخدام واحد، وTab بيلاقي الباقي.
Mirror edits: ضيف column على Eloquent model، وTab يقترح التعديل المطابق على الـ migration والـ form request.
اكتب الـ assertion الأول في الـ test وخلّيه يكمّل الـ setup.

متى تطفّيه: التغييرات الصغيرة الحساسة (security check، migration هشّة) — Cmd/Ctrl+Shift+P → Cursor: Toggle Tab.

Inline Edit (`Cmd+K`)

أسرع طريقة لتغيير مركّز. ظلّل دالة، اكتب جملة، اقبل الـ diff:

Add error handling for network failures
Convert this to async/await with proper cancellation
Add Form Request validation for this controller method

Chat (`Cmd+L`) — تحكّم الـ context بـ @-mentions

هذا أقوى سلاح في Chat. بدل سؤال مبهم، حدّد بدقة:

Mention التأثير @file:src/auth.ts محتوى الملف كامل @folder:src/api listing للمجلد (استخدمه بحذر) @docs:laravel docs اللي ضفتها للـ index @code:OrderProcessor تعريف الـ symbol بس @web يسمح بـ web search @diff الـ Git diff الحالي @terminal آخر output من الـ terminal

البومبة: ادمجهم. مثلاً:

Using the pattern in @file:app/Services/PaymentService.php,
create a RefundService with the same structure

Composer (`Cmd+I`) — السوبر باور

يقرأ الملفات → يحدد شو يتغيّر وشو ينخلق → يقترح diffs عبر كل الملفات في شاشة مراجعة واحدة → يطبّق المقبول atomically.

مثال prompt لمطلق:

Add a user profile page at /profile showing order history
and a "cancel order" button for orders within 24h of placement.
Include:
- a controller method that loads orders
- a Blade/Vue component with the cancel handler
- a route + policy (only owner can cancel)
- a feature test for cancellation
Reference @file:app/Models/Order.php and @file:routes/web.php

Agent mode

Composer + استقلالية:

يشغّل terminal commands (مع approval gates)
يقرأ الـ output ويتفاعل معه
يشغّل tests → يحلّل الفشل → يصلّح → يكرّر لحتى يخضرّ
يستدعي MCP tools (DB query، Sentry trace، Linear)

guardrail أساسي: فعّل Settings → Agent → Require approval for destructive commands — بيجبر click على rm -rf، DROP TABLE، git push --force. الـ tests والـ builds والـ read-only تنقبل تلقائياً.

3. Rules

القاعدة الذهبية: إذا لقيت حالك بتكتب نفس التعليمة 3 مرات في 3 جلسات — مكانها في .cursor/rules/.

الصيغة الحديثة 2026 هي .cursor/rules/*.mdc (markdown + YAML frontmatter) — بدل ملف .cursorrules القديم.

بنية ملف الـ rule

---
description: API security rules
globs:
  - "app/Http/Controllers/Api/**/*.php"
alwaysApply: false
---

- Validate every request with a Form Request before any DB access
- Never log full request bodies in production
- Return a typed error envelope: { error: { code, message } }

ثلاث مفاتيح بتتحكم بكل شي:

المفتاح الوظيفة description سطر واحد، يظهر في panel الـ Rules globs أنماط الملفات اللي بتنطبق عليها الـ rule alwaysApply إذا true، تتحمّل دايماً بغض النظر عن الملف المفتوح

النقطة الذكية: لما alwaysApply: false وglobs محددة، الـ rule بتتحمّل بس لما الـ chat يلمس ملف مطابق — يعني تقدر تحتفظ بـ 20 rule بدون ما تضخّم الـ system prompt.

بنية موصى فيها (مثال Laravel + Vue)

.cursor/rules/
├── 000-project.mdc          # alwaysApply, نظرة عامة على المشروع
├── 100-php-laravel.mdc      # globs: **/*.php
├── 110-vue.mdc              # globs: **/*.vue
├── 200-api-security.mdc     # globs: app/Http/Controllers/Api/**
├── 300-database.mdc         # globs: database/**
├── 400-tests.mdc            # globs: tests/**
└── 900-style.mdc            # globs: **/*.{php,vue,css}

أرقام البادئة بتتحكم بترتيب الدمج — الأرقام الأصغر لها أولوية عند التعارض (نفس فكرة الـ middleware stacking).

نصيحة: استخدم أمر /Generate Cursor Rules من الـ chat — بيحلّل أنماط الـ codebase الموجودة ويولّد rules تلقائياً.

مصادر rules أخرى يقرأها Cursor

.cursorrules (القديم — للتوافق فقط)
agents.md في الـ root — المعيار المشترك بين كل الأدوات (Cursor, Copilot, Claude Code). استخدمه للمعايير المشتركة في فريق متعدد الأدوات.
User-global rules (Settings → Rules → User) — تفضيلاتك الشخصية اللي ما إلها مكان في الـ repo.

عند التعارض: project rules تغلب user rules، والـ globs المحددة تغلب alwaysApply: true. تأكّد بأمر Cursor: Show Active Rules.

4. MCP

MCP = معيار مفتوح لربط الـ agent بأدوات خارجية. عند الربط، Composer وAgent بيقدروا يستدعوا الأدوات (يسألوا DB، يجيبوا Sentry trace، ينشروا على Linear) بدون ما تنسخ وتلصق context.

الإعداد — ملفّين

عام: ~/.cursor/mcp.json
خاص بالمشروع: .cursor/mcp.json في الـ root (اعمله commit)

مثال config عملي:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "postgresql://localhost/mutliq_dev" }
    },
    "figma": {
      "type": "http",
      "url": "https://mcp.figma.com/mcp"
    }
  }
}

transports: stdio (process محلي — command + args) أو SSE/http (URL بعيد).

انتبه لـ 3 أمور:

حد الـ 40 tool — Cursor يرسل بس أول 40 tool للـ agent. لا تكدّس MCP servers.
الـ MCP ممكن ما يشتغل عبر SSH.
بعد أي تغيير على الـ config، اضغط Reload MCP servers.

MCP servers مفيدة لشغلك

Context7 — يجيب docs محدّثة لأي مكتبة (Laravel, Vue, Tailwind) داخل السياق
Postgres/MySQL — يسأل DB مباشرة بدل ما تكتب SQL
Figma — design-to-code (تفصيل بالأسفل)
Notion — قراءة/كتابة على workspace (تفصيل بالأسفل)
Sentry — يقرأ الـ stack trace ويصلّح الباغ

5. Hooks

Hooks = سكربتات (bash/Node/Python) تربطها بأحداث في الـ editor، موجودة في .cursor/hooks/ (أو .cursor/hooks.json).

Hook متى يشتغل onPreEdit قبل ما Composer يطبّق — يقدر يرفض التعديل onPostEdit بعد ما يكتب التغيير على القرص onPreCommit قبل ما الـ agent يعمل stage للـ commit onApprove لما تضغط Approve على diff

استخدامات عملية لشغلك:

منع التعديل على ملفات infra/production/ إلا بـ flag خاص
auto-format كل ملف يطبّقه Composer بـ Pint/Prettier قبل الحفظ
تشغيل php artisan test أو tsc --noEmit بعد كل تعديل وإرجاع الأخطاء للـ agent
إشعار Slack لما الـ agent يعمل commit على main

الفكرة: Hooks بتخلّي الـ agent داخل نفس الـ guardrails اللي بتفرضها على زميل بشري.

6. Skills, Subagents, Plugins

Skills (Pinned skills)

ملفات تعليمات قابلة لإعادة الاستخدام بتعمل لها pin عشان الـ agent يرجع لها. مفيدة للـ workflows المتكررة (مثلاً: "كيف تكتب Service class عندي"، "ستايل الـ API responses").

Subagents (Build in Parallel)

Cursor يشغّل حتى 8 agents بالتوازي، كل واحد معزول في Git worktree خاص فيه. مفيد للمهام الموزّعة:

agent يكتب الـ migration، وثاني يكتب الـ tests، وثالث يراجع
/best-of-n — يولّد عدة حلول وتختار الأفضل

كمان تقدر تعمل per-agent MCP scoping — تعطي agent واحد وصول لـ Linear MCP بدون ما تكشفه لباقي الأسطح.

Plugins

تركّب من marketplace. تربط GitHub, Figma, Linear, Slack مباشرة. كمان فيه مجتمع plugins تقدر توسّع فيه.

شو بلزمك فعلياً (لا تكدّس):

Plugin/MCP لـ Figma — للـ design-to-code
Plugin/MCP لـ GitHub — للـ PR workflow
Context7 — أهم واحد عملياً، يمنع hallucination في الـ API
الباقي: ضيفه لما تحتاجه فعلاً، مش استباقياً (تذكّر حد الـ 40 tool)

7. Figma → Code

هذا الـ workflow اللي بيطلع شغل محترم لو عملته صح. الـ Figma MCP يعطي الـ AI رؤية منظّمة ودقيقة للـ layout (node tree، variants، layout constraints، design tokens، asset references) — مش screenshot.

الإعداد

ضيف في .cursor/mcp.json:

{
  "mcpServers": {
    "Figma": {
      "type": "http",
      "url": "https://mcp.figma.com/mcp"
    }
  }
}

أعد تشغيل Cursor، وتأكّد إن السيرفر بيظهر نقطة خضراء (لو "0 tools" طفّيه ورجّعه).

طريقتان للعمل

Link-based: انسخ رابط frame من Figma والصقه في الـ prompt
Selection-based: اختر layer في Figma (واحد بس!) — السيرفر يشوف بس المختار

Workflow كامل (Figma → Vue/React + Tailwind)

ابدأ من بنية نظيفة — Cursor يشتغل أفضل مع structure منظّم
شغّل Agent mode وقول: "Use the Figma MCP to..."
prompt محكم:

Use this Figma frame and generate the component in Vue 3 + Tailwind.
Figma link: <LINK>
Constraints:
- Use existing components from @folder:resources/js/components
- Match spacing/typography exactly
- Keep it responsive
- Reuse the spacing scale and tokens already in this repo

prompts الإنقاذ (مهمة جداً لما يبدأ يعبث)

"Stop refactoring. Restore the original structure. Apply only the visual changes needed to match Figma."
"Reuse existing components, spacing scale, typography, and tokens already in this repo. Don't introduce new conventions."
"Keep logic intact. Restore handlers, links, forms, routing, and state."

الحدود (كن واقعي)

ضعيف في تحديث code موجود — ممتاز لتوليد components جديدة من الصفر، بس التعديل الجراحي على كود موجود صعب
multi-frame orchestration — flow من 5 frames ما بيركّبه لحاله، حدّه frame frame

8. اختبار الفرونت المباشر

هاي النقطة اللي بتفرق بين "كود يمرّ tests" و"كود يطلع حلو فعلاً".

المبدأ

الـ Agent مثل أي مهندس — إذا طلبت منه يبني واجهة بدون ما تعطيه browser يشوف فيها النتيجة، رح تطلع وحشة. لما يقدر يغلق الـ feedback loop بصرياً، بيكرّر لحتى تصير حلوة.

الطرق

Browser control / Browser Edit mode — الـ agent يفتح الصفحة، يشوفها، يعدّل بصرياً
lock the browser قبل سلسلة تفاعلات — عشان الـ agent ما يتسابق مع mouse البشري على نفس النافذة
@terminal للـ debugging — لما يطلع error، الـ agent يقرأه مباشرة ويصلّح

نمط TDD على autopilot (Playwright + MCP)

اربط Playwright بـ Cursor عبر MCP:

الـ agent يشغّل test → يفشل → يصلّح الكود → يتحقق → يكرّر

هذا يعطيك Test-Driven Development بشكل شبه تلقائي.

مراجعة كل diff (لا تتجاوزها)

"يمرّ الـ tests" سقف منخفض. راجع على كل diff:

Imports — مسارات صح، ما في dependencies مفاجئة
Error handling — exceptions محددة، ما في catch مبلوع
Naming — يطابق أعرافك
Side effects — هل لمس ملفات ما توقّعتها؟
Tests — هل الـ test يختبر السلوك فعلاً أم بس يمرّ type-check؟

9. Notion + GitHub + Background Agent

Notion (عبر MCP)

اربط Notion MCP في .cursor/mcp.json (SSE/http). بعدها الـ agent يقدر:

يقرأ task من Notion ويحوّله لكود
يحدّث صفحة Notion بعد ما يخلّص شغل
يطابق بين متطلبات في Notion والكود الموجود

هذا يربط workspace الـ Notion تبعك (Home Dashboard / Master Board) مباشرة بالكود.

GitHub + Background Agent

Background Agent = agent سحابي يشتغل في VM معزول، عنده نسخة مؤقتة من الـ repo، ويحوّل GitHub issue أو رسالة Slack لـ draft PR — بدون ما laptopك مفتوح.

الإعداد:

Settings → Background Agent → Connect GitHub (يركّب GitHub App)
اختر base image (Ubuntu مع Node/Python/etc) أو Dockerfile لـ toolchain خاص
أضف env vars/secrets (مشفّرة)
(اختياري) اربط Slack: @cursor fix the failing test in ...

loop واقعي:

1. تفتح GitHub issue وتعمل tag @cursor
2. الـ agent يلتقط الـ issue، يفتح branch، يصلّح
3. يكتب test، يشغّل السويت، يعمل commit وpush
4. يفتح PR ويعمل tag لك + إشعار Slack

متى مناسب: باغات قابلة لإعادة الإنتاج بمعايير واضحة، dependency upgrades، refactors روتينية، سد فجوات الـ test coverage. متى غير مناسب: أي شي بدّه product judgment، شغل يلمس infra خارج الـ repo، أو test suite غير موثوق (الـ agent رح يدور للأبد على tests متذبذبة).

حذر مالي: Background Agent يستهلك من نفس الـ metered spend — حط cap في Settings → Background Agent → Spend Limits.

BugBot — مراجعة PR تلقائية

GitHub App يراجع كل PR (بشري أو agent) وينشر تعليقات inline عن: باغات محتملة، error handling ناقص، inputs غير منظّفة، race conditions، انحرافات عن .cursor/rules/، وفجوات test. مسعّر منفصل ($40/user/شهر، مع free tier للـ public repos).

10. الموديل والتكلفة

هاي أهم نقطة بالنسبة لك بحكم حساسية التكلفة.

سياسة افتراضية ذكية

المهمة الموديل Tab Sonic (دايماً، شبه مجاني ضمن الخطة) Composer روتيني Composer-1 (أرخص بكثير من frontier) Chat / Inline عادي Sonnet (أفضل توازن) reasoning صعب / architecture / باغ معقّد Opus أو GPT (أغلى ~5×) context ضخم (monorepo كامل) Gemini (أكبر context window)

كيف توفّر فعلياً

بدّل default الـ Composer من Sonnet لـ Composer-1 — كثير ناس وفّروا 40–60% من فاتورتهم الشهرية بهالخطوة، واحتفظوا بـ Sonnet للمهام المعقّدة فقط
استخدم Chat (plan) قبل Composer — تنقيح الفكرة في chat أرخص بكثير من رفض outputs الـ Composer
كن صارم بـ @file scope — الـ prompts العامة بتسبّب استكشاف مكلف لكامل الـ codebase
النظام dollar-denominated (مش "500 fast requests" القديم) — راقبه real-time في Settings → Billing

الخطط (2026)

الخطة السعر الأنسب Free (Hobby) $0 تجربة Pro $20/شهر الافتراضي للمطور الفردي Pro+ $60/شهر لمن يضرب سقف Pro منتصف الشهر Ultra $200/شهر استخدام Composer/Agent يومي كثيف

ملاحظة: الأسعار والتفاصيل بتتغيّر — راجع Settings → Billing و cursor.com للأحدث.

11. خلاصة عملية

إعداد أول 10 دقائق على أي مشروع (مطلق مثلاً)

Import from VS Code عند أول تشغيل (extensions + keybindings + settings)
انتظر الـ Indexing يخلص (status bar)
أنشئ .cursor/rules/000-project.mdc بـ alwaysApply: true يشرح الـ stack
ضيف documentation sources في Settings → Indexing (Laravel, Vue docs)
استثنِ المجلدات المزعجة: node_modules, vendor, dist, .next
اضبط MCP: Context7 + (Figma/Postgres حسب الحاجة)
فعّل Require approval for destructive commands

الميزات اللي بتلزمك فعلاً (بترتيب الأولوية)

.cursor/rules/ — أكبر return؛ يوقف تكرار التعليمات
@-mentions — تحكّم دقيق بالـ context = أرخص وأدق
Composer + diff review — السوبر باور للـ multi-file
Context7 MCP — يمنع hallucination في API الـ Laravel/Vue
Figma MCP — لو شغلك فيه تحويل تصاميم
Git branch لكل جلسة — شبكة الأمان
Hooks (Pint/test بعد كل تعديل) — لما تنضج workflowك
Background Agent + BugBot — لما يصير عندك فريق/مشاريع متوازية

ما تستخدمه (لتجنّب التشتّت وحرق الـ budget)

لا تكدّس MCP servers (حد 40 tool)
لا تستخدم Opus للشغل الروتيني
لا تثق بـ Composer على codebase موجود في تحويل Figma بدون prompts إنقاذ
لا تطلق Background Agent على test suite متذبذب

مرجع مبني على docs.cursor.com وأدلة DeployHQ/Builder.io/Medium (2026). التفاصيل التقنية بتتغيّر مع إصدارات Cursor — راجع المصدر الرسمي قبل أي اعتماد حرج.