# أنظمة القواعد وتوجيه السلوك (/ar/docs/verdent-for-vscode/agents-rules/rule-systems)

> التحكم في سلوك Verdent من خلال أنظمة القواعد



ملفات القواعد هي مستندات Markdown تحدد كيفية تصرف Verdent واستجابته خلال جلسات الترميز. فهي توجّه سلوك وكيل الذكاء الاصطناعي، وتنسيق المخرجات، واتخاذ القرارات، والالتزام بمعايير المشروع.

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

**كيف تعمل القواعد:** يشير Verdent باستمرار إلى ملفات القواعد خلال المحادثات، ويطبّق الإرشادات على توليد الكود، والتحليل، والتوثيق، واتخاذ القرارات. تؤثر القواعد في كل استجابة للوكيل لضمان الاتساق مع تفضيلات المستخدم.

**ثلاث فئات:**

* **التفضيلات العامة** (VERDENT.md) - أسلوب الترميز الشخصي، تفضيلات اللغة
* **معايير خاصة بالمشروع** (AGENTS.md) - اصطلاحات الفريق، الأنماط المعمارية
* **تخصيص الخطة** (Plan.md) - تنسيق ومحتوى مخرجات Plan Mode

**أسبقية القواعد:** عند تعارض القواعد، يطبّق Verdent الأسبقية التالية: **AGENTS.md** (الأعلى) ← **VERDENT.md** (متوسطة) ← **الإعدادات الافتراضية** (الأدنى)

***

## قواعد المستخدم (VERDENT.md) [#قواعد-المستخدم-verdentmd]

يحدد ملف VERDENT.md التفضيلات العامة التي تُطبّق على جميع المشاريع والجلسات. فهو يضبط أسلوب الترميز الشخصي، والأدوات المفضلة، وتفضيلات التواصل، والسلوكيات الافتراضية.

### الموقع والنطاق [#الموقع-والنطاق]

**موقع الملف:** `~/.verdent/VERDENT.md`

**النطاق:** عام لجميع المشاريع

**الوصول:**

* الإعدادات ← القواعد ← قواعد المستخدم
* تحرير الملف مباشرة في `~/.verdent/VERDENT.md`

**بدء نفاذ التغييرات:** تُطبّق القواعد فورًا في المحادثات الجديدة وتؤثر في استجابات المحادثة الحالية.

***

### حالات الاستخدام [#حالات-الاستخدام]

<Tabs>
  <Tab title="تفضيلات الترميز">
    **تفضيلات الترميز**

    * أسلوب المسافة البادئة (مسافتان، أربع مسافات، مسافات جدولية)
    * اصطلاحات التسمية (camelCase، snake\_case، PascalCase)
    * ميزات اللغة المفضلة (ES6+، النمط الصارم في TypeScript، تلميحات الأنواع)

    حدد أسلوب الترميز والاصطلاحات الشخصية الخاصة بك المطبّقة على جميع المشاريع.
  </Tab>

  <Tab title="لغة المخرجات">
    **لغة المخرجات**

    * لغة الاستجابة الافتراضية (مثل "أجب دائمًا بالإسبانية")
    * معالجة المصطلحات التقنية ("استخدم المصطلحات الإنجليزية عند غياب مقابل فرنسي")

    تحكّم في اللغة التي يستخدمها Verdent في الاستجابات والتفسيرات.
  </Tab>

  <Tab title="تعليقات الكود">
    **تعليقات الكود**

    * مستوى التفصيل المفضل ("تعليقات مفصّلة" مقابل "تعليقات دنيا فقط")
    * لغة التعليقات ("اكتب التعليقات بالفرنسية")

    حدد مقدار التعليقات ولغتها في الكود.
  </Tab>

  <Tab title="التوثيق">
    **أسلوب التوثيق**

    * كيفية توثيق الكود (JSDoc، TSDoc، docstrings)
    * تضمين أمثلة استخدام في التوثيق

    ضع معايير لتوثيق API وتنسيق توثيق الكود.
  </Tab>

  <Tab title="التواصل">
    **التواصل**

    * نغمة الاستجابات وطولها ("تفسيرات مختصرة" مقابل "تفسيرات مفصّلة")
    * أسلوب التفسير ("أظهر الكود أولًا، ثم اشرح")

    خصّص طريقة تواصل Verdent وتقديمه للمعلومات إليك.
  </Tab>
</Tabs>

***

### التنسيق والصياغة [#التنسيق-والصياغة]

يستخدم VERDENT.md تنسيق Markdown العادي بنقاط أو قوائم مرقّمة.

**البنية:**

```markdown
# User Rules

## Code Style Preferences
- Always use TypeScript strict mode
- Prefer functional components in React
- Include JSDoc comments for exported functions

## Documentation
- Add JSDoc comments for all exported functions
- Include usage examples in component documentation

## Communication
- Provide explanations before showing code
- Highlight breaking changes explicitly
```

**أسلوب الكتابة:**

