البدء

يشرح هذا الدليل كيفية عمل OpenSpec بعد تثبيتهتهيئته. للحصول على تعليمات التثبيت، راجع الملف الرئيسي README.

كيف يعمل

يساعدك OpenSpec أنت ومساعدك البرمجي بالذكاء الاصطناعي على الاتفاق على ما تريد بناءه قبل كتابة أي كود.

المسار السريع الافتراضي (الملف التعريفي الأساسي):

/opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive

المسار الموسع (اختيار سير عمل مخصص):

/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

الملف التعريفي العام الافتراضي هو core، الذي يتضمن propose و explore و apply و sync و archive. يمكنك تفعيل أوامر سير العمل الموسع باستخدام openspec config profile ثم openspec update.

ما ينشئه OpenSpec

بعد تشغيل openspec init، سيحتوي مشروعك على هذا الهيكل:

openspec/
├── specs/              # مصدر الحقيقة (سلوك نظامك)
│   └── <domain>/
│       └── spec.md
├── changes/            # التحديثات المقترحة (مجلد واحد لكل تغيير)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # مواصفات التغيير (ما يتغير)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # تكوين المشروع (اختياري)

دليلان رئيسيان:

• specs/ - مصدر الحقيقة. تصف هذه المواصفات سلوك نظامك الحالي. منظمة حسب المجال (مثل specs/auth/، specs/payments/).

• changes/ - التعديلات المقترحة. يحصل كل تغيير على مجلده الخاص مع جميع المصنفات ذات الصلة. عند اكتمال التغيير، تندمج مواصفاته في دليل specs/ الرئيسي.

فهم المصنفات

يحتوي مجلد كل تغيير على مصنفات توجه العمل:

المصنف	الغرض
proposal.md	"لماذا" و "ماذا" - يسجل النطاق والنية والمنهجية
specs/	مواصفات التغيير تظهر المتطلبات المُضافة/المُعدّلة/المُزالة
design.md	"كيف" - المنهجية التقنية وقرارات البنية التحتية
tasks.md	قائمة مهام التنفيذ مع مربعات الاختيار

المصنفات تبني على بعضها البعض:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            تحديث أثناء التعلم

يمكنك دائمًا العودة وتحسين المصنفات السابقة كلما اكتسبت مزيدًا من المعرفة أثناء التنفيذ.

كيف تعمل مواصفات التغيير

مواصفات التغيير هي المفهوم الأساسي في OpenSpec. تظهر ما يتغير بالنسبة لمواصفاتك الحالية.

الصيغة

تستخدم مواصفات التغيير أقسامًا لتحديد نوع التغيير:

# تغيير للمصادقة (Auth)

## متطلبات مُضافة

### المتطلب: المصادقة الثنائية
يجب على النظام أن يتطلب عاملًا ثانيًا أثناء تسجيل الدخول.

#### السيناريو: مطلوب OTP
- GIVEN مستخدم لديه المصادقة الثنائية مفعلة
- WHEN يقدم المستخدم بيانات اعتماد صالحة
- THEN تظهر مطالبة OTP

## متطلبات مُعدّلة

### المتطلب: انتهاء مهلة الجلسة
يجب على النظام أن تنتهي صلاحية الجلسات بعد 30 دقيقة من عدم النشاط.
(سابقًا: 60 دقيقة)

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

## متطلبات مُزالة

### المتطلب: تذكرني
(تم إهماله لصالح المصادقة الثنائية)

ما يحدث عند الأرشفة

عند أرشفة تغيير:

1. تُلحق المتطلبات المُضافة بالمواصفات الرئيسية
2. تحل المتطلبات المُعدّلة محل النسخة الحالية
3. تُحذف المتطلبات المُزالة من المواصفات الرئيسية

ينتقل مجلد التغيير إلى openspec/changes/archive/ للحفاظ على سجل التدقيق.

مثال: أول تغيير لك

لنمر عبر إضافة الوضع الداكن إلى تطبيق.

1. بدء التغيير (الافتراضي)

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

الذكاء الاصطناعي:  تم إنشاء openspec/changes/add-dark-mode/
     ✓ proposal.md — لماذا نفعل هذا، ماذا يتغير
     ✓ specs/       — المتطلبات والسيناريوهات
     ✓ design.md    — المنهجية التقنية
     ✓ tasks.md     — قائمة مهام التنفيذ
     جاهز للتنفيذ!

