أمثلة ووصفات عمل

تغييرات حقيقية، من البداية إلى النهاية. كل وصفة عمل تعرض الأوامر التي ستكتبها والنتيجة التي ستحصل عليها، حتى تتمكن من مطابقة حالتك مع نمط جاهز ونسخه. تستخدم هذه الوصفات الأوامر الأساسية الافتراضية (propose، explore، apply، sync، archive)؛ وفي الحالات التي تساعد فيها المجموعة الموسعة من الأوامر، سيتم الإشارة إلى ذلك.

تذكير قبل أن تبدأ: الأوامر المنحرفة مثل /opsx:propose تكتب في دردشة مساعد الذكاء الاصطناعي الخاص بك، بينما أوامر openspec تكتب في الطرفية. إذا كان هذا جديداً عليك، اقرأ كيف تعمل الأوامر أولاً. في النصوص الحوارية أدناه، تمثل أنت: و ذكاء اصطناعي: الدردشة، والأسطر التي تبدأ ب $ تمثل الأوامر في الطرفية.

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

الوصفة 1: ميزة صغيرة، المسار السريع

متى تستخدمها: عندما تعرف ما تريد، وهو عمل منفصل ومحدد. هذه هي الوصفة الأكثر شيوعاً.

كل العمل يتطلب ثلاثة أوامر فقط: اقتراح، بناء، أرشفة.

أنت: /opsx:propose add-logout-button

ذكاء اصطناعي:  تم إنشاء openspec/changes/add-logout-button/
     ✓ proposal.md — السبب والمحتوى
     ✓ specs/      — المتطلب الجديد وسيناريوهاته
     ✓ design.md   — النهج التقني
     ✓ tasks.md    — قائمة مهام التنفيذ
     جاهز للتنفيذ. قم بتشغيل /opsx:apply.

الآن اقرأ الخطة. افتح العرض التقديمي ومواصفة التغيير. هذه هي اللحظة التي صُمم OpenSpec من أجلها: اكتشاف افتراض خاطئ بينما لا يزال فقرة واحدة، لا 400 سطر من الكود. عدل أي عنصر مباشرة إذا كان هناك خطأ، ثم تابع.

أنت: /opsx:apply

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

أنت: /opsx:archive

ذكاء اصطناعي:  جاري أرشفة add-logout-button...
     ✓ تم دمج المواصفات في openspec/specs/auth/spec.md
     ✓ تم النقل إلى openspec/changes/archive/2026-06-22-add-logout-button/
     تم الانتهاء. جاهز للتغيير التالي.

هذا كل شيء. أصبح سلوك تسجيل الخروج الآن جزءاً من مواصفاتك، وتم أرشفة التغيير مع سياقه الكامل.

الوصفة 2: إصلاح عيب برمجي

متى تستخدمها: عندما يكون هناك شيء معطل، وتريد تسجيل الإصلاح كتغيير متعمد للسلوك، لا كإيداع غامض.

يعمل إصلاح العيوب البرمجية تماماً مثل الميزات. الفرق يكمن في كيفية صياغة العرض التقديمي: صف السلوك الصحيح، ولا تقتصر على قول "إصلاح العيب".

أنت: /opsx:propose fix-login-redirect-loop

ذكاء اصطناعي:  تم إنشاء openspec/changes/fix-login-redirect-loop/
     يلتقط العرض التقديمي السلوك المعطل الحالي والسلوك المقصود.
     تقوم مواصفة التغيير **بتعديل** متطلب إعادة التوجيه لجعله دقيق وقابل للاختبار الآن.
     جاهز للتنفيذ.

بما أن الإصلاح يظهر كمتطلب MODIFIED مع سيناريو جديد، فإن الشخص التالي (أو جلسة الذكاء الاصطناعي التالية) لن يرى فقط أنك قمت بإصلاحه، بل ماذا يعني "الصحيح". ثم استخدم /opsx:apply و /opsx:archive كالمعتاد.

نصيحة: بالنسبة للإصلاح، السيناريو الجيد هو اختبار الانحدار مكتوباً بالنص. "بفرض وجود مستخدم غير مسجل الدخول، عندما يقدم بيانات اعتماد صحيحة، ثم ينتقل إلى لوحة التحكم ولا يتم إعادة توجيهه مرة أخرى". اكتب هذا، وسيكون للتنفيذ هدف واضح.

الوصفة 3: الاستكشاف قبل إيداع التغيير

متى تستخدمها: عندما تكون لديك مشكلة ولكن ليس لديك خطة بعد. لست متأكداً مما ستبنيه، أو أي نهج هو الصحيح.