* استخدم لغة توجيهية واضحة ("استخدم دائمًا..."، "فضّل..."، "لا تستخدم أبدًا...")
* نظّم القواعد في أقسام منطقية بعناوين
* استخدم نقاطًا لكل قاعدة منفردة
* كن محددًا بشأن السلوك المطلوب

***

### أمثلة بحسب نوع المطوّر [#أمثلة-بحسب-نوع-المطوّر]

<Tabs>
  <Tab title="TypeScript">
    ```markdown
    # User Rules

    ## TypeScript Preferences
    - Use strict mode in tsconfig.json
    - Prefer interfaces over type aliases for object shapes
    - Include return types on all functions
    - Use const assertions where appropriate

    ## Code Organization
    - One component per file
    - Named exports instead of default exports
    - Organize imports: external, internal, types

    ## Documentation
    - TSDoc comments for public APIs
    - Include @param and @returns tags
    ```

    **التطبيق:** عندما تطلب من Verdent إنشاء مكوّن React جديد، فسيقوم تلقائيًا بـ:

    * استخدام TypeScript بالنمط الصارم
    * إنشاء export مسمّى (وليس default)
    * إضافة تعليقات TSDoc تحمل وسوم @param و@returns
    * تنظيم الاستيرادات (imports) بحسب الفئة
  </Tab>

  <Tab title="Python لعلوم البيانات">
    ```markdown
    # User Rules

    ## Python Style
    - Follow PEP 8 conventions
    - Use type hints for function signatures
    - Prefer list comprehensions over map/filter

    ## Data Analysis
    - Use pandas for data manipulation
    - Include DataFrame.head() after transformations
    - Document assumptions about data

    ## Output Format
    - Show shape and info() after operations
    - Include visualization examples
    ```

    **التطبيق:** عندما تطلب من Verdent كتابة كود لتحليل البيانات، فسيقوم بـ:

    * استخدام pandas لعمليات البيانات
    * تضمين تلميحات الأنواع (type hints) في جميع الدوال
    * عرض DataFrame.head() وshape بعد كل تحويل
    * إضافة تعليقات مضمّنة توثّق افتراضات البيانات
  </Tab>

  <Tab title="Full-Stack JS">
    ```markdown
    # User Rules

    ## JavaScript Preferences
    - Use ES6+ features (arrow functions, destructuring)
    - Async/await over promises
    - Template literals for string interpolation

    ## Testing
    - Jest for unit tests
    - Include test cases for edge conditions
    - Aim for 80%+ code coverage

    ## Code Review
    - Flag potential performance issues
    - Suggest security improvements
    ```

    **التطبيق:** سيقوم Verdent بـ:

    * كتابة جافاسكريبت حديثة بصياغة ES6+
    * استخدام async/await بدلًا من سلاسل الـ promise
    * توليد اختبارات Jest تستهدف تغطية 80%
    * تحديد المخاطر المتعلقة بالأداء والأمان بشكل استباقي
  </Tab>

  <Tab title="متعدد اللغات">
    ```markdown
    # User Rules

    ## Communication
    - Always respond in French
    - Use technical English terms when no French equivalent exists
    - Provide French variable/function names when appropriate

    ## Code Comments
    - Write comments in French
    - Documentation in both French and English
    ```

    **التطبيق:** ستكون جميع استجابات Verdent بالفرنسية، مع الحفاظ على المصطلحات التقنية بالإنجليزية عند الحاجة. ستتبع تعليقات الكود والتوثيق تفضيلات اللغة الخاصة بك.
  </Tab>

  <Tab title="الحد الأدنى">
    ```markdown
    # User Rules

    ## Code Style
    - Minimal comments - code should be self-documenting
    - Short, focused functions (< 20 lines)
    - Avoid unnecessary abstractions

    ## Output Preferences
    - Brief explanations
    - Show code first, explain after
    - No verbose documentation unless requested
    ```

    **التطبيق:** سيقوم Verdent بـ:

    * توليد كود مختصر يوثّق نفسه بنفسه
    * الحفاظ على الدوال بأقل من 20 سطرًا
    * تقديم تفسيرات مختصرة بعد عرض الكود
    * تجنّب التعليقات المطوّلة إلا إذا طلبت ذلك صراحةً
  </Tab>
</Tabs>

***

### كيفية الإنشاء والتحرير [#كيفية-الإنشاء-والتحرير]

<Tabs>
  <Tab title="قائمة الإعدادات">
    **موصى به لمعظم المستخدمين**

    1. حدد زر **الإعدادات** في الشريط العلوي لـ Verdent
    2. حدد **القواعد** من القائمة المنسدلة
    3. اختر **قواعد المستخدم**
    4. يُفتح الملف في محرر VS Code
    5. حرّر باستخدام تنسيق Markdown
    6. حفظ الملف (`Cmd+S` / `Ctrl+S`)

    تحدد هذه الطريقة موقع الملف تلقائيًا وتفتحه في محررك الافتراضي.
  </Tab>

  <Tab title="التحرير المباشر للملف">
    **موصى به للمستخدمين المتقدمين**

    1. انتقل إلى `~/.verdent/VERDENT.md`
    2. افتح الملف في أي محرر نصوص
    3. حرّر محتوى Markdown
    4. حفظ التغييرات

    هذه الطريقة أسرع إذا كنت تفضّل التعامل مباشرة مع ملفات الإعداد.
  </Tab>