إذا قمت بتفعيل ملف سير العمل الموسع، يمكنك أيضًا القيام بذلك على خطوتين: /opsx:new ثم /opsx:ff (أو /opsx:continue بشكل تدريجي).

2. ما يتم إنشاؤه

proposal.md - يسجل النية:

# اقتراح: إضافة الوضع الداكن

## النية
طلب المستخدمون خيار الوضع الداكن لتقليل إجهاد العينين
أثناء الاستخدام الليلي.

## النطاق
- إضافة مفتاح تبديل السمة في الإعدادات
- دعم تفضيلات النظام
- حفظ التفضيل في localStorage

## المنهجية
استخدام خصائص CSS المخصصة للسمات مع سياق React
لإدارة الحالة.

specs/ui/spec.md - تغيير يظهر المتطلبات الجديدة:

# تغيير لواجهة المستخدم (UI)

## متطلبات مُضافة

### المتطلب: اختيار السمة
يجب على النظام أن يسمح للمستخدمين بالاختيار بين السمة الفاتحة والداكنة.

#### السيناريو: التبديل اليدوي
- GIVEN مستخدم على أي صفحة
- WHEN ينقر المستخدم على مفتاح تبديل السمة
- THEN تتحول السمة فورًا
- AND يبقى التفضيل عبر الجلسات

#### السيناريو: تفضيل النظام
- GIVEN مستخدم بدون تفضيل محفوظ
- WHEN يتم تحميل التطبيق
- THEN يُستخدم نظام الألوان المفضل للنظام

tasks.md - قائمة مهام التنفيذ:

# المهام

## 1. البنية التحتية للسمة
- [ ] 1.1 إنشاء ThemeContext مع حالة فاتح/داكن
- [ ] 1.2 إضافة خصائص CSS مخصصة للألوان
- [ ] 1.3 تنفيذ الاستمرارية في localStorage

## 2. مكونات واجهة المستخدم
- [ ] 2.1 إنشاء مكون ThemeToggle
- [ ] 2.2 إضافة مفتاح التبديل إلى صفحة الإعدادات
- [ ] 2.3 تحديث Header لتضمين مفتاح تبديل سريع

## 3. التنسيق
- [ ] 3.1 تحديد لوحة ألوان السمة الداكنة
- [ ] 3.2 تحديث المكونات لاستخدام متغيرات CSS

3. التنفيذ

أنت: /opsx:apply

الذكاء الاصطناعي:  العمل على المهام...
     ✓ 1.1 تم إنشاء ThemeContext مع حالة فاتح/داكن
     ✓ 1.2 تمت إضافة خصائص CSS مخصصة إلى globals.css
     ✓ 1.3 تم تنفيذ الاستمرارية في localStorage
     ✓ 2.1 تم إنشاء مكون ThemeToggle
     ...
     اكتملت جميع المهام!

أثناء التنفيذ، إذا اكتشفت أن التصميم يحتاج إلى تعديل، قم بتحديث المصنف والمتابعة.

4. الأرشفة

أنت: /opsx:archive

الذكاء الاصطناعي:  أرشفة add-dark-mode...
     ✓ تم دمج المواصفات في openspec/specs/ui/spec.md
     ✓ تم النقل إلى openspec/changes/archive/2025-01-24-add-dark-mode/
     تم! جاهز للميزة التالية.

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

المراجعة والتحقق

استخدم واجهة سطر الأوامر للتحقق من تغييراتك:

# قائمة التغييرات النشطة
openspec list

# عرض تفاصيل التغيير
openspec show add-dark-mode

# التحقق من صحة تنسيق المواصفات
openspec validate add-dark-mode

# لوحة معلومات تفاعلية
openspec view

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

• سير العمل - الأنماط الشائعة ومتى تستخدم كل أمر
• الأوامر - المرجع الكامل لجميع أوامر الشرطة المائلة
• المفاهيم - فهم أعمق للمواصفات والتغييرات والمخططات
• التخصيص - اجعل OpenSpec يعمل بالطريقة التي تناسبك