Spec Workflow MCP

# دليل المستخدم دليل شامل لاستخدام Spec Workflow MCP للتطوير البرمجي بمساعدة الذكاء الاصطناعي. ## البدء ### ما هو Spec Workflow MCP؟ Spec Workflow MCP هو خادم Model Context Protocol يوفر أدوات تطوير منظمة قائمة على المواصفات للمساعدين الذكيين. يساعدك على: - إنشاء مواصفات مفصلة قبل البرمجة - تتبع تقدم التنفيذ - إدارة الموافقات والمراجعات - الحفاظ على توثيق المشروع ### سير العمل الأساسي 1. **إنشاء مواصفة** - حدد ما تريد بناءه 2. **المراجعة والموافقة** - تأكد من أن المواصفات تلبي المتطلبات 3. **تنفيذ المهام** - نفذ خطة التنفيذ 4. **تتبع التقدم** - راقب حالة الإنجاز ## إنشاء المواصفات ### إنشاء مواصفة بسيطة اطلب من مساعد الذكاء الاصطناعي إنشاء مواصفة: ``` "أنشئ مواصفة لمصادقة المستخدم" ``` سيقوم الذكاء الاصطناعي تلقائيًا بـ: 1. إنشاء مستند المتطلبات 2. تصميم النهج التقني 3. تقسيم التنفيذ إلى مهام ### إنشاء مواصفة مفصلة قدم المزيد من السياق للحصول على مواصفات أفضل: ``` "أنشئ مواصفة تسمى payment-gateway مع الميزات التالية: - معالجة بطاقات الائتمان - تكامل PayPal - إدارة الاشتراكات - معالجة webhook لأحداث الدفع" ``` ### من المستندات الموجودة استخدم مستندات PRD أو التصميم الموجودة لديك: ``` "ابنِ مواصفة من @product-requirements.md" ``` ## إدارة المواصفات ### سرد جميع المواصفات ``` "اعرض جميع مواصفاتي" ``` يُرجع: - أسماء المواصفات - الحالة الحالية - نسبة التقدم - حالات المستندات ### التحقق من حالة المواصفة ``` "أرني حالة مواصفة user-auth" ``` يوفر: - حالة موافقة المتطلبات - حالة موافقة التصميم - تقدم إنجاز المهام - تفصيل مفصل للمهام ### عرض مستندات المواصفة استخدم لوحة التحكم أو إضافة VSCode لـ: - قراءة مستندات المتطلبات - مراجعة مستندات التصميم - تصفح قوائم المهام - تتبع تقدم التنفيذ ## العمل مع المهام ### هيكل المهام المهام منظمة بشكل هرمي: - **1.0** - أقسام رئيسية - **1.1** - مهام فرعية - **1.2** - مهام فرعية - **1.2.1** - خطوات مفصلة ### تنفيذ المهام #### الطريقة 1: التنفيذ المباشر ``` "نفذ المهمة 1.2 من مواصفة user-auth" ``` #### الطريقة 2: النسخ من لوحة التحكم 1. افتح لوحة التحكم 2. انتقل إلى مواصفتك 3. انقر على علامة تبويب "المهام" 4. انقر على زر "نسخ الأمر" بجوار أي مهمة 5. الصق في محادثة الذكاء الاصطناعي #### الطريقة 3: التنفيذ المجمع ``` "نفذ جميع مهام إعداد قاعدة البيانات من مواصفة user-auth" ``` ### حالة المهمة المهام لها ثلاث حالات: - ⏳ **معلقة** - لم تبدأ - 🔄 **قيد التقدم** - يتم العمل عليها حاليًا - ✅ **مكتملة** - منتهية ## سير عمل الموافقة ### طلب الموافقة عندما تكون المستندات جاهزة للمراجعة: 1. يطلب الذكاء الاصطناعي الموافقة تلقائيًا 2. تُظهر لوحة التحكم إشعارًا 3. راجع المستند 4. قدم ملاحظات أو وافق ### إجراءات الموافقة - **الموافقة** - قبول المستند كما هو - **طلب التغييرات** - تقديم ملاحظات للمراجعة - **الرفض** - البدء من جديد بمتطلبات جديدة ### عملية المراجعة 1. قدم ملاحظات محددة 2. يراجع الذكاء الاصطناعي المستند 3. راجع الإصدار المحدث 4. وافق أو اطلب مزيدًا من التغييرات ## سير عمل الأخطاء ### الإبلاغ عن الأخطاء ``` "أنشئ تقرير خطأ لفشل تسجيل الدخول عند استخدام SSO" ``` ينشئ: - وصف الخطأ - خطوات إعادة الإنتاج - السلوك المتوقع مقابل الفعلي - الأولوية والخطورة ### حل الأخطاء ``` "أنشئ إصلاحًا للخطأ #123 في مواصفة user-auth" ``` يُنتج: - تحليل السبب الجذري - خطة تنفيذ الإصلاح - متطلبات الاختبار - خطوات النشر ## نظام القوالب ### استخدام القوالب يتضمن Spec Workflow قوالب لـ: - مستندات المتطلبات - مستندات التصميم - قوائم المهام - تقارير الأخطاء - مستندات التوجيه ### القوالب المخصصة أنشئ قوالبك الخاصة في `.spec-workflow/templates/`: ```markdown # قالب ميزة مخصص ## نظرة عامة [وصف الميزة] ## قصص المستخدم [قصص المستخدم] ## المتطلبات التقنية [التفاصيل التقنية] ``` ## الميزات المتقدمة ### مستندات التوجيه أنشئ إرشادات المشروع عالية المستوى: ``` "أنشئ مستندات توجيه لمشروع التجارة الإلكترونية الخاص بي" ``` ينتج: - **توجيه المنتج** - الرؤية والأهداف - **التوجيه التقني** - قرارات الهندسة المعمارية - **توجيه الهيكل** - تنظيم المشروع ### نظام الأرشفة إدارة المواصفات المكتملة: - نقل المواصفات المنتهية إلى الأرشيف - الحفاظ على نظافة مساحة العمل النشطة - الوصول إلى المواصفات المؤرشفة في أي وقت - استعادة المواصفات عند الحاجة ### دعم متعدد اللغات تغيير لغة الواجهة: 1. **لوحة التحكم**: الإعدادات → اللغة 2. **إضافة VSCode**: إعدادات الإضافة → اللغة 3. **ملف التكوين**: `lang = "ja"` (أو رمز لغة آخر) ## أفضل الممارسات ### 1. ابدأ بمستندات التوجيه قبل إنشاء المواصفات: ``` "أنشئ مستندات توجيه لتوجيه المشروع" ``` ### 2. كن محددًا في المتطلبات جيد: ``` "أنشئ مواصفة لمصادقة المستخدم مع: - تسجيل دخول البريد الإلكتروني/كلمة المرور - OAuth2 (Google، GitHub) - دعم 2FA - تدفق إعادة تعيين كلمة المرور" ``` غير مثالي: ``` "أنشئ مواصفة تسجيل دخول" ``` ### 3. المراجعة قبل التنفيذ راجع ووافق دائمًا على: 1. مستند المتطلبات 2. مستند التصميم 3. تفصيل المهام ### 4. التنفيذ التدريجي - أكمل المهام بالترتيب - اختبر بعد كل قسم رئيسي - حدّث حالة المهمة بانتظام ### 5. استخدم لوحة التحكم توفر لوحة التحكم: - تتبع تقدم مرئي - تنقل سهل في المستندات - إجراءات موافقة سريعة - تحديثات فورية ## سير العمل الشائع ### تطوير الميزات 1. إنشاء مواصفة: `"أنشئ مواصفة لميزة shopping-cart"` 2. مراجعة المتطلبات في لوحة التحكم 3. الموافقة أو طلب التغييرات 4. مراجعة مستند التصميم 5. الموافقة على التصميم 6. تنفيذ المهام بالتسلسل 7. تتبع التقدم في لوحة التحكم ### إصلاح الأخطاء 1. الإبلاغ عن الخطأ: `"أنشئ تقرير خطأ لخطأ الدفع"` 2. التحليل: `"حلل السبب الجذري للخطأ #45"` 3. خطة الإصلاح: `"أنشئ خطة إصلاح للخطأ #45"` 4. التنفيذ: `"نفذ الإصلاح"` 5. التحقق: `"أنشئ خطة اختبار لإصلاح الخطأ #45"` ### إعادة الهيكلة 1. إنشاء مواصفة: `"أنشئ مواصفة لتحسين قاعدة البيانات"` 2. توثيق الحالة الحالية 3. تصميم التحسينات 4. خطة خطوات الترحيل 5. التنفيذ التدريجي 6. التحقق من كل خطوة ## نصائح وحيل ### إدارة المهام الفعالة - استخدم تجميع المهام للعناصر ذات الصلة - انسخ الأوامر من لوحة التحكم للدقة - ضع علامة على المهام كمكتملة فور الانتهاء ### إدارة المستندات - حافظ على المتطلبات موجزة ولكن كاملة - قم بتضمين معايير القبول - أضف القيود التقنية في التصميم - أشر إلى المستندات الخارجية عند الحاجة ### التعاون - استخدم تعليقات الموافقة للملاحظات - شارك رابط لوحة التحكم مع الفريق - صدّر المستندات للمراجعة الخارجية - تتبع التغييرات من خلال سجل المراجعة ## التكامل مع المساعدين الذكيين ### الوعي بالسياق يقوم مساعد الذكاء الاصطناعي تلقائيًا بـ: - معرفة هيكل مشروعك - فهم علاقات المواصفات - تتبع تقدم التنفيذ - الحفاظ على الاتساق ### أوامر اللغة الطبيعية تحدث بشكل طبيعي: - "ما المواصفات التي لدي؟" - "أرني ما تبقى للقيام به" - "ابدأ العمل على المهمة التالية" - "حدّث التصميم لأداء أفضل" ### سير العمل المستمر يحافظ الذكاء الاصطناعي على السياق بين الجلسات: - استئناف من حيث توقفت - الإشارة إلى القرارات السابقة - البناء على العمل الموجود - الحفاظ على تماسك المشروع ## التوثيق ذو الصلة - [عملية سير العمل](WORKFLOW.md) - دليل سير العمل المفصل - [دليل الأوامر](PROMPTING-GUIDE.md) - أمثلة الأوامر - [دليل الواجهات](INTERFACES.md) - تفاصيل لوحة التحكم والإضافة - [مرجع الأدوات](TOOLS-REFERENCE.md) - توثيق الأدوات الكامل