OpenSpec

سير العمل ​

تغطي هذه الدليل أنماط سير العمل الشائعة في OpenSpec ومتى تستخدم كل نمط. للإعداد الأساسي، انظر البدء السريع. لمرجع الأوامر، انظر الأوامر.

الفلسفة: إجراءات وليس مراحل ​

تفرض سير العمل التقليدية عليك المرور عبر مراحل محددة: التخطيط، ثم التنفيذ، ثم الانتهاء. لكن العمل الحقيقي لا يناسب الصناديق بشكل دقيق.

يتبع OPSX نهجاً مختلفاً:

text
التقليدي (مقيد بالمراحل):

  PLANNING ────────► IMPLEMENTING ────────► DONE
      │                    │
      │   "لا يمكن الرجوع"  │
      └────────────────────┘

OPSX (إجراءات مرنة):

  proposal ──► specs ──► design ──► tasks ──► implement

المبادئ الأساسية:

  • إجراءات، وليس مراحل - الأوامر هي أشياء يمكنك القيام بها، وليست مراحل تكون عالقاً فيها
  • التبعيات هي مُمكّنات - تُظهر ما هو ممكن، وليس ما يجب فعله تالياً كشرط إلزامي

التخصيص: سير عمل OPSX مدفوع بالمخططات التي تحدد تسلسل العناصر. انظر التخصيص لمزيد من التفاصيل حول إنشاء مخططات مخصصة.

نظرة عامة على سير العمل ​

يبقى سير العمل الافتراضي سلسًا: الاستكشاف والتحقق اختياريان، ويمكنك تحديث وثائق التخطيط في أي وقت يكشف التنفيذ عن معلومات جديدة.