ابدأ بأمر /opsx:explore. هو شريك تفكير بلا هيكل محدد ولا ينشئ أي عناصر عمل. يقرأ قاعدة الكود الخاصة بك ويساعدك على اتخاذ القرار.

أنت: /opsx:explore

ذكاء اصطناعي:  ماذا تريد أن تستكشف؟

أنت: تحميل الصفحات بطيء ولكنني لا أعرف أين يذهب الوقت.

ذكاء اصطناعي:  دعني أتحقق... وجدت ثلاثة أسباب محتملة:
     1. صور كبيرة غير محسنة على قائمة المنتجات
     2. جلب بيانات متزامن يمنع عملية العرض
     3. إعادة عرض الصفحة triggered by تغييرات في السياق
     أي منها نعالج أولاً؟

أنت: الخاص بجلب البيانات.

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

ذكاء اصطناعي:  تم إنشاء التغيير، مع عرض تقديمي مستنير بما وجدناه للتو.
     جاهز للتنفيذ.

الاستكشاف يوضح تفكيرك قبل أن تنفق تغييراً عليه. عندما تتضح الرؤية، قم بالاقتراح، وسيحمل الذكاء الاصطناعي السياق إلى الأمام.

الوصفة 4: إدارة تغييرين في وقت واحد

متى تستخدمها: عندما تكون في منتصف عمل ميزة ويقفز إصلاح عاجل إلى مقدمة الطابور.

التغييرات عبارة عن مجلدات مستقلة، لذا لا يتعارض العمل المتوازي. ابدأ بالإصلاح، أتمه وأرشفه، ثم عد إلى الميزة من النقطة التي توقفت عندها بالضبط.

أنت: أنا في منتصف عمل add-dark-mode، ولكن أحتاج إلى إصلاح عيب في تسجيل الدخول الآن.

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

ذكاء اصطناعي:  تم إنشاء openspec/changes/fix-login-redirect/. جاهز للتنفيذ.

أنت: /opsx:apply

ذكاء اصطناعي:  تم تنفيذ الإصلاح. تم الانتهاء من جميع المهام.

أنت: /opsx:archive

ذكاء اصطناعي:  ✓ تمت أرشفة fix-login-redirect.

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

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

ذكاء اصطناعي:  استئناف عمل add-dark-mode. الاستمرار من المهمة 2.3: تحديث الترويسة...

تسمية التغيير في أمر /opsx:apply add-dark-mode هي الطريقة التي تشير بها إلى الذكاء الاصطناعي لتحديد التغيير المطلوب عندما يكون هناك أكثر من تغيير نشط. وبما أن المهام تتتبع حالة الإنجاز في ملف tasks.md، يعرف الذكاء الاصطناعي بالضبط أين توقفت.

عند إنجاز عدة تغييرات في وقت واحد، يقوم الأمر الموسع /opsx:bulk-archive بأرشفتها معاً وحل تعارضات المواصفات من خلال التحقق مما تم تنفيذه فعلياً. راجع سير العمل.

الوصفة 5: إعادة هيكلة بدون تغيير في السلوك

متى تستخدمها: عندما تعيد هيكلة الكود، ويجب أن يبقى السلوك الظاهر للخارج مطابقاً تماماً.

هذه هي الحالة المثيرة للاهتمام، لأن إعادة الهيكلة النقية لا تضيف شيئاً إلى مواصفاتك. عقد السلوك لا يتغير؛ يتغير التنفيذ فقط. لذا يقع العمل في قسمي التصميم والمهام، وتكون مواصفة التغيير فارغة أو غير موجودة.

أنت: /opsx:propose refactor-payment-module

ذكاء اصطناعي:  تم إنشاء التغيير. يحدد العرض التقديمي الهدف (تقسيم وحدة الدفع، بدون تغيير في السلوك) ويحدد التصميم الهيكل الجديد. لا توجد تغييرات في المواصفات، لأن السلوك مطابق تماماً. جاهز للتنفيذ.

أعلن عن مواصفة التغيير الفارغة صراحةً عن طريق تعيين القيمة skip_specs: true في ملف .openspec.yaml الخاص بالتغيير:

schema: spec-driven
skip_specs: true