</Tabs>

***

## قواعد المشروع (AGENTS.md) [#قواعد-المشروع-agentsmd]

يحدد ملف AGENTS.md القواعد الخاصة بالمشروع التي تتحكم في سلوك الوكيل للمشروع الحالي. فهو يضبط معايير ترميز الفريق، والأنماط المعمارية، ومتطلبات الاختبار، وسير عمل التطوير الخاص بالمشروع.

### الموقع والنطاق [#الموقع-والنطاق-1]

**موقع الملف:** المجلد الجذر للمشروع

**النطاق:** المشروع الحالي فقط

**التحكم بالإصدارات:** يمكن الالتزام به (commit) إلى git للمشاركة على مستوى الفريق

**الوصول:**

* الإعدادات ← القواعد ← قواعد المشروع
* التحرير المباشر في `<project-root>/AGENTS.md`

***

### حالات الاستخدام [#حالات-الاستخدام-1]

<Tabs>
  <Tab title="اصطلاحات الفريق">
    **اصطلاحات الفريق**

    معايير ترميز مشتركة يتبعها جميع أعضاء الفريق:

    * مسافة بادئة متسقة عبر الفريق
    * اصطلاحات تسمية المكوّنات/الدوال
    * أنماط تنظيم الملفات

    فرض أسلوب ترميز متسق عبر فريق التطوير بالكامل.
  </Tab>

  <Tab title="البنية المعمارية">
    **الأنماط المعمارية**

    أنماط تصميم خاصة بالمشروع:

    * MVC، الخدمات المصغرة، بنية monorepo
    * أسلوب إدارة الحالة (Redux، Context، Zustand)
    * أنماط تصميم API (REST، GraphQL)

    حدد القرارات والأنماط المعمارية للمشروع.
  </Tab>

  <Tab title="الاختبار">
    **متطلبات الاختبار**

    تغطية الاختبار وأطر العمل المتوقعة:

    * حدود التغطية الدنيا (80%، 90%)
    * أطر الاختبار (Jest، pytest، Vitest)
    * اصطلاحات تسمية ملفات الاختبار

    حدد معايير الاختبار وبوابات الجودة للمشروع.
  </Tab>

  <Tab title="سير العمل">
    **سير عمل التطوير**

    أوامر البناء، وإجراءات النشر، وإرشادات طلبات السحب (PR):

    * كيفية تشغيل الاختبارات (`pnpm test`، `npm run test`)
    * أوامر البناء لحزم محددة
    * متطلبات تنسيق عنوان طلب السحب

    وثّق سير عمل الفريق وإجراءات التطوير.
  </Tab>

  <Tab title="التقنية">
    **قيود التقنية**

    المكتبات وإصدارات الأطر المعتمدة:

    * التبعيات المسموح بها
    * متطلبات إصدار الإطار
    * دعم المنصات (iOS 14+‎، Android API 26+‎)

    تحكّم في اختيارات مكدّس التقنية وحافظ على الاتساق.
  </Tab>
</Tabs>

**تعاون الفريق:** يُخزَّن ملف AGENTS.md في المجلد الجذر للمشروع ويمكن الالتزام به (commit) إلى نظام التحكم بالإصدارات، مما يضمن أن يعمل جميع أعضاء الفريق بسلوك وكيل متسق.

<Tip>
  شارك ملف AGENTS.md مع فريقك عبر نظام التحكم بالإصدارات لضمان سلوك متسق للذكاء الاصطناعي عبر جميع أعضاء الفريق.
</Tip>

***

### التنسيق والصياغة [#التنسيق-والصياغة-1]

يستخدم AGENTS.md تنسيق Markdown بأقسام منظمة ونقاط، على غرار VERDENT.md لكن بتركيز على متطلبات خاصة بالمشروع.

**البنية:**

```markdown
# AGENTS.md

## Dev environment tips
- Command for navigating workspace
- Installation commands
- Environment setup instructions

## Testing instructions
- Test execution commands
- Coverage requirements
- CI/CD integration details

## PR instructions
- Title format requirements
- Pre-commit checklist
- Review guidelines
```

**أسلوب الكتابة:**

* لغة توجيهية وأمرية
* منظّم بحسب مجال سير العمل (التطوير، الاختبار، النشر)
* أوامر وإجراءات محددة
* معايير على مستوى الفريق، لا تفضيلات شخصية

***

### أمثلة بحسب نوع المشروع [#أمثلة-بحسب-نوع-المشروع]

