أمثلة ووصفات

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

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

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

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

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

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

You: /opsx:propose add-logout-button

AI:  Created openspec/changes/add-logout-button/
     ✓ proposal.md — why and what
     ✓ specs/      — the new requirement and its scenarios
     ✓ design.md   — technical approach
     ✓ tasks.md    — implementation checklist
     Ready for implementation. Run /opsx:apply.

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

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Add logout button to header
     ✓ 1.2 Clear session on click
     ✓ 1.3 Add confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  Archiving add-logout-button...
     ✓ Merged specs into openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/
     Done. Ready for the next change.

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

الوصفة 2: إصلاح خطأ

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

إصلاحات الأخطاء تعمل تمامًا مثل الميزات. الفرق يكمن في كيفية صياغة الاقتراح: صف السلوك الصحيح، وليس فقط "إصلاح الخطأ".

You: /opsx:propose fix-login-redirect-loop

AI:  Created openspec/changes/fix-login-redirect-loop/
     The proposal captures the current broken behavior and the
     intended behavior. The delta spec MODIFIES the redirect
     requirement so it's now precise and testable.
     Ready for implementation.

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

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

الوصفة 3: الاستكشاف قبل الالتزام

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

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

You: /opsx:explore

AI:  What would you like to explore?

You: Page loads feel slow but I don't know where the time goes.

AI:  Let me look... I found three likely culprits:
     1. Large unoptimized images on the product list
     2. Synchronous data fetching that blocks render
     3. Re-renders triggered by context changes
     Which should we tackle first?

You: The data fetching one.

You: /opsx:propose optimize-product-list-fetching

AI:  Created the change, with a proposal informed by what we just
     found. Ready for implementation.

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

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

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

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

You: I'm partway through add-dark-mode, but I need to fix a login bug now.

You: /opsx:propose fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/. Ready for implementation.

You: /opsx:apply

AI:  Implemented the fix. All tasks complete.

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect.

You: Back to dark mode.

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode. Picking up at task 2.3: Update Header...

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

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

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

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

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

You: /opsx:propose refactor-payment-module

AI:  Created the change. The proposal states the goal (split the
     payment module, no behavior change) and the design captures
     the new structure. No spec changes, since behavior is identical.
     Ready for implementation.

أعلن عن الفارق الفارغ صراحةً عن طريق تعيين 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      # select the expanded workflows
$ openspec update              # apply them to this project

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

You: /opsx:new add-2fa

AI:  Created openspec/changes/add-2fa/. Ready to create: proposal.

You: /opsx:continue

AI:  Created proposal.md. Now available: specs, design.

You: /opsx:continue

AI:  Created specs/auth/spec.md. Now available: design.

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

الوصفة 7: تعلم الحلقة كاملةً عمليًا

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

فعّل الأوامر الموسعة (انظر الوصفة 6)، ثم:

You: /opsx:onboard

AI:  Welcome to OpenSpec! I'll walk you through a complete change
     using your actual codebase. Let me scan for a small, safe
     improvement we can make together...

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

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

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

$ openspec list                      # active changes
$ openspec show add-dark-mode        # one change in detail
$ openspec validate add-dark-mode    # check structure
$ openspec view                      # interactive dashboard

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

أين تذهب بعد

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