سير العمل (Workflows)
يغطي هذا الدليل أنماط سير العمل الشائعة لـ OpenSpec ومتى يجب استخدام كل منها. للإعداد الأساسي، راجع Getting Started. وللاطلاع على مرجع الأوامر، راجع Commands.
الفلسفة: الإجراءات، لا المراحل (Actions, Not Phases)
تجبر سير العمل التقليدية المستخدم على المرور عبر مراحل: التخطيط، ثم التنفيذ، ثم الانتهاء. لكن العمل الحقيقي لا يمكن أن يتناسب بشكل مثالي في صناديق محددة.
يتبنى OPSX نهجًا مختلفًا:
text
Traditional (phase-locked):
PLANNING ────────► IMPLEMENTING ────────► DONE
│ │
│ "Can't go back" │
└────────────────────┘
OPSX (fluid actions):
proposal ──► specs ──► design ──► tasks ──► implementالمبادئ الأساسية:
- الإجراءات، لا المراحل - الأوامر هي أشياء يمكنك القيام بها، وليست مراحل عالقًا فيها.
- التبعيات هي ممكّنات (Enablers) - إنها تظهر ما هو ممكن، وليس ما هو مطلوب لاحقًا.
التخصيص: يتم تشغيل سير عمل OPSX بواسطة مخططات (schemas) تحدد تسلسل القطع الأثرية (artifact sequences). راجع Customization للحصول على تفاصيل حول إنشاء المخططات المخصصة.
نمطان
المسار السريع الافتراضي (core profile)
تستخدم التثبيتات الجديدة بشكل افتراضي ملف التعريف core، والذي يوفر ما يلي:
/opsx:explore/opsx:propose/opsx:apply/opsx:sync/opsx:archive
سير العمل النموذجي:
text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
(اختياري)ابدأ بالاستكشاف (العادة التي تستحق التكوين)
يعد /opsx:explore جزءًا من ملف التعريف الافتراضي، وليس إضافة متقدمة. إنها الخطوة التي يجب اتخاذها عندما تكون لديك مشكلة ولكن ليس لديك خطة بعد، وهو ما يحدث في معظم الأحيان بمساعدة مساعد الذكاء الاصطناعي.
text
أنت: /opsx:explore
الذكاء الاصطناعي: ماذا تود استكشافه؟
أنت: نتائج البحث لدينا تبدو قديمة. لست متأكدًا مما إذا كان السبب هو التخزين المؤقت (caching)، أو الفهرسة (indexing)، أو الاستعلام نفسه.
الذكاء الاصطناعي: دعني ألقي نظرة... [يقرأ خدمة البحث وطبقة التخزين المؤقت]
إنه الفهرس: فهو يعيد البناء ليلاً، لذا فإن التعديلات لا تظهر إلا في اليوم التالي. خياران: إعادة البناء عند الكتابة (الأبسط، وأكثر استهلاكًا للموارد) أو إلغاء صلاحية التخزين المؤقت قصير الأجل (أجزاء متحركة أكثر، واستنزاف أقل). نظرًا لأن حجم الكتابات لديك منخفض، فإن إعادة البناء عند الكتابة هو الحل الأنظف. هل تريد تحديد النطاق؟
أنت: نعم.
أنت: /opsx:propose rebuild-search-index-on-writeلا يُنشئ الاستكشاف أي مواد أو يكتب أي شيفرة برمجية. إنها محادثة مجانية وخالية من المخاطر تحول القلق الغامض إلى تغيير دقيق، بحيث يكون الاقتراح الذي يليه حادًا وواضحًا. هل تعرف بالفعل بالضبط ما تريده؟ تخطَّ هذه الخطوة وانتقل مباشرةً إلى /opsx:propose. الدليل الكامل: Explore First.
سير العمل الموسع/الكامل (اختيار مخصص)
إذا كنت ترغب في أوامر التكوين والبناء الصريحة (/opsx:new، /opsx:continue، إلخ)، فقم بتمكينها باستخدام:
bash
openspec config profile
openspec updateأنماط سير العمل (الوضع الموسع)
ميزة سريعة
عندما تعرف ما تريد بناءه وتحتاج فقط إلى التنفيذ:
text
/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archiveمثال على المحادثة:
text
أنت: /opsx:new add-logout-button
الذكاء الاصطناعي: تم إنشاء openspec/changes/add-logout-button/
جاهز لإنشاء: proposal
أنت: /opsx:ff
الذكاء الاصطناعي: جاري إنشاء جميع مواد التخطيط...
✓ proposal.md
✓ specs/
✓ design.md
✓ tasks.md
جاهز للتنفيذ!
أنت: /opsx:apply
الذكاء الاصطناعي: العمل على المهام...
✓ تمت إضافة زر تسجيل الخروج إلى الرأس (header)
✓ تم تنفيذ مسح بيانات الجلسة
✓ تمت إضافة مربع حوار التأكيد
جميع المهام مكتملة!
أنت: /opsx:archive
الذكاء الاصطناعي: ✓ دمج المواصفات
✓ أرشفة التغييرالأفضل لـ: الميزات الصغيرة والمتوسطة، وإصلاح الأخطاء، والتغييرات الواضحة والمباشرة.
استكشافي (Exploratory)
عندما تكون المتطلبات غير واضحة أو تحتاج إلى التحقيق أولاً:
text
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:applyمثال على المحادثة:
text
أنت: /opsx:explore
الذكاء الاصطناعي: ماذا تود استكشافه؟
أنت: أريد تحسين أداء تحميل الصفحة، لكني لست متأكدًا من أماكن الاختناقات.
الذكاء الاصطناعي: دعني المساعدة في التحقيق...
[يحلل أحجام الحزم (bundle sizes)، ويحدد الاستعلامات البطيئة، ويراجع أنماط عرض المكونات]
لقد وجدت ثلاثة اختناقات رئيسية:
1. صور كبيرة غير مُحسّنة
2. جلب البيانات المتزامن في ProductList
3. إعادة العرض من تغييرات السياق (context changes)
أي منها تود معالجته أولاً؟
أنت: دعنا نتناول مشكلة جلب البيانات.
أنت: /opsx:new optimize-product-list-fetching
الذكاء الاصطناعي: تم إنشاء التغيير. جاهز لإنشاء: proposal
أنت: /opsx:continue
الذكاء الاصطناعي: إنشاء الاقتراح بناءً على استكشافنا...
[يكتب الاقتراح متضمنًا رؤى التحقيق]
جاهز لإنشاء: specs, design
ماذا تود القيام به بعد ذلك؟
أنت: /opsx:continue
الذكاء الاصطناعي: إنشاء المواصفات...الأفضل لـ: تحسين الأداء، وتصحيح الأخطاء، والقرارات المعمارية، والمتطلبات غير الواضحة.
التغييرات المتوازية
اعمل على تغييرات متعددة في وقت واحد:
text
التغيير A: /opsx:new ──► /opsx:ff ──► /opsx:apply (قيد التنفيذ)
│
تبديل السياق (context switch)
│
التغيير B: /opsx:new ──► /opsx:ff ──────► /opsx:applyمثال على المحادثة:
text
أنت: أنا أعمل على add-dark-mode ولكنني انغمست في إصلاح خطأ (bug fix)
أنت: /opsx:new fix-login-redirect
الذكاء الاصطناعي: تم إنشاء openspec/changes/fix-login-redirect/
أنت: /opsx:ff
الذكاء الاصطناعي: ✓ تم إنشاء مواد التخطيط
أنت: /opsx:apply
الذكاء الاصطناعي: العمل على fix-login-redirect...
[يقوم بتنفيذ الإصلاح]
جميع المهام مكتملة!
أنت: /opsx:archive
الذكاء الاصطناعي: ✓ أرشفة fix-login-redirect
أنت: دعنا نعود إلى الوضع الداكن (dark mode)
أنت: /opsx:apply add-dark-mode
الذكاء الاصطناعي: استئناف add-dark-mode...
البدء من المهمة 2.3: تحديث الرأس (Header)...الأفضل لـ: مسارات العمل المتوازية، والتدخلات العاجلة، والتعاون الجماعي.
عندما يكون لديك تغييرات مكتملة متعددة، استخدم /opsx:bulk-archive:
text
أنت: /opsx:bulk-archive
الذكاء الاصطناعي: تم العثور على 3 تغييرات مكتملة:
- add-dark-mode (جميع المهام مكتملة)
- fix-login-redirect (جميع المهام مكتملة)
- update-footer (جميع المهام مكتملة)
التحقق من تعارضات المواصفات...
⚠ كل من add-dark-mode و update-footer يمسّان specs/ui/
فحص قاعدة الشيفرة لحل المشكلة...
كلا التغييرين قد تم تنفيذهما. سيتم تطبيقهما بترتيب زمني.
هل أؤرشف جميع التغييرات الثلاث؟
أنت: نعم
الذكاء الاصطناعي: ✓ أرشفة add-dark-mode
✓ أرشفة fix-login-redirect
✓ أرشفة update-footer
دمج المواصفات بالترتيب: add-dark-mode → update-footerيكتشف الأرشفة بالجملة متى تلمس تغييرات متعددة نفس المواصفات ويحل التعارضات عن طريق التحقق مما تم تنفيذه بالفعل.
إكمال التغيير
سير الإكمال الموصى به:
text
/opsx:apply ──► /opsx:verify ──► /opsx:archive
│ │
التحقق من التنفيذ يطلب المزامنة
التنفيذ إذا لزم الأمرالتحقق: افحص عملك
يقوم /opsx:verify بالتحقق من التنفيذ مقابل المواد الخاصة بك عبر ثلاثة أبعاد:
text
أنت: /opsx:verify
الذكاء الاصطناعي: التحقق من add-auth...
الاكتمال (COMPLETENESS)
✓ تم فحص جميع المهام الـ 12 في tasks.md
✓ تتطابق جميع المتطلبات الموجودة في المواصفات مع الشيفرة البرمجية
⚠ لم يتم اختبار سيناريو "انتهاء الجلسة بعد الخمول"
الصحة التقنية (CORRECTNESS)
✓ يتطابق التنفيذ مع قصد المواصفات
✓ تم التعامل مع حالات الحافة من السيناريوهات
✓ تتطابق حالات الخطأ مع تعريفات المواصفات
التناسق (COHERENCE)
✓ تعكس قرارات التصميم في هيكل الشيفرة
✓ الاتفاق على تسمية المكونات متسق مع design.md
⚠ يذكر التصميم "مدفوع بالأحداث" لكن التنفيذ يستخدم الاستقصاء (polling)
الملخص (SUMMARY)
─────────────────────────────
المشكلات الحرجة: 0
التحذيرات: 2
جاهز للأرشفة: نعم (مع التحذيرات)
التوصيات:
1. إضافة اختبار لسيناريو انتهاء الجلسة
2. النظر في إعادة الهيكلة لتكون مدفوعة بالأحداث كما هو مصمم، أو تحديث design.mdما الذي يتحقق منه التحقق:
| البُعد | ما الذي يتحقق منه |
|---|---|
| الاكتمال | جميع المهام مكتملة، وجميع المتطلبات مُنفذة، وتم تغطية السيناريوهات |
| الصحة التقنية | يتطابق التنفيذ مع قصد المواصفات، وتم التعامل مع حالات الحافة |
| التناسق | تعكس قرارات التصميم في الشيفرة، واتفاق المكونات متسق |
لن يمنع التحقق الأرشفة، ولكنه سيسلط الضوء على المشكلات التي قد ترغب في معالجتها أولاً.
أرشفة: إنهاء التغيير
يقوم /opsx:archive بإكمال التغيير ونقله إلى الأرشيف:
text
أنت: /opsx:archive
الذكاء الاصطناعي: أرشفة add-auth...
حالة المواد:
✓ موجود ملف proposal.md
✓ موجود مجلد specs/
✓ موجود ملف design.md
✓ موجود ملف tasks.md (12/12 مهمة مكتملة)
المواصفات المتغيرة: لم تتم مزامنتها بعد مع الرئيسي
→ هل تود المزامنة الآن؟
أنت: نعم
الذكاء الاصطناعي: ✓ تم مزامنة المواصفات إلى openspec/specs/auth/spec.md
✓ نقل الملف إلى openspec/changes/archive/2025-01-24-add-auth/
تمت أرشفة التغيير بنجاح.ستطلب الأرشفة إذا لم تكن المواصفات متزامنة. لن تمنعها المهام غير المكتملة، لكنها ستحذرك.
متى تستخدم ماذا
/opsx:ff مقابل /opsx:continue
| الحالة | الاستخدام |
|---|---|
| المتطلبات واضحة، وجاهز للتنفيذ | /opsx:ff |
| الاستكشاف، وترغب في مراجعة كل خطوة | /opsx:continue |
| الرغبة في التكرار على الاقتراح قبل المواصفات | /opsx:continue |
| ضغط الوقت، والحاجة إلى التحرك بسرعة | /opsx:ff |
| تغيير معقد، والرغبة في السيطرة | /opsx:continue |
القاعدة الأساسية: إذا كان بإمكانك وصف النطاق الكامل مقدمًا، فاستخدم /opsx:ff. وإذا كنت تكتشف الأمر أثناء العمل، فاستخدم /opsx:continue.
متى تقوم بالتحديث مقابل البدء من جديد
سؤال شائع: متى يكون تحديث تغيير موجود أمرًا، ومتى يجب أن تبدأ واحدًا جديدًا؟
قم بتحديث التغيير الموجود عندما:
- نفس القصد، وتنفيذ مُنقَّح
- ضاق النطاق (MVP أولاً، والبقية لاحقًا)
- تصحيحات مدفوعة بالتعلم (قاعدة الشيفرة ليست كما توقعت)
- تعديلات التصميم بناءً على اكتشافات التنفيذ
ابدأ تغييرًا جديدًا عندما:
- تغير القصد بشكل جوهري
- انفجر النطاق ليغطي عمل مختلف تمامًا
- يمكن وضع التغيير الأصلي كـ "مكتمل" بمفرده
- قد تسبب الرقع (patches) المزيد من الارتباك بدلاً من التوضيح
text
┌─────────────────────────────────────┐
│ هل هذا هو نفس العمل؟ │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
نفس القصد؟ >50% تداخل؟ يمكن أن يكون الأصلي
نفس المشكلة؟ نفس النطاق؟ "مكتمل" بدون هذه التغييرات؟
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
نعم لا نعم لا لا نعم
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
تحديث جديد تحديث جديد تحديث جديدمثال: "إضافة الوضع الداكن"
- "نحتاج أيضًا إلى دعم السمات المخصصة" ← تغيير جديد (انفجار النطاق)
- "اكتشاف تفضيلات النظام أصعب مما هو متوقع" ← تحديث (نفس القصد)
- "دعنا نشحن الزر أولاً، وإضافة التفضيلات لاحقًا" ← تحديث ثم أرشفة، ثم تغيير جديد
أفضل الممارسات
اجعل التغييرات مركزة
وحدة عمل منطقية واحدة لكل تغيير. إذا كنت تقوم بـ "إضافة الميزة X وإعادة هيكلة Y"، فكر في تغييرين منفصلين.
لماذا هذا مهم:
- أسهل للمراجعة والفهم
- سجل أرشيف أنظف
- يمكن شحنها بشكل مستقل
- تراجع أبسط إذا لزم الأمر
استخدم /opsx:explore للمتطلبات غير الواضحة
قبل الالتزام بأي تغيير، استكشف مجال المشكلة:
text
أنت: /opsx:explore
الذكاء الاصطناعي: ماذا تود استكشافه؟
أنت: كيف يجب أن نتعامل مع تحديد المعدل (rate limiting) لواجهة برمجة التطبيقات الخاصة بنا؟
الذكاء الاصطناعي: دعني أبحث في إعداداتك الحالية والخيارات المتاحة...
[يبحث في الشيفرة البرمجية، ويفكر في الأنماط]
أرى ثلاثة مقاربات يمكننا اتخاذها:
1. قائم على الوسيط (Middleware-based) (بسيط، لكل نقطة نهاية)
2. مدعوم بـ Redis (قابل للتوسع، حالة مشتركة)
3. دلو الرموز لكل مستخدم (منصف، معقد)
يشير مكدس العمل الحالي لديك إلى الخيار #1 أو #2. ما هو حجم عملك؟يُوضح الاستكشاف التفكير قبل أن تقوم بإنشاء المواد.
التحقق قبل الأرشفة
استخدم /opsx:verify للتحقق من تطابق التنفيذ مع المواد:
text
أنت: /opsx:verify
الذكاء الاصطناعي: التحقق من add-dark-mode...
✓ تم فحص جميع المهام في tasks.md
✓ تتطابق المتطلبات الموجودة في المواصفات مع الشيفرة البرمجية
✓ تعكس قرارات التصميم في التنفيذ
جاهز للأرشفة!يكشف عدم التطابق قبل إغلاق التغيير.
سمِّ التغييرات بوضوح
الأسماء الجيدة تجعل openspec list مفيدًا:
text
جيد: تجنب:
add-dark-mode feature-1
fix-login-redirect update
optimize-product-query changes
implement-2fa wipمرجع سريع للأوامر
للحصول على تفاصيل وخيارات الأوامر الكاملة، راجع الأوامر.
| الأمر | الغرض | متى يُستخدم |
|---|---|---|
/opsx:propose | إنشاء تغيير ومخرجات تخطيطية | المسار الافتراضي السريع (core profile) |
/opsx:explore | التفكير في الأفكار مع الذكاء الاصطناعي | ابدأ هنا عندما تكون غير متأكد: متطلبات غير واضحة، أو تحقيق، أو مقارنة الخيارات |
/opsx:new | بدء هيكل تغيير | الوضع الموسع، والتحكم الصريح في المخرجات |
/opsx:continue | إنشاء المخرج التالي | الوضع الموسع، وإنشاء المخرجات خطوة بخطوة |
/opsx:ff | إنشاء جميع مخرجات التخطيط | الوضع الموسع، ونطاق واضح |
/opsx:apply | تنفيذ المهام | جاهز لكتابة الكود |
/opsx:verify | التحقق من التنفيذ | الوضع الموسع، قبل الأرشفة |
/opsx:sync | دمج مواصفات التغيير (delta specs) | الوضع الموسع، اختياري |
/opsx:archive | إكمال التغيير | بعد الانتهاء من جميع الأعمال |
/opsx:bulk-archive | أرشفة تغييرات متعددة | الوضع الموسع، العمل المتوازي |