<Tabs>
  <Tab title="Monorepo">
    ```markdown
    # AGENTS.md

    ## Dev environment tips
    - Use `pnpm dlx turbo run where <project_name>` to jump to a package
    - Run `pnpm install --filter <project_name>` to add package to workspace
    - Check the name field in package.json to confirm the right name

    ## Testing instructions
    - Run `pnpm turbo run test --filter <project_name>` for all checks
    - From package root: `pnpm test`
    - Focus on one test: `pnpm vitest run -t "<test name>"`
    - Fix all errors before merge

    ## PR instructions
    - Title format: [<project_name>] <Title>
    - Always run `pnpm lint` and `pnpm test` before committing
    ```

    **التطبيق:** عند العمل على هذا الـ monorepo، سيقوم Verdent بـ:

    * استخدام أوامر turbo للتنقل والاختبار
    * تنسيق عناوين طلبات السحب مع بادئة اسم المشروع
    * تشغيل أوامر lint والاختبار قبل اقتراح أي commit
  </Tab>

  <Tab title="React/TypeScript">
    ```markdown
    # AGENTS.md

    ## Code Standards
    - Use functional components with hooks
    - TypeScript strict mode required
    - Named exports only (no default exports)
    - PropTypes or TypeScript interfaces for all components

    ## File Organization
    - One component per file
    - Components in `src/components/`
    - Hooks in `src/hooks/`
    - Utils in `src/utils/`

    ## Testing
    - Jest + React Testing Library
    - Test all user interactions
    - 80%+ coverage required
    ```

    **التطبيق:** جميع مكوّنات React التي يُنشئها Verdent ستقوم بـ:

    * استخدام مكوّنات وظيفية (functional components) مع hooks
    * تضمين واجهات TypeScript (interfaces)
    * الوضع في المجلد الصحيح
    * تضمين اختبارات Jest تستهدف تغطية 80%
  </Tab>

  <Tab title="خادم API">
    ```markdown
    # AGENTS.md

    ## API Standards
    - All endpoints include input validation
    - Use async/await for asynchronous operations
    - Consistent error format: { error: string, code: number }
    - Rate limiting on public endpoints

    ## Security
    - Never log sensitive data (passwords, tokens, PII)
    - Parameterized queries only (prevent SQL injection)
    - Validate and sanitize all inputs

    ## Testing
    - Unit tests for all business logic
    - Integration tests for API endpoints
    - Test success and error cases
    ```

    **التطبيق:** عند إنشاء نقاط نهاية API، سيقوم Verdent بـ:

    * إضافة التحقق من صحة المدخلات تلقائيًا
    * استخدام استعلامات معلمة (parameterized queries) لعمليات قاعدة البيانات
    * توليد اختبارات لحالات النجاح والفشل معًا
    * تجنّب تسجيل البيانات الحساسة في السجلات (logs)
  </Tab>

  <Tab title="تطبيق الموبايل">
    ```markdown
    # AGENTS.md

    ## Platform Support
    - iOS 14+ and Android API 26+
    - React Native 0.72+
    - Test on both platforms before PR

    ## State Management
    - Use Redux Toolkit
    - Async operations with Redux Thunk
    - Normalize state shape

    ## Performance
    - Images: WebP format, max 500KB
    - Bundle size: monitor with bundle analyzer
    - FlatList for long lists (>20 items)
    ```

    **التطبيق:** سيقوم كود تطبيق الموبايل بـ:

    * دعم الإصدارات الدنيا للمنصات
    * استخدام Redux Toolkit لإدارة الحالة
    * تحسين الصور إلى تنسيق WebP
    * استخدام FlatList لتحسين الأداء في القوائم الطويلة
  </Tab>

  <Tab title="Python Django">
    ```markdown
    # AGENTS.md

    ## Django Conventions
    - Follow Django best practices and PEP 8
    - Class-based views preferred
    - Django ORM for database operations
    - Migrations: never edit generated files

    ## Testing
    - pytest-django for all tests
    - Factory Boy for test fixtures
    - Coverage must be 90%+

    ## Deployment
    - Docker compose for local development
    - Environment variables in .env (never committed)
    - Run migrations before deployment
    ```

    **التطبيق:** سيقوم كود Django بـ:

    * استخدام العروض القائمة على الفئات (class-based views)
    * استخدام Django ORM بدلًا من SQL الخام
    * توليد اختبارات pytest باستخدام fixtures من Factory Boy
    * استهداف تغطية اختبار بنسبة 90% أو أعلى
  </Tab>
</Tabs>

***

### الاختلافات عن VERDENT.md [#الاختلافات-عن-verdentmd]

**النطاق:**

* **VERDENT.md:** تفضيلات شخصية عبر جميع المشاريع
* **AGENTS.md:** معايير الفريق لمشروع محدد فقط

**الأولوية:**