mermaid
flowchart TD
    Idea["فكرة أو مشكلة"] --> Explore["/opsx:explore<br/>(اختياري)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"هل وثائق التخطيط<br/>جاهزة؟"}
    Review -->|"تحسين"| Update["/opsx:update"]
    Update --> Review
    Review -->|"تنفيذ"| Apply["/opsx:apply"]
    Apply -->|"تغير الخطة"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(اختياري، اختيار مخصص)"]
    Apply --> Sync["/opsx:sync<br/>(اختياري قبل الأرشفة)"]
    Verify --> Verified{"جاهز للأرشفة؟"}
    Verified -->|"إصلاح التنفيذ"| Apply
    Verified -->|"مراجعة الخطة"| Update
    Verified -->|"جاهز"| Sync
    Verified -->|"جاهز"| Archive
    Sync --> Archive

يقود المساعد الذكي (AI) سير العمل، بينما يوفر واجهة سطر الأوامر (CLI) هيكلاً حاسماً، وحالة النظام، وتعليمات حول الوثائق:

mermaid
sequenceDiagram
    actor Human
    participant Assistant as مساعد ذكي (AI)
    participant CLI as واجهة سطر الأوامر OpenSpec
    participant Files as ملفات التخطيط والتنفيذ

    Human->>Assistant: /opsx:propose "change"
    Assistant->>CLI: openspec new change
    CLI->>Files: إنشاء هيكل بيانات التغيير
    Assistant->>CLI: طلب الحالة وتعليمات الوثائق
    CLI-->>Assistant: ترتيب البناء، المسارات، والقوالب
    Assistant->>Files: كتابة وثائق التخطيط حسب المخطط
    Assistant-->>Human: عرض الوثائق للمراجعة

    Human->>Assistant: /opsx:apply
    Assistant->>CLI: طلب تعليمات التطبيق
    CLI-->>Assistant: ملفات السياق وحالة المهام
    Assistant->>Files: تنفيذ المهام وتحديث مربعات الاختيار
    Assistant-->>Human: الإبلاغ عن حالة التنفيذ

    Human->>Assistant: /opsx:archive
    Assistant->>CLI: طلب مدخلات الأرشفة وحالة الوثائق
    CLI-->>Assistant: مسارات التخطيط واكتمال الوثائق
    Assistant->>Files: قراءة حالة المهام ومقارنة مواصفات الفروقات
    opt وجود مواصفات فروقات
        Assistant-->>Human: عرض المزامنة قبل الأرشفة
        alt تم قبول المزامنة
            Human->>Assistant: تأكيد المزامنة
            Assistant->>Files: دمج مواصفات الفروقات في المواصفات الرئيسية
        else تم تخطي المزامنة
            Human->>Assistant: أرشفة دون مزامنة
        end
    end
    Assistant->>Files: نقل التغيير إلى الأرشيف
    Assistant-->>Human: الإبلاغ عن موقع الأرشفة ونتيجة المزامنة

    Note over Human,CLI: بديل CLI: الأمر `openspec archive change-name --yes` يتخطى طلبات التأكيد. يقوم بالتحقق أولاً، ثم يطبق أي مواصفات فروقات ويقوم بالأرشفة

وضعان للعمل ​

المسار السريع الافتراضي (ملف core) ​

الإصدارات الجديدة تكون افتراضياً على ملف core، الذي يوفر:

  • /opsx:explore
  • /opsx:propose
  • /opsx:apply
  • /opsx:update
  • /opsx:sync
  • /opsx:archive

التدفق النموذجي:

text
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
  (اختياري)

ابدأ بالاستكشاف (عادة تستحق التشكيل) ​

يُعد /opsx:explore جزءاً من الملف الافتراضي، وليس إضافة متقدمة. إنه الخطوة التي يجب اتخاذها كلما كانت لديك مشكلة ولكن ليس لديك خطة بعد، وهو ما يحدث في معظم الأوقات مع مساعد ذكي.

text
أنت: /opsx:explore

المساعد: ماذا تريد استكشافه؟

أنت: نتائج البحث لدينا تبدو قديمة. لست متأكداً إذا كان السبب في التخزين المؤقت،
     أو الفهرسة، أو الاستعلام نفسه.

المساعد: دعني ألقي نظرة... [يقرأ خدمة البحث وطبقة التخزين المؤقت]
     المشكلة في الفهرس: يتم إعادة بنائه ليلاً فقط، لذا التعديلات لا تظهر
     حتى اليوم التالي. خياران: إعادة البناء عند الكتابة (بسيط، حمل أكبر)
     أو إلغاء صلاحية التخزين المؤقت لفترة قصيرة (أجزاء متحركة أكثر، حمل أقل).
     نظراً لأن حجم كتابتك منخفض، فإن إعادة البناء عند الكتابة هو الحل الأنظف.
     هل تريد تحديد النطاق؟

أنت: نعم.

أنت: /opsx:propose rebuild-search-index-on-write

لا ينشئ الاستكشاف أي وثائق ولا يكتب أي كود. إنه حوار مجاني بدون مخاطر يحول القلق الغامض إلى تغيير دقيق، بحيث يكون الاقتراح اللاحق حاداً ودقيقاً. تعرف بالفعل بالضبط ما تريده؟ تخطاه وانتقل مباشرة إلى /opsx:propose. الدليل الكامل: استكشف أولاً.

سير العمل الموسع/الكامل (اختيار مخصص) ​

إذا كنت تريد أوامر إنشاء الهيكل والبناء الصريحة (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard)، فعّلها باستخدام:

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

المساعد: جاري العمل على المهام...
         ✓ تمت إضافة زر تسجيل الخروج إلى الرأس
         ✓ تم تنفيذ مسح الجلسة
         ✓ تمت إضافة مربع حوار التأكيد
         اكتملت جميع المهام!

أنت: /opsx:archive

المساعد: ✓ تم دمج المواصفات
         ✓ تم أرشفة التغيير

الأفضل لـ: الميزات الصغيرة والمتوسطة، إصلاح الأخطاء، التغييرات البسيطة.

استكشافي ​

عندما تكون المتطلبات غير واضحة أو تحتاج للتحقيق أولاً:

text
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

مثال على المحادثة:

text
أنت: /opsx:explore

المساعد: ماذا تريد استكشافه؟

أنت: أريد تحسين أداء تحميل الصفحة لكنني لست متأكداً
     أين الاختناقات.

المساعد: دعني أساعد في التحقيق...
         [يحلل أحجام الحزم، يحدد الاستعلامات البطيئة، يراجع
         أنماط عرض المكونات]

         وجدت ثلاثة اختناقات رئيسية:
         1. صور كبيرة غير محسنة
         2. جلب البيانات التزامني في ProductList
         3. إعادة العرض بسبب تغييرات السياق

         أي منها تريد معالجته أولاً؟

أنت: لنعالج مشكلة جلب البيانات.

أنت: /opsx:new optimize-product-list-fetching

المساعد: تم إنشاء التغيير. جاهز لإنشاء: proposal

أنت: /opsx:continue

المساعد: جاري إنشاء اقتراح بناءً على استكشافنا...
         [يكتب اقتراحاً يدمج رؤى التحقيق]

         جاهز لإنشاء: specs, design
         ماذا تريد التالي؟

أنت: /opsx:continue

المساعد: جاري إنشاء المواصفات...

الأفضل لـ: تحسين الأداء، تصحيح الأخطاء، القرارات المعمارية، المتطلبات غير الواضحة.

تغييرات متوازية ​

العمل على عدة تغييرات في وقت واحد:

text
التغيير A: /opsx:new ──► /opsx:ff ──► /opsx:apply (قيد التقدم)
                                         │
                                    تبديل السياق
                                         │
التغيير B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

مثال على المحادثة:

text
أنت: أعمل على add-dark-mode لكنني انقطعت لإصلاح خطأ

أنت: /opsx:new fix-login-redirect

المساعد: تم إنشاء openspec/changes/fix-login-redirect/

أنت: /opsx:ff

المساعد: ✓ تم إنشاء وثائق التخطيط

أنت: /opsx:apply

المساعد: جاري العمل على fix-login-redirect...
         [ينفذ الإصلاح]
         اكتملت جميع المهام!

أنت: /opsx:archive

المساعد: ✓ تم أرشفة fix-login-redirect

أنت: لنعد إلى الوضع الداكن

أنت: /opsx:apply add-dark-mode

المساعد: استئناف add-dark-mode...
         الاستئناف من المهمة 2.3: تحديث الرأس...

الأفضل لـ: تدفقات العمل المتوازية، المقاطعات العاجلة، التعاون بين الفريق.

عندما يكون لديك عدة تغييرات مكتملة، استخدم /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...

     الاكتمال
     ✓ جميع المهام الـ 12 في tasks.md محددة
     ✓ جميع المتطلبات في المواصفات لها كود مقابل
     ⚠ السيناريو "انتهاء صلاحية الجلسة بعد عدم النشاط" لم يُختبر

     الصحة
     ✓ التنفيذ يتوافق مع نية المواصفات
     ✓ الحالات الهامشية من السيناريوهات معالجة
     ✓ حالات الخطأ تتطابق مع تعريفات المواصفات

     الاتساق
     ✓ قرارات التصميم منعكسة في هيكل الكود
     ✓ اتفاقيات التسمية متسقة مع design.md
     ⚠ يذكر التصميم "مدعوم بالأحداث" لكن التنفيذ يستخدم الاستطلاع

     الملخص
     ─────────────────────────────
     مشكلات حرجة: 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 أولاً، الباقي لاحقاً)
  • تصحيحات مدفوعة بالتعلم (قاعدة الكود ليست كما توقعت)
  • تعديلات تصميمية بناءً على اكتشافات التنفيذ

