كتابة المواصفات الجيدة

نادراً ما تكتب مواصفة من صفحة فارغة. تصف التغيير بلغة بسيطة، ثم يقوم الأمر /opsx:propose بصياغة المتطلبات والسيناريوهات، وبعدها تقوم بتحسينها. هذه الصفحة تتناول الجزء الأخير من هذه العملية — ما معنى أن تكون المواصفة "جيدة"، وكيف توجه الذكاء الاصطناعي لتحقيق ذلك.

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

المواصفة هي سلوك، وليس كوداً

تحدد المواصفة ما يفعله نظامك، بعبارات يمكن لأي شخص التحقق منها — وليس كيف تم بناؤه. تتكون من متطلبات (عبارات تصف السلوك) وسيناريوهات (أمثلة ملموسة تثبت صحة هذه المتطلبات).

### المتطلب: انتهاء صلاحية الجلسة
النظام SHALL ينهي صلاحية الجلسة بعد 30 دقيقة من عدم النشاط.

#### السيناريو: انتهاء الصلاحية بسبب الخمول
- GIVEN وجود جلسة مصادقة عليها
- WHEN تمر 30 دقيقة بدون أي نشاط
- THEN يتم إلغاء صلاحية الجلسة ويجب على المستخدم إعادة المصادقة

احتفظ بـ كيفية التنفيذ — الطابور، المكتبة، مخطط الجدول — في ملف design.md أو في الكود. عندما يتم خلط السلوك وآلية التنفيذ في متطلب واحد، يتوقف هذا المتطلب عن أن يكون قابلاً للاختبار، ويبدأ في أن يصبح قديمًا بمجرد تغيير الكود.

ما الذي يجعل المتطلب جيداً

المتطلب الجيد هو متطلب يصف سلوكًا واحدًا، مكتوبًا ببساطة بحيث يمكنك تسليمه لشخص آخر لاختباره.

• عبارة واحدة، ورمز SHALL/MUST واحد. إذا كان المتطلب يحتوي على ثلاث شروط تبدأ بـ "وأيضاً"، فهذا يعني أنه في الواقع ثلاثة متطلبات منفصلة. قم بتقسيمها.

• قابل للملاحظة. يجب أن يكون أي شخص خارج فريق التطوير قادرًا على التحقق من تحقق هذا المتطلب. المتطلب "النظام SHALL يعرض شريط خطأ عند تجاوز حجم الرفع 10 ميجابايت" قابل للملاحظة، أما المتطلب "النظام SHALL يتعامل مع عمليات الرفع الكبيرة بسلاسة" فليس كذلك.

• القوة المناسبة. تستخدم OpenSpec كلماتRFC 2119 المفتاحية، ولكل منها معنى مختلف:

  الكلمة المفتاحية	المعنى
  MUST / SHALL	متطلب إلزامي. لا يمكن التفاوض عليه.
  SHOULD	توصية قوية، مع إمكانية وجود استثناء مبرر.
  MAY	اختياري حقًا.

  استخدم MUST/SHALL افتراضيًا. استخدم SHOULD فقط عندما تعني حقًا "ما لم يكن هناك سبب وجيه لعدم ذلك".

اختبار المتطلب هو: هل يمكن لمختبر لم يرى الكود من قبل أن يحدد ما إذا كان المتطلب قد تم تحقيقه؟ إذا كانت الإجابة لا، فالمتطلب بحاجة إلى مزيد من الدقة.

ما الذي يجعل السيناريو جيداً

السيناريوهات هي التي تجعل المتطلب ذا فائدة. كل سيناريو هو حالة ملموسة تتبع نمط GIVEN / WHEN / THEN، ويمكن تحويلها إلى اختبار آلي.

• يختبر متطلبه. السيناريو الذي يعيد صياغة المتطلب بكلمات أخرى لا يختبر أي شيء. اجعله حالة محددة بنتيجة محددة.
• غطي الحالات المهمة، ولا تكتفِ بالمسار الناجح فقط. عملية تسجيل الدخول الصحيحة سهلة الاختبار. أما الإدخال الفارغ، الرمز المميز المنتهي الصلاحية، النقر الثاني، أو الحالة التي تسوء الأمور فيها — فهذه هي الأماكن التي توجد فيها الأخطاء، وهي الأماكن التي تكون فيها السيناريوهات ذات فائدة قصوى.
• سمِ الحالة في عنوان السيناريو. عنوان "السيناريو: رفض الرمز المميز المنتهي الصلاحية" يخطر المراجع بما يتم تغطيته بمجرد النظر، أما عنوان "السيناريو: اختبار 2" فلا يفعل ذلك.

عادة مفيدة: قبل الموافقة على التغيير، اسأل نفسك ما هي الحالة الوحيدة التي سأغضب إذا رأيتها معطلة؟ — وتأكد من وجود سيناريو يغطي هذه الحالة.

اختر نوع الدلتا المناسب

يصف التغيير تعديلاته على المواصفات باستخدام ثلاثة أنواع من الأقسام. استخدام النوع المناسب يحافظ على دقة المواصفات المؤرشفة:

• ## ADDED Requirements — سلوك جديد لم يكن موجودًا من قبل.
• ## MODIFIED Requirements — سلوك كان موجودًا من قبل ويتم تعديله. قم بتضمين الإصدار الجديد بالكامل؛ وملاحظة قصيرة عن التغييرات تساعد المراجع.
• ## REMOVED Requirements — سلوك يتم إيقافه، مع ذكر سبب الإيقاف.

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

حجم التغيير المناسب

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

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

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

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

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

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

كيف توجه الذكاء الاصطناعي لصياغة مسودة جيدة

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

• حدد النية والحدود. "إضافة مفتاح تبديل للوضع الداكن يتبع إعدادات نظام التشغيل عند التحميل الأول — ولا تلمس واجهة برمجة التطبيقات API للسمات الموجودة حاليًا." الجزء الخاص بما هو خارج النطاق مهم بنفس أهمية الجزء الخاص بما هو داخل النطاق.
• حدد الحالات التي تهتم بها. "تأكد من وجود سيناريو لمستخدم قام باختيار سمة يدويًا مسبقًا." يغطي الذكاء الاصطناعي ما تشير إليه أنت.
• ثم قم بالتحرير. المحتوى عبارة عن ماركداون بسيط. قم بتحديد متطلب SHALL الغامض، احذف السيناريو الذي لا يختبر أي شيء، أضف الحالة التي فاتتها — أو اطلب من الذكاء الاصطناعي القيام بذلك: "متطلب انتهاء الصلاحية غامض، قم بتحديده إلى 30 دقيقة."

صيغ المسودة، حسّنها، كرر العملية. بضع جولات من ذلك تنتج مواصفة يمكنك الوثوق بها، وهذا هو الهدف كله.

قائمة تحقق سريعة

• [ ] كل متطلب يصف سلوكًا واحدًا قابلًا للملاحظة ويحتوي على SHALL/MUST.
• [ ] لا توجد تفاصيل تنفيذ مدمجة في المتطلبات.
• [ ] كل متطلب لديه سيناريو واحد على الأقل يختبره فعليًا.
• [ ] الحالات الحدية وحالات الخطأ المهمة لها سيناريوهات خاصة بها، ولا تكتفى بالمسار الناجح فقط.
• [ ] تستخدم الدلتا أقسام ADDED / MODIFIED / REMOVED بشكل صحيح مقابل المواصفة الحالية.
• [ ] التغيير كله له نية واحدة يمكنك التعبير عنها في جملة واحدة.

إلى أين تذهب بعد ذلك

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