* **AGENTS.md:** أسبقية أعلى - تتجاوز قواعد المستخدم لضمان اتساق المشروع
* **VERDENT.md:** أسبقية أدنى - تُطبَّق عندما لا تتعارض مع قاعدة خاصة بالمشروع

**تركيز المحتوى:**

* **VERDENT.md:** أسلوب الترميز الفردي، تفضيلات التواصل، الأدوات الشخصية
* **AGENTS.md:** اصطلاحات الفريق، بنية المشروع، سير العمل المشترك، مكدّس التقنية

**التحكم بالإصدارات:**

* **VERDENT.md:** غير مشترك - يبقى على جهاز الفرد
* **AGENTS.md:** يُلتزَم به (commit) إلى git - مشترك مع الفريق بالكامل

**التخزين:**

* **VERDENT.md:** `~/.verdent/VERDENT.md` (عام)
* **AGENTS.md:** المجلد الجذر للمشروع (خاص بالمشروع)

**مثال على حل التعارض:**

```
VERDENT.md: "I prefer 2-space indentation"
AGENTS.md: "This project uses 4-space indentation"
→ Result: 4-space indentation (team standard wins)
```

**متى تستخدم كل واحد:**

* **VERDENT.md:** التفضيلات الشخصية التي تريدها عبر جميع المشاريع
* **AGENTS.md:** المعايير التي يجب أن يتبعها الفريق بالكامل لهذا المشروع

***

## قواعد الخطة (Plan.md) [#قواعد-الخطة-planmd]

يخصّص ملف Plan.md محتوى وتنسيق الخطط المُولَّدة في Plan Mode. فهو يتحكم في مستوى تفصيل الخطة، والأقسام المضمّنة، وتفضيلات التنسيق، والمعلومات المعروضة.

### الموقع والنطاق [#الموقع-والنطاق-2]

**موقع الملف:** \~/.verdent/plan\_settings.json

**النطاق:** عام لجميع المشاريع

**التطبيق:** يُطبَّق فقط خلال Plan Mode عند توليد الخطط

**الوصول:**

* الإعدادات ← القواعد ← قواعد الخطة
* تحرير الملف مباشرة في \~/.verdent/plan\_settings.json

***

### حالات الاستخدام [#حالات-الاستخدام-2]

<Tabs>
  <Tab title="بنية الخطة">
    **بنية الخطة**

    حدد الأقسام المطلوب تضمينها:

    * الملخص، المتطلبات المسبقة، الخطوات، التحقق
    * تقييم المخاطر، إجراءات التراجع
    * تقديرات الوقت، المسار الحرج

    تحكّم في الأقسام والمعلومات التي تظهر في كل خطة.
  </Tab>

  <Tab title="مستوى التفصيل">
    **مستوى التفصيل**

    تحكّم في مستوى الدقة:

    * نظرة عامة عالية المستوى (مراحل من ساعة إلى ساعتين لكل منها)
    * خطوات تنفيذ مفصّلة (مهام من 15 إلى 30 دقيقة)
    * تفاصيل على مستوى الدوال (التوقيعات، مسارات الملفات)

    اضبط مستوى التفصيل والدقة المطلوبة في خطط التنفيذ.
  </Tab>

  <Tab title="التنسيق">
    **تفضيلات التنسيق**

    اختر أسلوب العرض:

    * القوائم المرقّمة مقابل النقاط
    * مقتطفات الكود مقابل الوصف
    * المخططات (موصوفة نصيًا)

    خصّص كيفية تنسيق وعرض معلومات الخطة.
  </Tab>

  <Tab title="المعلومات">
    **تضمين المعلومات**

    حدد عناصر إضافية:

    * تقديرات الوقت داخل النص
    * مستويات الخطورة (منخفضة/متوسطة/عالية)
    * تعيين الأدوار للتعاون الجماعي
    * التركيز على متطلبات الاختبار

    أضف سياقًا وبيانات وصفية لجعل الخطط أكثر قابلية للتنفيذ.
  </Tab>
</Tabs>

***

### التنسيق والصياغة [#التنسيق-والصياغة-2]

يستخدم Plan.md تنسيق Markdown بأقسام تصف بنية ومحتوى الخطة المطلوبة.

**البنية:**

```markdown

---
name: Plan Rules
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Start with brief summary (2-3 sentences)
- Include estimated time for each major step
- List prerequisites before implementation steps
- Identify potential risks

## Level of Detail
- Break tasks into subtasks of 15-30 minutes
- Include specific file paths for modifications
- List functions/components to create/modify

## Format
- Use numbered lists for sequential steps
- Use bullet points for options
- Include code snippets for complex changes
```

***

### أمثلة بحسب أسلوب التخطيط [#أمثلة-بحسب-أسلوب-التخطيط]