ابدأ تغييراً جديداً عندما:

  • تغيرت النية جذرياً
  • انفجر النطاق ليصبح عملاً مختلفاً تماماً
  • يمكن وضع علامة "مكتمل" على التغيير الأصلي بشكل مستقل
  • التصحيحات ستربك أكثر مما توضح
text
                     ┌─────────────────────────────────────┐
                     │     هل هذا العمل نفسه؟          │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          نفس النية؟      >50% تشابه؟      هل يمكن للأصلي
          نفس المشكلة?     نفس النطاق?        أن يكون "مكتملاً" بدون
                 │                  │          هذه التغييرات؟
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      نعم               لا نعم           لا  لا              نعم
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    تحديث            جديد  تحديث       جديد  تحديث          جديد

مثال: "إضافة الوضع الداكن"

  • "تحتاج أيضاً لدعم السمات المخصصة" → تغيير جديد (انفجر النطاق)
  • "اكتشاف تفضيل النظام أصعب مما توقعنا" → تحديث (نفس النية)
  • "لنطلق زر التبديل أولاً، ونضيف التفضيلات لاحقاً" → تحديث ثم أرشفة، ثم تغيير جديد

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

حافظ على تركز التغييرات ​

وحدة منطقية واحدة من العمل لكل تغيير. إذا كنت تقوم بـ "إضافة الميزة X وإعادة هيكلة Y أيضًا"، فكّر في فصلهما إلى تغييرين مستقلين.

