انتقل إلى المحتوى الرئيسي

أفضل الممارسات لـ .cursor/rules

.cursor/rules هي ميزة قوية تساعد الفرق على الحفاظ على معايير ترميز متسقة وتحسين التعاون. يغطي هذا الدليل أفضل الممارسات لإعداد وإدارة القواعد بفعالية.

فهم .cursor/rules​

.cursor/rules هو نظام تكوين يقوم بما يلي:

  • تحديد معايير الترميز على مستوى المشروع
  • أتمتة تنظيم الكود
  • فرض أنماط متسقة
  • تحسين تعاون الفريق

الإعداد الأساسي​

إنشاء ملف القواعد​

قم بإنشاء ملف .cursor/rules في جذر مشروعك:

mkdir .cursor
touch .cursor/rules

الهيكل الأساسي​

هيكل نموذجي لملف القواعد:

version: 1.0
rules:
  - name: "هيكل المكون"
    pattern: "src/components/**/*.{ts,tsx}"
    template: |
      import React from 'react'
      
      interface ${ComponentName}Props {
        // الخصائص
      }
      
      export const ${ComponentName}: React.FC<${ComponentName}Props> = () => {
        return (
          <div>
            {/* محتوى المكون */}
          </div>
        )
      }

  - name: "طبقة الخدمة"
    pattern: "src/services/**/*.ts"
    template: |
      import { ApiClient } from '../utils/apiClient'
      
      export class ${ServiceName}Service {
        private client: ApiClient
        
        constructor() {
          this.client = new ApiClient()
        }
        
        // طرق الخدمة
      }

أفضل الممارسات​

1. اصطلاحات التسمية المتسقة​

استخدم أسماء واضحة ووصفية للقواعد:

rules:
  - name: "مكون React"
    description: "هيكل مكون React قياسي"
    pattern: "src/components/**/*.tsx"

  - name: "خدمة API"
    description: "قالب خدمة REST API"
    pattern: "src/services/**/*.ts"

2. التنظيم النمطي​

قم بتجميع القواعد ذات الصلة:

rules:
  # قواعد المكونات
  - name: "مكون/وظيفي"
    pattern: "src/components/**/*.tsx"
    
  - name: "مكون/صنف"
    pattern: "src/components/**/*.class.tsx"
    
  # قواعد الخدمات
  - name: "خدمة/REST"
    pattern: "src/services/rest/**/*.ts"
    
  - name: "خدمة/GraphQL"
    pattern: "src/services/graphql/**/*.ts"

3. متغيرات القالب​

استخدم متغيرات قالب وصفية:

rules:
  - name: "قالب المكون"
    pattern: "src/components/**/*.tsx"
    template: |
      interface ${ComponentName}Props {
        ${PropName}: ${PropType}
      }
      
      export const ${ComponentName} = ({
        ${PropName}
      }: ${ComponentName}Props) => {
        return (
          <div>
            {${PropName}}
          </div>
        )
      }

4. التوثيق​

قم بتضمين توثيق واضح في القواعد:

rules:
  - name: "خدمة API"
    description: |
      قالب لأصناف خدمة API.
      يتضمن عمليات CRUD القياسية ومعالجة الأخطاء.
    pattern: "src/services/**/*.ts"
    template: |
      /**
       * خدمة ${ServiceName}
       * تتعامل مع ${ServiceDescription}
       */
      export class ${ServiceName}Service {
        // التنفيذ
      }

5. معالجة الأخطاء​

قم بتضمين أنماط معالجة الأخطاء:

rules:
  - name: "معالجة أخطاء الخدمة"
    pattern: "src/services/**/*.ts"
    template: |
      try {
        // منطق الخدمة
      } catch (error) {
        if (error instanceof ApiError) {
          // معالجة أخطاء API
        } else {
          // معالجة الأخطاء الأخرى
        }
        throw error
      }

الأنماط المتقدمة​

1. القوالب الشرطية​

استخدم الشروط في القوالب:

rules:
  - name: "مكون مع خصائص"
    pattern: "src/components/**/*.tsx"
    template: |
      ${HasProps ? `
      interface ${ComponentName}Props {
        // الخصائص
      }
      ` : ''}
      
      export const ${ComponentName}${HasProps ? ': React.FC<${ComponentName}Props>' : ''} = () => {
        // التنفيذ
      }

2. الأنماط المشتركة​

حدد الأنماط القابلة لإعادة الاستخدام:

patterns:
  typescript-header: |
    /**
     * @file ${FileName}
     * @description ${FileDescription}
     * @created ${Date}
     */

rules:
  - name: "مكون"
    pattern: "src/components/**/*.tsx"
    template: |
      ${patterns.typescript-header}
      // تنفيذ المكون

نصائح التحسين​

  1. تنظيم الملفات

    • قم بتجميع الملفات ذات الصلة
    • استخدم هياكل دليل متسقة
    • اتبع اصطلاحات التسمية

  2. كفاءة القوالب

    • احتفظ بالقوالب مركزة ومحددة
    • تجنب الكود المكرر
    • استخدم الأنماط المشتركة للعناصر الشائعة

  3. اعتبارات الأداء

    • قم بتحديد تعقيد النمط
    • استخدم أنماط ملفات محددة
    • تجنب المطابقات الواسعة جداً

الأنماط الشائعة​

مكونات React​

rules:
  - name: "مكون React وظيفي"
    pattern: "src/components/**/*.tsx"
    template: |
      import React from 'react'
      import styles from './${ComponentName}.module.css'
      
      export interface ${ComponentName}Props {
        // الخصائص
      }

الخاتمة​

الاستخدام الفعال لـ .cursor/rules يمكن أن يحسن بشكل كبير جودة الكود وإنتاجية الفريق. باتباع أفضل الممارسات هذه، يمكن للفرق:

  • الحفاظ على كود متسق
  • زيادة سرعة التطوير
  • تحسين جودة الكود
  • تعزيز تعاون الفريق