<Tabs>
  <Tab title="تقني مفصّل">
    ```markdown
    ---
    name: Detailed Technical
    version: 1.0.0
    last_updated: 2025-11-26
    ---

    ## Plan Structure
    - Executive summary (2-3 sentences)
    - Prerequisites and dependencies
    - Numbered implementation steps
    - Testing and verification strategy
    - Rollback procedures

    ## Level of Detail
    - Break into 20-30 minute tasks
    - Specific file paths for all modifications
    - Function signatures for new code
    - Database schema changes with migration steps

    ## Format
    - Numbered lists for sequence
    - Code blocks for complex logic
    - Diagrams for architecture changes (describe verbally)
    ```

    **التطبيق:** ستضمّن الخطط:

    * ملخصًا تنفيذيًا في الأعلى
    * تقسيم المهام إلى فترات 20-30 دقيقة
    * مسارات ملفات محددة مثل `src/components/Auth/Login.tsx`
    * توقيعات دوال مثل `async function authenticateUser(credentials: UserCredentials): Promise<AuthResult>`
    * إجراءات الاختبار والتراجع
  </Tab>

  <Tab title="استراتيجي عالي المستوى">
    ```markdown
    ---
    name: High-Level Strategic
    version: 1.0.0
    last_updated: 2025-11-26
    ---

    ## Plan Structure
    - Brief overview (1 paragraph)
    - Major phases only (3-5 high-level steps)
    - Key decisions and trade-offs
    - Success criteria

    ## Level of Detail
    - High-level phases (1-2 hours each)
    - Avoid implementation specifics
    - Focus on approach and strategy

    ## Format
    - Bullet points for flexibility
    - Minimal code examples
    - Emphasize "why" over "how"
    ```

    **التطبيق:** ستكون الخطط عالية المستوى، وتركّز على:

    * النهج الاستراتيجي في 3-5 مراحل رئيسية
    * تفسيرات "السبب" أكثر من تفاصيل التنفيذ
    * نقاط القرار والمفاضلات
    * معايير النجاح دون تفاصيل تنفيذ محددة
  </Tab>

  <Tab title="مراعٍ للوقت">
    ```markdown
    ---
    name: Time-Conscious
    version: 1.0.0
    last_updated: 2025-11-26
    ---

    ## Plan Structure
    - Time estimates for each step
    - Total project duration estimate
    - Parallel tasks identified
    - Critical path highlighted

    ## Level of Detail
    - Tasks sized to 30-minute increments
    - Dependencies clearly marked
    - Blocking operations identified

    ## Format
    - Include time estimates inline
    - Mark parallel tasks
    - Highlight critical path with bold
    ```

    **التطبيق:** ستضمّن الخطط:

    * كل خطوة مع تقدير للوقت: "إنشاء وسيط المصادقة (45 دقيقة)"
    * المدة الإجمالية: "التقدير الإجمالي: 6 ساعات"
    * تحديد المهام المتوازية: "يمكن تنفيذها بالتوازي مع الخطوة 3"
    * تمييز المسار الحرج بخط عريض لإظهار العمليات المعطّلة (blocking)
  </Tab>

  <Tab title="مركّز على المخاطر">
    ```markdown
    ---
    name: Risk-Focused
    version: 1.0.0
    last_updated: 2025-11-26
    ---

    ## Plan Structure
    - Risk assessment for each phase
    - Mitigation strategies included
    - Rollback procedures defined
    - Testing requirements emphasized

    ## Level of Detail
    - Identify potential failure points
    - Document error handling approach
    - Include recovery procedures

    ## Format
    - Risk levels: low, medium, high
    - Separate "Risks" section for each phase
    - Mitigation steps in sub-bullets
    ```

    **التطبيق:** ستضمّن كل مرحلة:

    * تقييم المخاطر: "الخطورة: عالية (ترحيل قاعدة بيانات في بيئة الإنتاج)"
    * التخفيف: "شغّل الترحيل على بيئة staging أولًا، وتحقق من خلال استعلامات اختبارية"
    * التراجع: "استرجع الترحيل باستخدام سكربت down في حال حدوث مشكلات"
  </Tab>

  <Tab title="التعاون الجماعي">
    ```markdown
    ---
    name: Team Collaboration
    version: 1.0.0
    last_updated: 2025-11-26
    ---

    ## Plan Structure
    - Role assignments for each task
    - Coordination points identified
    - Review checkpoints included
    - Communication requirements

    ## Level of Detail
    - Specify who handles each component
    - List integration points between team members
    - Include pair programming opportunities

    ## Format
    - Use mentions for role assignments
    - Mark collaboration points
    - Include "Review required" markers
    ```

    **التطبيق:** ستحدد الخطط:

    * "خادم API (فريق الخادم): إنشاء نقاط نهاية المصادقة"
    * "نقطة التكامل: فريق الواجهة الأمامية ينتظر مواصفة API من فريق الخادم"
    * "مراجعة مطلوبة: مراجعة فريق الأمان قبل الدمج (merge)"
  </Tab>
</Tabs>

***

### متى تُطبَّق قواعد الخطة؟ [#متى-تُطبَّق-قواعد-الخطة]

**تطبيق قواعد الخطة:**