لماذا هذا مهم:

  • أسهل في المراجعة والفهم
  • سجل أرشيف أنظف
  • إمكانية النشر بشكل مستقل
  • تراجع أبسط عند الحاجة

استخدم /opsx:explore للمتطلبات غير الواضحة ​

قبل الالتزام بتغيير، استكشف مساحة المشكلة:

text
You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle rate limiting for our API?

AI:  Let me investigate your current setup and options...
     [Researches codebase, considers patterns]

     I see three approaches we could take:
     1. Middleware-based (simple, per-endpoint)
     2. Redis-backed (scalable, shared state)
     3. Token bucket per user (fair, complex)

     Your current stack suggests #1 or #2. What's your scale?

الاستكشاف يوضح التفكير قبل إنشاء المخرجات.

تحقّق قبل الأرشفة ​

استخدم /opsx:verify للتحقق من أن التنفيذ يتطابق مع المخرجات:

text
You: /opsx:verify

AI:  Verifying add-dark-mode...

     ✓ All tasks in tasks.md are checked
     ✓ Requirements in specs have corresponding code
     ✓ Design decisions are reflected in implementation

     Ready to archive!

يرصد عدم التطابق قبل إغلاق التغيير.

سمِّ التغييرات بوضوح ​

الأسماء الجيدة تجعل openspec list مفيدة:

text
Good:                          Avoid:
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

مرجع سريع للأوامر ​

للتفاصيل الكاملة حول الأوامر والخيارات، راجع الأوامر.

الأمرالغرضمتى يُستخدم
/opsx:proposeإنشاء تغيير + مخرجات تخطيطالمسار الافتراضي السريع (ملف core)
/opsx:exploreالتفكير في الأفكار مع الذكاء الاصطناعيابدأ هنا عند عدم اليقين: متطلبات غير واضحة، تحقيق، مقارنة خيارات
/opsx:newبدء هيكل تغييرالوضع الموسّع، تحكّم صريح في المخرجات
/opsx:continueإنشاء المخرج التاليالوضع الموسّع، إنشاء المخرجات خطوة بخطوة
/opsx:ffإنشاء جميع مخرجات التخطيطالوضع الموسّع، نطاق واضح
/opsx:applyتنفيذ المهامجاهز لكتابة الكود
/opsx:verifyالتحقق من التنفيذالوضع الموسّع، قبل الأرشفة
/opsx:syncدمج مواصفات الفروقالوضع الموسّع، اختياري
/opsx:archiveإكمال التغييراكتمل كل العمل
/opsx:bulk-archiveأرشفة تغييرات متعددةالوضع الموسّع، عمل متوازٍ

الخطوات التالية ​