المفاهيم الأساسية في لمحة سريعة

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

إليك الفكرة بأكملها في خمس كلمات: اتفق أولاً، ثم ابنِ بثقة.

الأفكار الخمسة

كل شيء في OpenSpec مبني على خمس مفاهيم. تعلم هذه المفاهيم وسيكون الباقي تفصيلاً.

1. المواصفات هي الحقيقة. تصف المواصفات كيف يعمل نظامك الآن. وهي موجودة في openspec/specs/، منظمة حسب المجال (auth/, payments/, ui/). تتكون المواصفات من المتطلبات ("يجب على النظام انتهاء الجلسات بعد 30 دقيقة") والسيناريوهات (أمثلة ملموسة "إذا/عندما/إذن"). فكر في المواصفات على أنها الإجابة الواحدة المتفق عليها لسؤال: "ماذا يفعل هذا البرنامج؟"

2. التغيير هو وحدة عمل واحدة. عندما تريد إضافة أو تعديل أو إزالة سلوك ما، فإنك تنشئ تغييرًا: وهو مجلد في openspec/changes/ يحتوي على كل شيء يتعلق بهذا العمل في مكان واحد. مقترح، وتصميم، وقائمة مهام، وتعديلات المواصفات. تغيير واحد، ومجلد واحد، وميزة واحدة.

3. مواصفات دلتا (Delta specs) تصف ما يتغير، وليس العالم بأكمله. داخل التغيير، لا تعيد كتابة المواصفات بالكامل. بل تكتب "دلتا" صغيرة: ADDED هذا المتطلب، وMODIFIED ذاك، وREMOVED ذاك الآخر. هذه هي الحيلة التي تجعل OpenSpec جيدًا في تحرير الأنظمة الموجودة، وليس فقط تلك التي تبدأ من الصفر. أنت تصف الاختلاف (diff)، لا الوجهة النهائية.

4. المخرجات (Artifacts) تُبنى على بعضها البعض. يحتوي التغيير على بضع وثائق، يتم إنشاؤها بترتيب طبيعي، وكل منها يغذي التالي:

proposal ──► specs ──► design ──► tasks ──► implement
   why        what       how       steps      do it

يمكنك مراجعة أي منها في أي وقت. إنها عوامل تمكين، وليست حواجز. (المزيد عن ذلك أدناه).

5. الأرشفة تعيد التغيير إلى الحقيقة. عندما ينتهي العمل، تقوم بأرشفة التغيير. وتندمج مواصفات الدلتا الخاصة به في المواصفات الرئيسية، ويُنقل مجلد التغيير إلى changes/archive/ مع ختم تاريخ. الآن تصف مواصفاتك الواقع الجديد، وأنت مستعد للتغيير التالي. يكتملت الدورة.

الصورة العامة

┌─────────────────────────────────────────────────────────────────┐
│                          openspec/                              │
│                                                                 │
│   ┌──────────────────┐         ┌──────────────────────────┐    │
│   │     specs/       │         │        changes/          │    │
│   │                  │ ◄─────  │                          │    │
│   │ مصدر الحقيقة    │  merge  │ مجلد واحد لكل تغيير      │    │
│   │ كيف تسير الأمور │  على     │ proposal · design ·      │    │
│   │ اليوم           │ archive │ tasks · delta specs      │    │
│   └──────────────────┘         └──────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

مجلدان. specs/ هو ما هو حقيقي. وchanges/ هو ما تقترحه. الأرشفة تنقل المقترح إلى الحقيقة.

الحلقة التي ستنفذها بالفعل

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

/opsx:explore                   →  (اختياري) التفكير مع الذكاء الاصطناعي أولاً
/opsx:propose add-dark-mode     →  يقوم الذكاء الاصطناعي بصياغة المقترح والمواصفات والتصميم والمهام
        (تقرأ وتعدل الخطة)
/opsx:apply                     →  يقوم الذكاء الاصطناعي ببنائه، ومراجعة المهام
/opsx:archive                   →  تحديث المواصفات، وأرشفة التغيير

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

هذه أوامر سلاش (slash commands)، تُكتب في دردشة مساعد الذكاء الاصطناعي الخاص بك. يتم الإعداد (openspec init) في الطرفية الخاصة بك. إذا كان هذا التقسيم جديدًا بالنسبة لك، فاقرأ كيف تعمل الأوامر أولاً؛ فهذه هي النقطة الأكثر شيوعًا للالتباس.

"عوامل تمكين، وليست حواجز"

تظهر هذه العبارة في كل مكان في OpenSpec، لذا إليك ما تعنيه بالكلمات الواضحة.

عمليات المواصفات القديمة هي شلالات: تنهي التخطيط، ثم يُسمح لك بالتنفيذ، والعودة تكون مؤلمة. OpenSpec يرفض ذلك. يعرض الترتيب proposal → specs → design → tasks ما يصبح ممكنًا بعد ذلك، وليس ما أنت مجبر على فعله تاليًا.

هل تكتشف أثناء التنفيذ أن التصميم خاطئ؟ قم بتحرير design.md واستمر. هل تدرك أن النطاق يجب أن يتقلص؟ حدّث المقترح. لا شيء يقفل عليك. التبعيات موجودة فقط لكي يكون لدى الذكاء الاصطناعي السياق الذي يحتاجه (لا يمكنك كتابة مهام جيدة دون مواصفات تعتمد عليها)، وليس لحصرك.

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

لماذا يستحق هذا العبء البسيط

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

• أنت تلتقط التحولات الخاطئة قبل أن تكلفك شيئًا. تصحيح سوء فهم في مقترح من فقرة واحدة مجاني. وتصحيحه بعد أن يكتب الذكاء الاصطناعي 400 سطر ليس كذلك.
• الخطة والكود يبقىان في نفس المستودع (repo). بعد ستة أشهر، تخبرك المواصفات (وجلسة الذكاء الاصطناعي التالية) لماذا يعمل النظام بالطريقة التي يعمل بها.
• التغييرات قابلة للمراجعة. مجلد التغيير هو حزمة مرتبة: اقرأ المقترح، وتصفح الدلتا، وتحقق من المهام. لا حاجة للحفريات في سجل الدردشة.
• إنه يتناسب مع قواعد الكود الموجودة. تعني الدلتاس أنه يمكنك تحديد تغيير لتطبيق مكون من 50,000 سطر دون توثيق كل شيء أولاً.

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

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

• هل أنت جديد؟ Getting Started يغطي التغيير الأول بالكامل.
• لست متأكدًا مما يجب بناؤه بعد؟ Explore First هو المكان الذي تبدأ منه.
• هل أنت مرتبك بشأن مكان تشغيل الأوامر؟ How Commands Work.
• هل تريد النسخة العميقة لكل ما سبق؟ Concepts.
• هل تتعلم بالمثال؟ Examples & Recipes.
• هل تحتاج إلى تعريف مصطلح؟ Glossary.