* **التوقيت:** تُطبَّق فقط خلال Plan Mode عند توليد الخطط
* **النطاق:** تتحكم في تنسيق ومحتوى الخطة، لا في توليد الكود
* **الاستقلالية:** لا تتعارض مع VERDENT.md أو AGENTS.md

**تطبيق أنواع القواعد الأخرى:**

* **VERDENT.md:** تُطبَّق باستمرار عبر جميع الأنماط (Agent، Plan، Chat)
* **AGENTS.md:** تُطبَّق باستمرار عبر جميع الأنماط للسلوك الخاص بالمشروع

**مثال على التفاعل:**

```
Plan Mode activated:
1. VERDENT.md: "Use TypeScript" → Applied to code in plan
2. AGENTS.md: "Follow project conventions" → Applied to approach
3. plan_rules.md: "Include time estimates" → Applied to plan format
→ Result: Plan shows TypeScript code following project conventions with time estimates
```

**السلوك الخاص بكل نمط:**

* **Agent Mode:** تُطبَّق VERDENT.md + AGENTS.md (بدون plan\_rules.md)
* **Plan Mode:** تُطبَّق VERDENT.md + AGENTS.md + Plan.md معًا
* **Chat Mode:** تُطبَّق VERDENT.md + AGENTS.md (بدون Plan.md)

***

## أسبقية القواعد وحل التعارضات [#أسبقية-القواعد-وحل-التعارضات]

عند تعارض القواعد، يطبّق Verdent أسبقية معينة لضمان سلوك متسق.

### ترتيب الأسبقية [#ترتيب-الأسبقية]

**1. قواعد المشروع (AGENTS.md) - الأولوية الأعلى** تتجاوز القواعد الخاصة بالمشروع التفضيلات العامة. تحظى معايير الفريق بالأسبقية على التفضيلات الفردية من أجل الاتساق.

**2. قواعد المستخدم (VERDENT.md) - أولوية متوسطة** تُطبَّق التفضيلات العامة عندما لا تتعارض مع قاعدة خاصة بالمشروع.

**3. السلوك الافتراضي - الأولوية الأدنى** تُطبَّق الإعدادات الافتراضية المدمجة في Verdent عند عدم تحديد أي قواعد.

**مثال على حل التعارض:**

```
VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation for this project"
→ Result: Verdent uses 4-space indentation (project rules win)
```

**قواعد الخطة:** يُطبَّق Plan.md بشكل مستقل خلال Plan Mode ولا يتعارض مع قواعد المستخدم/المشروع. فهو يتحكم في تنسيق الخطة، بينما تتحكم VERDENT.md وAGENTS.md في أسلوب الكود ضمن الخطة.

<Note>
  تؤثر قواعد الخطة فقط في تنسيق مخرجات Plan Mode. ولا تغيّر كيفية تحليل Verdent للحلول أو تنفيذه لها.
</Note>

<Tip>
  تذكّر ترتيب الأسبقية: AGENTS.md (الأعلى) ← VERDENT.md (متوسطة) ← الإعدادات الافتراضية (الأدنى). تفوز قواعد المشروع دائمًا في حالات التعارض.
</Tip>

<Info>
  خوارزميات حل التعارض التفصيلية، وآليات معرفة القاعدة المطبَّقة عند التعارض، وآليات التجاوز لتعليق القواعد مؤقتًا، جميعها قيد التطوير حاليًا.
</Info>

***

### استكشاف تعارضات القواعد وإصلاحها [#استكشاف-تعارضات-القواعد-وإصلاحها]

عندما تلاحظ سلوكًا غير متوقع يتعارض مع قاعدة، اتبع استراتيجية التشخيص التالية:

#### الخطوة 1: تحديد التعارض [#الخطوة-1-تحديد-التعارض]

1. لاحظ السلوك غير المتوقع الذي يتعارض مع قاعدة
2. تحقق من القواعد التي قد تنطبق على الحالة
3. ابحث عن تعارضات بين ملفات القواعد

#### الخطوة 2: تحقق من أسبقية القواعد [#الخطوة-2-تحقق-من-أسبقية-القواعد]

```
AGENTS.md (highest) → VERDENT.md (medium) → defaults (lowest)
```

تتجاوز قواعد المشروع التفضيلات الشخصية.

#### الخطوة 3: اختبر بشكل منعزل [#الخطوة-3-اختبر-بشكل-منعزل]

**تعطيل VERDENT.md:** أعد تسمية الملف أو أفرغ محتواه مؤقتًا، واختبر إذا انحل التعارض

**الاختبار بدون AGENTS.md:** اعمل في المشروع بدون AGENTS.md لعزل سلوك قواعد المستخدم

**محادثة جديدة:** ابدأ جلسة جديدة لاستبعاد تأثير سياق المحادثة

***

### سيناريوهات التعارض الشائعة [#سيناريوهات-التعارض-الشائعة]

#### السيناريو 1: تعارض في التنسيق [#السيناريو-1-تعارض-في-التنسيق]

