كتابة مواصفات جيدة
نادرًا ما تكتب مواصفة من صفحة فارغة. تصف التغيير بلغة بسيطة، ويقوم /opsx:propose بصياغة المتطلبات والسيناريوهات، ثم تقوم بتحسينها. تتناول هذه الصفحة الجزء الأخير — كيف تبدو المواصفة "الجيدة"، وكيفية توجيه الذكاء الاصطناعي نحو ذلك.
وهي مكملة لـ مراجعة التغيير: المراجعة هي اكتشاف نقاط الضعف في المسودة، بينما الكتابة هي معرفة مكونات النسخة القوية.
المواصفة سلوك وليست كودًا
تقول المواصفة ماذا يفعل نظامك بالضبط، بطريقة يمكن لأي شخص التحقق منها — وليس كيف تم بناؤه. تتكون من متطلبات (بيانات عن السلوك) وسيناريوهات (أمثلة ملموسة تثبتها).
### Requirement: Session Timeout
The system SHALL expire a session after 30 minutes of inactivity.
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass with no activity
- THEN the session is invalidated and the user must re-authenticateاحتفظ بـ كيف — الطابور، المكتبة، مخطط الجدول — في design.md أو الكود. عندما تختلط السلوكيات بالتنفيذ في متطلب واحد، يتوقف المتطلب عن أن يكون قابلاً للاختبار ويبدأ في التقادم بمجرد تغيير الكود.
ما الذي يجعل المتطلب جيدًا
المتطلب الجيد هو متطلب واحد، مُصاغ ببساطة بحيث يمكنك تسليمه لشخص آخر لاختباره.
عبارة واحدة،
SHALL/MUSTواحدة. إذا كان المتطلب يحتوي على ثلاث عبارات "وأيضًا"، فهو في الواقع ثلاثة متطلبات. افصل بينها.قابل للملاحظة. يجب أن يتمكن شخص خارج نطاق الكود من معرفة ما إذا كان ينطبق أم لا. "يجب على النظام عرض لافتة خطأ عند تجاوز حجم التحميل 10 ميجابايت" قابل للملاحظة. "يجب على النظام التعامل مع التحميلات الكبيرة بسلاسة" ليس كذلك.
القوة المناسبة. يستخدم OpenSpec كلمات RFC 2119، ولها معانٍ مختلفة:
الكلمة المفتاحية المعنى MUST/SHALLمتطلب صارم. غير قابل للتفاوض. SHOULDتوصية قوية، مع وجود مجال لاستثناء مبرر. MAYاختياري حقًا. اعتمد على
MUST/SHALLبشكل افتراضي. استخدمSHOULDفقط عندما تعني حقًا "ما لم يكن هناك سبب جيد لعدم القيام بذلك".
اختبار المتطلب: هل يمكن لمختبر لم يرَ الكود من قبل أن يخبرك عما إذا كان قد نجح؟ إذا لم يكن الأمر كذلك، فهو يحتاج إلى التشديد عليه.
ما الذي يجعل السيناريو جيدًا
السيناريوهات هي حيث يثبت المتطلب قيمته. كل سيناريو هو GIVEN / WHEN / THEN ملموس يمكن أن يصبح اختبارًا آليًا.
- يُجرب متطلبه. السيناريو الذي يعيد صياغة المتطلب بكلمات أخرى لا يختبر شيئًا. اجعله حالة محددة بنتيجة محددة.
- غطِ الحالات المهمة، وليس المسار السعيد فقط. تسجيل الدخول الصحيح أمر سهل. الإدخال الفارغ، الرمز المنتهي الصلاحية، النقرة الثانية، الشيء الذي يسوء — هذه هي أماكن وجود الأخطاء، حيث يكون السيناريو ذا قيمة أكبر.
- سمِّ الحالة في العنوان. "Scenario: Rejects an expired token" يخبر المراجع بما يتم تغطيته بنظرة خاطفة؛ "Scenario: Test 2" لا يفعل ذلك.
عادة مفيدة: قبل الموافقة، اسأل ما هي الحالة الوحيدة التي سأكون غاضبًا لرؤيتها مكسورة؟ — وتأكد من أن سيناريو يذكرها.
اختر نوع الدلتا المناسب
يصف التغيير تحريراتاته في المواصفات باستخدام ثلاثة أنواع من الأقسام. استخدام النوع الصحيح يحافظ على دقة المواصفات المؤرشفة:
## ADDED Requirements— سلوك جديد تمامًا لم يكن موجودًا من قبل.## MODIFIED Requirements— سلوك كان موجودًا بالفعل ويتغير. قم بتضمين النسخة الجديدة الكاملة؛ ملاحظة قصيرة حول ما تغير تساعد المراجع.## REMOVED Requirements— سلوك يتم إزالته، مع سطر يوضح السبب.
عند الأرشفة، يتم إلحاق ADDED بالمواصفة الرئيسية، وتحل MODIFIED محل النسخة القديمة، ويتم إسقاط REMOVED منها. أزل المتطلب الأخير الذي تمتلكه القدرة وسيتقاعد: بدلاً من ترك مواصفة فارغة، تحذف الأرشفة openspec/specs/<capability>/spec.md. لأن هذه هي خطوة الأرشفة الوحيدة التي تحذف ملفًا، يجب طلبها — أضف retire_capabilities: true إلى .openspec.yaml الخاص بالتغيير، بجانب schema: الذي تحتاجه الملف بالفعل. بدونها، ستفشل الأرشفة وتخبرك بذلك. يؤدي التقاعد إلى حذف الملف بالكامل، لذلك يتم رفضه أيضًا أثناء احتفاظ المواصفة بأي شيء خارج عنوانها، ## Purpose، وكتل المتطلبات الخاصة بها — قسم ## Notes، تعليق تحت متطلب. يذكر الانسحاب تلك الأسطر؛ انقلها إلى ## Purpose أو متطلب، أو احذف المواصفة يدويًا. بالنسبة للمواصفة الموجودة في فحص المستدعي، يذكر إخراج الأرشفة أيضًا git checkout الذي يستعيد ملفًا ملتزمًا؛ تتلقى المستودعات المحددة إرشادات استرداد محدودة بالنطاق بدلاً من ذلك. إذا قمت بتحديد تغيير حقيقي على أنه ADDED، فسيكون لديك متطلبان متنافسان؛ إذا وصفت سلوكًا جديدًا على أنه MODIFIED، فلن يكون هناك ما يتم استبداله. عند الشك، افتح المواصفة الحالية وانظر ما إذا كان المتطلب موجودًا بالفعل.
يوجد قسم آخر يستحق المعرفة. عندما ينشئ دلتا الخاص بك قدرة غير موجودة بعد، افتحه بـ ## Purpose — جملة أو جملتين حول الغرض من القدرة. تستخدمها الأرشفة كـ Purpose للمواصفة الرئيسية التي تنشئها؛ تخطيها وستحصل على مكانة TBD يجب ملؤها يدويًا. تحتوي المواصفة الموجودة بالفعل على Purpose، لذا يتم تجاهل دلتا الخاص بها هناك — قم بتحرير openspec/specs/<capability-path>/spec.md مباشرة لتغيير واحد. هنا، <capability-path> هو الدليل النسبي لـ specs/، مثل user-auth في مشروع مسطح أو identity/user-auth في مشروع منظم حسب المجال.
ضبط حجم التغيير
خطأ التأليف الأكثر شيوعًا ليس متطلبًا مكتوبًا بشكل سيء — إنه تغيير يحاول أن يكون ثلاثة تغييرات.
التغيير الجيد له نية واحدة يمكنك قولها في جملة. "إضافة زر تبديل الوضع الداكن." "تقييد معدل نقطة نهاية تسجيل الدخول." "تحويل الجلسات بعيدًا عن ملفات تعريف الارتباط." إذا كانت وصف التغيير يتطلب الكثير من "وأيضًا"، فهذا هو الإشارة إلى تقسيمه.
علامات أن التغيير كبير جدًا:
- نطاق الاقتراح يبدو وكأنه قائمة بميزات غير ذات صلة.
- مراجعته ستستغرق فترة بعد الظهر، لذلك لن يقوم بها أحد.
- لا يستطيع شخصان العمل عليه دون التصادم.
- نصف المهام يمكن شحنها بمفردها.
التغييرات الأصغر أسهل في المراجعة، أسهل في البناء في جلسة واحدة مركزة، وأسهل في الاستدلال عليها بعد ستة أشهر عندما تكون الأرشفة هي كل ما تبقى. يمكنك دائمًا تشغيل عدة تغييرات بالتوازي — انظر التحرير والتكرار وسير العمل.
يحدث العكس أيضًا: إصلاح خطأ مطبعي في سطر واحد لا يحتاج إلى ثلاثة متطلبات ومستند تصميم. طقوس الحفل تناسب المخاطر.
كيفية توجيه الذكاء الاصطناعي نحو مسودة جيدة
لأن /opsx:propose يقوم بالمسودة الأولى، فإن جودة ما تحصل عليه تتبع جودة ما تعطيه. ليس عليك كتابة المتطلبات يدويًا — عليك توجيه الذكاء الاصطناعي جيدًا:
- اذعل النية والحدود. "إضافة زر تبديل الوضع الداكن الذي يتبع إعداد النظام التشغيلي عند التحميل الأول — لا تلمس واجهة برمجة التطبيقات للثيم الموجودة." الجزء خارج النطاق مهم بقدر الجزء داخل النطاق.
- سمِّ الحالات التي تهتم بها. "تأكد من وجود سيناريو لمستخدم اختار ثيمًا يدويًا بالفعل." يغطي الذكاء الاصطناعي ما تشير إليه.
- ثم قم بالتحرير. إنه Markdown عادي. شدد
SHALLالغامض، احذف سيناريو لا يختبر شيئًا، أضف الحالة التي فاتته — أو اطلب من الذكاء الاصطناعي: "متطلب مهلة الوقت غامض، ثبتّه على 30 دقيقة."
مسودة، تشديد، تكرار. تنتج بضعة جولات من ذلك مواصفة تثق بها، وهو الهدف الكامل.
قائمة مراجعة سريعة
أين تذهب بعد ذلك
- مراجعة التغيير — المرور السريع لمدة دقيقتين الذي يلتقط ما فات.
- المفاهيم — النموذج الأعمق وراء المواصفات والتغييرات والدلتا.
- أمثلة ووصفات — تغييرات حقيقية من البداية إلى النهاية.