بدون هذا العلامة، سيرفض أمر openspec validate أي تغيير لا يحتوي على أي تغييرات في المواصفات (لذا يتم اكتشاف مرحلة المواصفات المنسية حتى لو تم نسيانها)؛ مع وجود العلامة، تنجز عملية التحقق ويظهر أمر openspec status أن مرحلة المواصفات تم تخطيها صراحةً بدلاً من كونها معلقة. إذا تبين أن إعادة الهيكلة تغير السلوك في النهاية، فاحذف السطر skip_specs من ملف .openspec.yaml واكتب مواصفات التغيير – يعامل أمر التحقق العلامة مع ملفات المواصفات كتعارض، لذا لا يمكن للعلامة القديمة أن تبقى صامتة دون أن يلاحظها أحد.

أرشفة تغيير مُعلَّم لا تحتاج إلى أي علامات إضافية (لا توجد مواصفات تغيير لدمجها). بشكل منفصل، تخبر علامة --skip-specs أمر الطرفية بتخطي خطوة المواصفات صراحةً:

$ openspec archive refactor-payment-module --skip-specs

هذه العلامة مفيدة أيضاً لأدوات التطوير، و CI، والتغييرات الخاصة بالوثائق فقط. المبدأ: المواصفات تصف السلوك، لذا إذا لم يتغير السلوك، فلا يجب أن تتغير المواصفة أيضاً. راجع المفاهيم.

الوصفة 6: تحكم خطوة بخطوة (أوامر موسعة)

متى تستخدمها: تغيير معقد أو عالي المخاطر، حيث تريد مراجعة كل عنصر قبل المتابعة.

يقوم الأمر الأساسي /opsx:propose بإنشاء مسودة لجميع العناصر مرة واحدة. عندما تفضل المتابعة خطوة بخطوة، قم بتفعيل الأوامر الموسعة:

$ openspec config profile      # تحديد سير العمل الموسع
$ openspec update              # تطبيقها على هذا المشروع

الآن يمكنك إنشاء الهيكل الأولي والبناء تدريجياً:

أنت: /opsx:new add-2fa

ذكاء اصطناعي:  تم إنشاء openspec/changes/add-2fa/. جاهز لإنشاء: العرض التقديمي.

أنت: /opsx:continue

ذكاء اصطناعي:  تم إنشاء proposal.md. متاح الآن: المواصفات، التصميم.

أنت: /opsx:continue

ذكاء اصطناعي:  تم إنشاء specs/auth/spec.md. متاح الآن: التصميم.

راجع كل عنصر بمجرد إنشائه، عدله بحرية، واستمر عندما تكون راضياً. عندما تريد إنشاء مسودة لبقية العناصر مرة واحدة، يقوم الأمر /opsx:ff بتخطي العناصر المتبقية من مرحلة التخطيط بسرعة. قبل الأرشفة، يتأكد أمر /opsx:verify من أن التنفيذ يطابق المواصفات فعلياً. راجع سير العمل.

الوصفة 7: تعلم دورة العمل بالكامل عملياً

متى تستخدمها: عندما تكون قد ثبّت OpenSpec وتريد تشعر بدورة العمل على الكود الخاص بك، لا على مثال تجريبي بسيط.

قم بتفعيل الأوامر الموسعة (راجع الوصفة 6)، ثم:

أنت: /opsx:onboard

ذكاء اصطناعي:  مرحباً بك في OpenSpec! سأقوم بإرشادك خلال تغيير كامل
     باستخدام قاعدة الكود الفعلية الخاصة بك. دعني أبحث عن تحسين
     صغير وآمن يمكننا تنفيذه معاً...

يجد أمر /opsx:onboard تحسيناً حقيقياً (صغيراً)، ينشئ تغييراً له، ينفذه، ويؤرشفها، مع سرد كل خطوة. يستغرق الأمر من 15 إلى 30 دقيقة ويترك لك تغييراً حقيقياً يمكنك الاحتفاظ به أو تجاهله. إنها الطريقة الأكثر سلاسة للتعلم. راجع الأوامر.

التحقق من عملك من الطرفية

في أي وقت، من خلال الطرفية الخاصة بك، يمكنك فحص حالة الأمور:

$ openspec list                      # التغييرات النشطة
$ openspec show add-dark-mode        # عرض تغيير واحد بتفصيل
$ openspec validate add-dark-mode    # التحقق من الهيكل
$ openspec view                      # لوحة تحكم تفاعلية

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

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

• استكشف أولاً: الطريقة الموصى بها للبدء عندما لست متأكداً
• سير العمل: الأنماط المذكورة أعلاه، مع إرشادات لاتخاذ القرار حول وقت استخدام كل منها
• الأوامر: كل أمر منحرف بتفصيل
• البدء: الدليل الرسمي الخطوة بخطوة للتغيير الأول
• المفاهيم: لماذا تتناسب القطع مع بعضها البعض بهذه الطريقة