```
VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation"
→ Resolution: AGENTS.md wins (project standard)
→ Fix: Accept project standard or discuss with team
```

#### السيناريو 2: قواعد متناقضة في الملف نفسه [#السيناريو-2-قواعد-متناقضة-في-الملف-نفسه]

```
AGENTS.md:
- "Prefer functional components"
- "Use class components for complex state"
→ Resolution: Verdent interprets based on context
→ Fix: Clarify when each rule applies
```

مثال على الإصلاح:

```markdown
- Prefer functional components for simple UI
- Use functional components with hooks for complex state
- Only use class components for legacy code maintenance
```

#### السيناريو 3: قاعدة غامضة جدًا [#السيناريو-3-قاعدة-غامضة-جدًا]

```
"Write good tests"
→ Problem: What is "good"?
→ Fix: "Generate unit tests with 80%+ coverage, include edge cases"
```

***

### استراتيجية التشخيص [#استراتيجية-التشخيص]

**1. اختبار صريح:** اسأل Verdent "ما القاعدة التي تتبعها فيما يخص \[سلوك محدد]؟"

مثال:

```
You: "Which rule are you following for indentation?"
Verdent: "I'm using 4-space indentation from AGENTS.md (line 12),
which overrides your VERDENT.md preference for 2-space indentation."
```

**2. تحسين تدريجي:** أضف مزيدًا من التحديد إلى القواعد الغامضة

<Tip>
  عند تشخيص تعارضات القواعد، عطّل القواعد واحدة تلو الأخرى مؤقتًا لعزل القاعدة المسبّبة للسلوك غير المتوقع.
</Tip>

قبل:

```markdown
- Use appropriate error handling
```

بعد:

```markdown
- Wrap async operations in try/catch blocks
- Return error objects with message and code fields
- Log errors with context (function name, input parameters)
```

**3. علامات الأولوية:** استخدم "CRITICAL:" أو "REQUIRED:" للقواعد غير القابلة للتفاوض

```markdown
## Security Rules
- **CRITICAL:** Never log passwords, API keys, or tokens
- **REQUIRED:** All user inputs must be validated and sanitized
- Preferred: Use parameterized queries for database operations
```

***

### أفضل الممارسات لكتابة القواعد [#أفضل-الممارسات-لكتابة-القواعد]

**كن محددًا وتوجيهيًا:**

* استخدم لغة أمرية واضحة ("استخدم دائمًا..."، "لا تفعل أبدًا..."، "فضّل...")
* تجنّب الصياغة الغامضة ("حاول أن..." ← "استخدم دائمًا...")
* اذكر بالضبط ما تريده، وليس ما لا تريده

**جيد:**

```markdown
- Use async/await for asynchronous operations
- Include JSDoc comments for all exported functions
```

**تجنّب:**

```markdown
- Try to use modern JavaScript features
- Add comments when necessary
```

**نظّم منطقيًا:**

* اجمع القواعد ذات الصلة تحت عناوين أقسام
* افصل بين الاهتمامات المختلفة (الأسلوب، الاختبار، التوثيق، الأمان)
* استخدم بنية متسقة عبر ملفات القواعد

**حافظ على قابلية القواعد للصيانة:**

* اكتب قواعد مختصرة (مفهوم واحد لكل نقطة)
* راجع القواعد وحدّثها مع تطور المشروع
* أزل القواعد المتقادمة فورًا

**رتّب القواعد المهمة بحسب الأولوية:**

* ضع القواعد الحرجة أولًا في كل قسم
* استخدم التأكيد للمعايير غير القابلة للتفاوض ("**لا ترتكب** أبدًا بيانات اعتماد في commit")
* ركّز على القواعد التي تمنع الأخطاء أو المشكلات الأمنية

**اختبر فعالية القواعد:**

* تحقق من أن Verdent يتبع القواعد فعليًا
* ابدأ محادثة جديدة لاختبار تطبيق القاعدة
* حسّن القواعد بناءً على سلوك الوكيل الفعلي

**وازن بين التفصيل والمرونة:**

* تفصيل مفرط ← سلوك متصلّب لا يتكيف
* غموض مفرط ← سلوك غير متسق
* استهدف إرشادات واضحة مع مساحة لقرارات مناسبة للسياق

**اعتبارات الفريق (AGENTS.md):**

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

***

## انظر أيضًا [#انظر-أيضًا]

<CardGroup cols="2">
  <Card title="إدارة الوكلاء الفرعيين" icon="robot" href="/docs/verdent-for-vscode/agents-rules/subagent-management">
    إنشاء وإدارة وكلاء فرعيين متخصصين للمهام الخاصة بالمشروع
  </Card>

  <Card title="أفضل الممارسات: Prompts" icon="message-lines" href="/docs/verdent-for-vscode/best-practices/prompts">
    كتابة prompts فعّالة للاستفادة القصوى من VerdentP
  </Card>
</CardGroup>