البدء في الاستخدام

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

أين أكتب هذه الأوامر؟ هناك مكانان، والخلط بينهما هو أكثر الأخطاء شيوعاً في البداية.

• أوامر openspec ... (مثل openspec init) تعمل في الطرفية (Terminal) الخاصة بك.
• أوامر /opsx:... (مثل /opsx:propose) تعمل في دردشة مساعد الذكاء الاصطناعي الخاصة بك، نفس المكان الذي تطلب منه فيه كتابة الكود.

لا يوجد "وضع تفاعلي" منفصل للبدء. ما عليك سوى كتابة الأمر المسبوق بشرطة مائلة في الدردشة وسيتولى مساعدك الأمر من هناك. شرح كامل: كيف تعمل الأوامر.

أول خمس دقائق لك

الحلقة الكاملة، مع تحديد كل خطوة بالمكان الذي تحدث فيه:

الطرفية   $ npm install -g @fission-ai/openspec@latest
الطرفية   $ cd your-project && openspec init
دردشة الذكاء الاصطناعي      /opsx:explore                    (اختياري: فكر في الأمر أولاً)
دردشة الذكاء الاصطناعي      /opsx:propose add-dark-mode      (الذكاء الاصطناعي يعد الخطة؛ أنت تراجعها)
دردشة الذكاء الاصطناعي      /opsx:apply                      (الذكاء الاصطناعي يبنيها)
دردشة الذكاء الاصطناعي      /opsx:archive                    (تم تحديث المواصفات، تم أرشفة التغيير)

خطوتان في الطرفية للإعداد، ثم تعمل في الدردشة. باقي هذا الدليل يشرح ما تفعله كل خطوة وما ستراه.

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

كيف يعمل

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

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

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (اختياري)

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

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

/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. وهي تُظهر ما يتم تغييره بالنسبة لمواصفاتك الحالية.

التنسيق

تستخدم مواصفات دلتا أقساماً للإشارة إلى نوع التغيير:

# دلتا للمصادقة

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

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

#### السيناريو: مطلوب كلمة مرور لمرة واحدة (OTP)
- نظراً لوجود مستخدم مع تفعيل المصادقة الثنائية (2FA)
- عندما يقدم المستخدم بيانات اعتماد صالحة
- عندئذ يتم تقديم تحدي كلمة مرور لمرة واحدة (OTP)

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

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

#### السيناريو: انتهاء صلاحية الخمول
- نظراً لوجود جلسة مصادقة
- عندما تمر 30 دقيقة بدون نشاط
- عندئذ يتم إلغاء صلاحية الجلسة

## متطلبات محذوفة

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

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

عندما تقوم بأرشفة تغيير:

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

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

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

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

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

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

الذكاء الاصطناعي:  Created 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 - دلتا تُظهر المتطلبات الجديدة:

# دلتا لواجهة المستخدم

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

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

#### السيناريو: التبديل اليدوي
- نظراً لوجود مستخدم في أي صفحة
- عندما ينقر المستخدم على مفتاح تبديل السمة
- عندئذ يتم تبديل السمة فوراً
- ويتم حفظ التفضيل عبر الجلسات

#### السيناريو: تفضيل النظام
- نظراً لوجود مستخدم بدون تفضيل محفوظ
- عندما يتم تحميل التطبيق
- عندئذ يتم استخدام مخطط الألوان المفضل للنظام

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

الذكاء الاصطناعي:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

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

4. الأرشفة

أنت: /opsx:archive

الذكاء الاصطناعي:  Archiving add-dark-mode...
     ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

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

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

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

# عرض التغييرات النشطة
openspec list

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

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

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

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

• استكشف أولاً - استخدم /opsx:explore للتفكير في فكرة قبل الالتزام بها
• مراجعة التغيير - ما الذي تتحقق منه في الخطة التي يعدها الذكاء الاصطناعي، قبل أي كود
• كتابة مواصفات جيدة - كيف يبدو المتطلب والسيناريو القويان
• استخدام OpenSpec في مشروع موجود - البدء في قاعدة كود كبيرة موجودة (brownfield)
• تحرير وتكرار التغيير - تحديث عناصر العمل، العودة، التوفيق بين التعديلات اليدوية
• المفاهيم الأساسية بلمحة - النموذج العقلي الكامل في صفحة واحدة
• أمثلة ووصفات - تغييرات حقيقية، من البداية إلى النهاية
• سير العمل - الأنماط الشائعة ومتى تستخدم كل أمر
• الأوامر - مرجع كامل لجميع الأوامر المسبوقة بشرطة مائلة
• المفاهيم - فهم أعمق للمواصفات والتغييرات والمخططات
• التخصيص - اجعل OpenSpec يعمل بطريقتك
• المخازن - هل تخطط لعمليات تمتد عبر مستودعات أو فرق؟ احفظها في مستودعها الخاص (بيتا)
• الأسئلة الشائعة و استكشاف الأخطاء وإصلاحها - عندما تواجه مشاكل