Spec Workflow MCP

# دليل عملية سير العمل يشرح هذا الدليل عملية سير العمل الكاملة للتطوير القائم على المواصفات وأفضل الممارسات لاستخدام Spec Workflow MCP. ## نظرة عامة يتبع سير العمل القائم على المواصفات نهجًا منظمًا: ``` التوجيه → المواصفات → التنفيذ → التحقق ``` كل مرحلة تبني على السابقة، مما يضمن تطويرًا منهجيًا وموثقًا جيدًا. ## المرحلة 1: إعداد المشروع بمستندات التوجيه ### لماذا مستندات التوجيه؟ توفر مستندات التوجيه إرشادات عالية المستوى تحافظ على توافق واتساق مشروعك. تعمل كنجم الشمال لجميع قرارات التطوير. ### إنشاء مستندات التوجيه ``` "أنشئ مستندات توجيه لمشروعي" ``` هذا ينتج ثلاثة مستندات رئيسية: #### 1. توجيه المنتج (`steering/product.md`) - رؤية ومهمة المنتج - المستخدمون المستهدفون والشخصيات - الميزات الأساسية والأولويات - مقاييس النجاح ومؤشرات الأداء الرئيسية - الأهداف غير المطلوبة والقيود #### 2. التوجيه التقني (`steering/tech.md`) - قرارات الهندسة المعمارية - اختيارات مجموعة التقنيات - متطلبات الأداء - اعتبارات الأمان - نهج قابلية التوسع #### 3. توجيه الهيكل (`steering/structure.md`) - تنظيم المشروع - اصطلاحات الملفات والمجلدات - معايير التسمية - حدود الوحدات - هيكل التوثيق ### أفضل الممارسات للتوجيه 1. **أنشئ مبكرًا** - أعد التوجيه قبل أي مواصفات 2. **حافظ على التحديث** - راجع مع تطور المشروع 3. **ارجع كثيرًا** - استخدم لاتخاذ القرارات 4. **شارك على نطاق واسع** - تأكد من توافق الفريق ## المرحلة 2: إنشاء المواصفات ### نظام المستندات الثلاثة تتكون كل مواصفة من ثلاثة مستندات متسلسلة: ``` المتطلبات → التصميم → المهام ``` ### مستند المتطلبات **الغرض**: تحديد ما يجب بناؤه **المحتويات**: - نظرة عامة على الميزة - قصص المستخدم - المتطلبات الوظيفية - المتطلبات غير الوظيفية - معايير القبول - القيود والافتراضات **مثال على الإنشاء**: ``` "أنشئ متطلبات لنظام إشعارات المستخدم يدعم: - إشعارات البريد الإلكتروني - الإشعارات داخل التطبيق - الإشعارات الفورية - تفضيلات المستخدم - سجل الإشعارات" ``` ### مستند التصميم **الغرض**: تحديد كيفية البناء **المحتويات**: - الهندسة المعمارية التقنية - تصميم المكونات - نماذج البيانات - مواصفات API - نقاط التكامل - نهج التنفيذ **التوليد التلقائي**: يُنشأ بعد الموافقة على المتطلبات ### مستند المهام **الغرض**: تحديد الخطوات لبنائه **المحتويات**: - تفصيل هرمي للمهام - التبعيات - تقديرات الجهد - ترتيب التنفيذ - متطلبات الاختبار **مثال على الهيكل**: ``` 1.0 إعداد قاعدة البيانات 1.1 إنشاء جداول الإشعارات 1.2 إعداد الفهارس 1.3 إنشاء سكريبتات الترحيل 2.0 تنفيذ الخلفية 2.1 إنشاء خدمة الإشعارات 2.1.1 معالج البريد الإلكتروني 2.1.2 معالج الإشعارات الفورية 2.2 إنشاء نقاط نهاية API 2.3 إضافة المصادقة 3.0 تنفيذ الواجهة الأمامية 3.1 إنشاء مكونات الإشعارات 3.2 التكامل مع API 3.3 إضافة واجهة التفضيلات ``` ## المرحلة 3: المراجعة والموافقة ### سير عمل الموافقة 1. **إنشاء المستند** - ينتج الذكاء الاصطناعي المستند 2. **طلب المراجعة** - يُطلب الموافقة تلقائيًا 3. **مراجعة المستخدم** - مراجعة في لوحة التحكم/الإضافة 4. **القرار** - الموافقة أو طلب التغييرات أو الرفض 5. **المراجعة** (إذا لزم الأمر) - يحدث الذكاء الاصطناعي بناءً على الملاحظات 6. **الموافقة النهائية** - المستند مقفل للتنفيذ ### اتخاذ قرارات الموافقة #### متى توافق - المتطلبات كاملة وواضحة - التصميم يحل المشكلة المذكورة - المهام منطقية وشاملة - لا توجد مخاوف أو فجوات كبيرة #### متى تطلب التغييرات - تفاصيل مهمة مفقودة - مواصفات غير واضحة - نهج أفضل متاح - يحتاج التوافق مع المعايير #### متى ترفض - سوء فهم أساسي - نهج خاطئ تمامًا - يتطلب إعادة تفكير كاملة ### تقديم ملاحظات فعالة ملاحظات جيدة: ``` "يجب أن يستخدم تدفق المصادقة رموز JWT بدلاً من الجلسات. أضف تحديد المعدل إلى نقاط نهاية API. قم بتضمين معالجة الأخطاء لفشل الشبكة." ``` ملاحظات سيئة: ``` "هذا لا يبدو صحيحًا. أصلحه." ``` ## المرحلة 4: التنفيذ ### استراتيجية تنفيذ المهام #### التنفيذ المتسلسل الأفضل للمهام التابعة: ``` "نفذ المهمة 1.1 من مواصفة user-auth" "الآن نفذ المهمة 1.2" "تابع مع المهمة 1.3" ``` #### التنفيذ المتوازي للمهام المستقلة: ``` "نفذ جميع مهام واجهة المستخدم من مواصفة لوحة التحكم بينما أعمل على الخلفية" ``` #### التنفيذ القائم على الأقسام للتجميعات المنطقية: ``` "نفذ جميع مهام قاعدة البيانات من مواصفة الدفع" ``` ### تتبع التقدم راقب التنفيذ من خلال: - عرض مهام لوحة التحكم - أشرطة التقدم - مؤشرات الحالة - نسب الإنجاز ### معالجة العوائق عند مواجهة عائق: 1. وثّق العائق 2. أنشئ مهمة فرعية للحل 3. انتقل إلى المهام المتوازية إن أمكن 4. حدّث حالة المهمة إلى "محظور" ## المرحلة 5: التحقق ### استراتيجية الاختبار بعد التنفيذ: 1. **اختبار الوحدة** ``` "أنشئ اختبارات وحدة لخدمة الإشعارات" ``` 2. **اختبار التكامل** ``` "أنشئ اختبارات تكامل لنقاط نهاية API" ``` 3. **اختبار من البداية إلى النهاية** ``` "أنشئ اختبارات E2E لتدفق الإشعارات الكامل" ``` ### تحديثات التوثيق حافظ على التوثيق محدثًا: ``` "حدّث توثيق API للنقاط النهائية الجديدة" "أضف أمثلة استخدام إلى README" ``` ## هيكل الملفات والتنظيم ### هيكل المشروع القياسي ``` your-project/ ├── .spec-workflow/ │ ├── steering/ │ │ ├── product.md │ │ ├── tech.md │ │ └── structure.md │ ├── specs/ │ │ ├── user-auth/ │ │ │ ├── requirements.md │ │ │ ├── design.md │ │ │ └── tasks.md │ │ └── payment-gateway/ │ │ ├── requirements.md │ │ ├── design.md │ │ └── tasks.md │ └── approval/ │ └── [ملفات تتبع الموافقة] ├── src/ │ └── [تنفيذك] └── tests/ └── [اختباراتك] ``` ### اصطلاحات التسمية **أسماء المواصفات**: - استخدم kebab-case: `user-authentication` - كن وصفيًا: `payment-processing` وليس `payments` - تجنب الإصدارات: `user-profile` وليس `user-profile-v2` **أسماء المستندات**: - دائمًا: `requirements.md`، `design.md`، `tasks.md` - متسق عبر جميع المواصفات ## سير العمل المتقدم ### تكرارات الميزات للميزات المتطورة: 1. أنشئ مواصفة أولية 2. نفذ MVP 3. أنشئ مواصفة تحسين 4. أشر إلى المواصفة الأصلية 5. ابنِ على العمل الموجود مثال: ``` "أنشئ مواصفة تحسين لـ user-auth تضيف: - تسجيل دخول اجتماعي (Google، Facebook) - مصادقة بيومترية - تحسينات إدارة الجلسة" ``` ### سير عمل إعادة الهيكلة 1. **وثّق الحالة الحالية** ``` "أنشئ مواصفة توثق نظام المصادقة الحالي" ``` 2. **صمم التحسينات** ``` "صمم إعادة هيكلة لتحسين أداء المصادقة" ``` 3. **خطط للترحيل** ``` "أنشئ مهام ترحيل لإعادة الهيكلة" ``` 4. **نفذ تدريجيًا** ``` "نفذ مهام إعادة الهيكلة مع التوافق العكسي" ``` ### سير عمل حل الأخطاء 1. **تقرير الخطأ** ``` "أنشئ تقرير خطأ لمشكلة مهلة تسجيل الدخول" ``` 2. **التحقيق** ``` "تحقق في السبب الجذري للخطأ #45" ``` 3. **تصميم الحل** ``` "صمم إصلاحًا لمشكلة المهلة" ``` 4. **التنفيذ** ``` "نفذ إصلاح الخطأ" ``` 5. **التحقق** ``` "أنشئ اختبارات انحدار للخطأ #45" ``` ## أفضل الممارسات ### 1. حافظ على دقة المواصفة **جيد**: مواصفة واحدة لكل ميزة - `user-authentication` - `payment-processing` - `notification-system` **سيء**: مواصفات واسعة جدًا - `backend-system` - `all-features` ### 2. إنشاء مستندات متسلسل اتبع الترتيب دائمًا: 1. المتطلبات (ماذا) 2. التصميم (كيف) 3. المهام (الخطوات) لا تتخطى أبدًا. ### 3. موافقة كاملة قبل التنفيذ - ✅ وافق على المتطلبات → أنشئ التصميم - ✅ وافق على التصميم → أنشئ المهام - ✅ راجع المهام → ابدأ التنفيذ - ❌ تخطي الموافقة → مشاكل التنفيذ ### 4. حافظ على تحديث المواصفات عندما تتغير المتطلبات: ``` "حدّث متطلبات user-auth لتضمين دعم SSO" ``` ### 5. استخدم مصطلحات متسقة حافظ على الاتساق عبر: - أسماء المواصفات - أسماء المكونات - مصطلحات API - تسمية قاعدة البيانات ### 6. أرشف المواصفات المكتملة حافظ على نظافة مساحة العمل: ``` "أرشف مواصفة user-auth المكتملة" ``` ## الأنماط الشائعة ### من MVP إلى ميزة كاملة 1. ابدأ بمواصفة MVP 2. نفذ الوظائف الأساسية 3. أنشئ مواصفات تحسين 4. ابنِ تدريجيًا 5. حافظ على التوافق العكسي ### تطوير الخدمات الصغيرة 1. أنشئ مستند توجيه الخدمة 2. حدد حدود الخدمة 3. أنشئ مواصفة لكل خدمة 4. حدد نقاط التكامل 5. نفذ الخدمات بشكل مستقل ### التطوير القائم على API أولاً 1. أنشئ مواصفة API أولاً 2. صمم العقود 3. أنشئ التوثيق 4. نفذ النقاط النهائية 5. أنشئ SDKs للعميل ## استكشاف مشكلات سير العمل وإصلاحها ### المواصفات تصبح كبيرة جدًا **الحل**: قسّم إلى مواصفات أصغر ``` "قسم مواصفة التجارة الإلكترونية إلى: - product-catalog - shopping-cart - checkout-process - order-management" ``` ### متطلبات غير واضحة **الحل**: اطلب التوضيح ``` "المتطلبات تحتاج مزيدًا من التفاصيل حول: - أدوار المستخدم والأذونات - سيناريوهات معالجة الأخطاء - متطلبات الأداء" ``` ### التصميم لا يتطابق مع المتطلبات **الحل**: اطلب المراجعة ``` "التصميم لا يعالج متطلبات تعدد المستأجرين. يرجى المراجعة لتضمين عزل المستأجر." ``` ## التكامل مع عملية التطوير ### سير عمل Git 1. أنشئ فرع ميزة لكل مواصفة 2. أرسل بعد إكمال كل مهمة 3. أشر إلى المواصفة في رسائل الالتزام 4. PR عند اكتمال المواصفة ### تكامل CI/CD - قم بتشغيل الاختبارات للمهام المكتملة - تحقق من صحة المتطلبات - انشر الميزات المكتملة - راقب مقابل مقاييس النجاح ### التعاون الجماعي - شارك رابط لوحة التحكم - عيّن المواصفات لأعضاء الفريق - راجع مواصفات بعضكم البعض - نسّق من خلال الموافقات ## التوثيق ذو الصلة - [دليل المستخدم](USER-GUIDE.md) - تعليمات الاستخدام العامة - [دليل الأوامر](PROMPTING-GUIDE.md) - أمثلة الأوامر والأنماط - [مرجع الأدوات](TOOLS-REFERENCE.md) - توثيق الأدوات الكامل - [دليل الواجهات](INTERFACES.md) - تفاصيل لوحة التحكم والإضافة