المفاهيم
يوضح هذا الدليل الأفكار الأساسية وراء OpenSpec وكيف تتكامل معًا. للاستخدام العملي، راجع البدء و سير العمليات.
الفلسفة
تم بناء OpenSpec على أربعة مبادئ:
fluid not rigid — لا توجد بوابات مراحل، اعمل على ما يبدو منطقيًا
iterative not waterfall — تعلم أثناء البناء، وقم بالتحسين المستمر
easy not complex — إعداد خفيف الوزن، واحتفالات بسيطة
brownfield-first — يعمل مع قواعد الأكواد الموجودة، وليس فقط الأنظمة الجديدة كليًالماذا هذه المبادئ مهمة
مرن وليس جامدًا. أنظمة المواصفات التقليدية تقيدك بمراحل محددة: أولاً تخطط، ثم تنفذ، ثم تنهي. OpenSpec أكثر مرونة — يمكنك إنشاء artifacts بأي ترتيب منطقي لعملك.
تكراري وليس شلاليًا. تتغير المتطلبات. ويتعمق الفهم. ما بدا وكأنه نهج جيد في البداية قد لا يصمد بعد رؤية codebase. OpenSpec يتقبل هذه الحقيقة.
سهل وليس معقدًا. تتطلب بعض أُطر عمل المواصفات إعدادًا مكثفًا، أو تنسيقات جامدة، أو عمليات ثقيلة. OpenSpec لا يعيق عملك. ابدأ التهيئة في ثوانٍ، وابدأ العمل فورًا، وقم بالتخصيص فقط إذا لزم الأمر.
أولاً في البيئات القائمة (Brownfield-first). معظم عمل البرمجيات ليس بناءً من الصفر — بل تعديل الأنظمة الموجودة. يجعل نهج OpenSpec المعتمد على التغييرات (delta-based) من السهل تحديد التغييرات التي تطرأ على السلوك الحالي، وليس مجرد وصف أنظمة جديدة.
نظرة عامة
تنظم OpenSpec عملك في مجالين رئيسيين:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ مصدر الحقيقة │◄─────│ تعديلات مقترحة │ │
│ │ كيف يعمل نظامك │ │ كل تغيير = مجلد │ │
│ │ حالياً │ │ يحتوي على المخرجات و Deltas │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘المواصفات (Specs) هي مصدر الحقيقة — فهي تصف كيف يعمل نظامك حاليًا.
التغييرات (Changes) هي تعديلات مقترحة — وهي موجودة في مجلدات منفصلة حتى تكون مستعدًا لدمجها.
هذا الفصل أمر أساسي. يمكنك العمل على عدة تغييرات بالتوازي دون حدوث تعارضات. يمكنك مراجعة التغيير قبل أن يؤثر على المواصفات الرئيسية. وعندما تُؤرشف تغيير، فإن دلتا (deltas) الخاصة به تندمج بسلاسة في مصدر الحقيقة.
المواصفات (Specs)
تصف المواصفات سلوك نظامك باستخدام متطلبات وسيناريوهات منظمة.
الهيكل
openspec/specs/
├── auth/
│ └── spec.md # سلوك المصادقة
├── payments/
│ └── spec.md # معالجة المدفوعات
├── notifications/
│ └── spec.md # نظام الإشعارات
└── ui/
└── spec.md # سلوك واجهة المستخدم والمظاهر (Themes)نظم المواصفات حسب المجال — وهي مجموعات منطقية ذات معنى لنظامك. الأنماط الشائعة:
- حسب مجال الميزة:
auth/،payments/،search/ - حسب المكون:
api/،frontend/،workers/ - حسب السياق المحدد (Bounded Context):
ordering/،fulfillment/،inventory/
صيغة المواصفات
يحتوي المتطلب على متطلبات، وكل متطلب يحتوي على سيناريوهات:
markdown
# مواصفات المصادقة (Auth Specification)
## الغرض (Purpose)
إدارة المصادقة والجلسة للتطبيق.
## المتطلبات (Requirements)
### المتطلب: مصادقة المستخدم
يجب على النظام إصدار رمز JWT عند تسجيل الدخول بنجاح.
#### السيناريو: بيانات اعتماد صالحة
- بالنظر إلى مستخدم لديه بيانات اعتماد صالحة
- عندما يقدم المستخدم نموذج تسجيل الدخول
- إذن يتم إرجاع رمز JWT
- و يتم توجيه المستخدم إلى لوحة التحكم
#### السيناريو: بيانات اعتماد غير صالحة
- بالنظر إلى بيانات اعتماد غير صالحة
- عندما يقدم المستخدم نموذج تسجيل الدخول
- إذن يتم عرض رسالة خطأ
- ولا يتم إصدار أي رمز
### المتطلب: انتهاء صلاحية الجلسة
يجب على النظام إنهاء الجلسات بعد 30 دقيقة من عدم النشاط.
#### السيناريو: مهلة الخمول (Idle timeout)
- بالنظر إلى جلسة مصادقة
- عندما تمر 30 دقيقة دون نشاط
- إذن يتم إلغاء صلاحية الجلسة
- ويجب على المستخدم إعادة المصادقةالعناصر الرئيسية:
| العنصر | الغرض |
|---|---|
## Purpose | وصف عالي المستوى لمجال هذه المواصفات |
### Requirement: | سلوك محدد يجب أن يتوفر للنظام |
#### Scenario: | مثال ملموس للمتطلب قيد التنفيذ |
| SHALL/MUST/SHOULD | كلمات مفتاحية من RFC 2119 تشير إلى قوة المتطلب |
لماذا هيكلة المواصفات بهذه الطريقة
المتطلبات هي "ماذا" (the what) — فهي تحدد ما يجب أن يفعله النظام دون تحديد التنفيذ.
السيناريوهات هي "متى" (the when) — فهي توفر أمثلة ملموسة يمكن التحقق منها. السيناريوهات الجيدة:
- قابلة للاختبار (يمكنك كتابة اختبار آلي لها)
- تغطي المسار السعيد وحالات الحافة (edge cases)
- تستخدم صيغة منظمة مثل Given/When/Then
الكلمات المفتاحية RFC 2119 (SHALL, MUST, SHOULD, MAY) تنقل القصد:
- MUST/SHALL — متطلب مطلق
- SHOULD — موصى به، ولكن هناك استثناءات
- MAY — اختياري
ما هي المواصفة (Spec) وما ليست عليه
المواصفة هي عقد سلوكي، وليست خطة تنفيذ.
محتوى جيد للمواصفة:
- السلوك القابل للملاحظة الذي يعتمد عليه المستخدمون أو الأنظمة الأخرى.
- المدخلات والمخرجات وحالات الخطأ.
- القيود الخارجية (الأمان، والخصوصية، والموثوقية، والتوافق).
- السيناريوهات التي يمكن اختبارها أو التحقق منها بشكل صريح.
تجنب في المواصفات:
- أسماء الفئات/الدوال الداخلية.
- اختيارات المكتبة أو الإطار (Framework).
- تفاصيل التنفيذ خطوة بخطوة.
- خطط التنفيذ المفصلة (هذه تنتمي إلى
design.mdأوtasks.md).
اختبار سريع:
- إذا كان يمكن تغيير التنفيذ دون تغيير السلوك المرئي خارجيًا، فمن المحتمل أنه لا ينبغي أن يكون موجودًا في المواصفات.
اجعلها خفيفة: الصرامة التدريجية (Progressive Rigor)
تهدف OpenSpec إلى تجنب البيروقراطية. استخدم أدنى مستوى يجعل التغيير قابلاً للتحقق منه.
المواصفة الخفيفة (Lite spec - الافتراضي):
- متطلبات قصيرة تركز على السلوك.
- نطاق واضح وأهداف غير مرغوبة (non-goals).
- عدد قليل من فحوصات القبول الملموسة.
المواصفة الكاملة (Full spec - للمخاطر الأعلى):
- تغييرات عبر الفرق أو المستودعات.
- تغييرات واجهة برمجة التطبيقات/العقد، وعمليات الترحيل، ومخاوف الأمان/الخصوصية.
- التغييرات التي من المحتمل أن يؤدي الغموض فيها إلى إعادة عمل مكلفة.
يجب أن تبقى معظم التغييرات في الوضع الخفيف (Lite mode).
التعاون بين الإنسان والوكلاء (Agent)
في العديد من الفرق، يستكشف البشر ويصوغ الوكلاء المخرجات. الحلقة المقصودة هي:
- يقدم الإنسان النية والسياق والقيود.
- يحول الوكيل هذا إلى متطلبات وسيناريوهات تركز على السلوك.
- يحتفظ الوكيل بتفاصيل التنفيذ في
design.mdوtasks.md، وليس فيspec.md. - يؤكد التحقق الهيكل والوضوح قبل التنفيذ.
هذا يحافظ على المواصفات قابلة للقراءة للبشر ومتسقة للوكلاء.
التغييرات (Changes)
التغيير هو تعديل مقترح لنظامك، ويتم تغليفه كمجلد يحتوي على كل ما يلزم لفهمة وتنفيذه.
هيكل التغيير
openspec/changes/add-dark-mode/
├── proposal.md # لماذا وماذا
├── design.md # كيف (النهج التقني)
├── tasks.md # قائمة مراجعة التنفيذ
├── .openspec.yaml # بيانات وصف التغيير (اختياري)
└── specs/ # مواصفات التغيير (Delta specs)
└── ui/
└── spec.md # ما الذي يتغير في ui/spec.mdكل تغيير مكتفٍ بذاته. ويحتوي على:
- المخرجات (Artifacts) — المستندات التي تلتقط النية والتصميم والمهام.
- مواصفات التغيير (Delta specs) — المواصفات لما يتم إضافته أو تعديله أو حذفه.
- البيانات الوصفية (Metadata) — تكوين اختياري لهذا التغيير المحدد.
لماذا التغييرات هي مجلدات
إن تغليف التغيير كمجلد له عدة مزايا:
كل شيء معًا. المقترح والتصميم والمهام والمواصفات موجودة في مكان واحد. لا حاجة للبحث عبر مواقع مختلفة.
العمل المتوازي. يمكن أن توجد تغييرات متعددة في نفس الوقت دون تعارض. اعمل على
add-dark-modeبينماfix-auth-bugقيد التنفيذ أيضًا.تاريخ نظيف. عند الأرشفة، تنتقل التغييرات إلى
changes/archive/مع الحفاظ على سياقها الكامل. يمكنك النظر إلى الوراء وفهم ليس فقط ما الذي تغير، ولكن لماذا.سهولة المراجعة. مجلد التغيير سهل للمراجعة — افتحه، واقرأ المقترح، وتحقق من التصميم، وانظر إلى دلتا المواصفات.
المخرجات (Artifacts)
المخرجات هي المستندات الموجودة داخل التغيير والتي توجه العمل.
تدفق المخرجات
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
لماذا ماذا كيف الخطوات
+ النطاق التغييرات النهج الشيء الواجب القيام بهتبني المخرجات على بعضها البعض. كل مخرج يوفر سياقًا للمخرج التالي.
أنواع المخرجات
المقترح (proposal.md)
يلتقط المقترح النية والنطاق والنهج بمستوى عالٍ.
markdown
# مقترح: إضافة الوضع الداكن (Add Dark Mode)
## النية (Intent)
طلب المستخدمين خيار الوضع الداكن لتخفيف إجهاد العين أثناء الاستخدام الليلي ومطابقة تفضيلات النظام.
## النطاق (Scope)
ضمن النطاق:
- تبديل المظهر في الإعدادات
- اكتشاف تفضيلات النظام
- الاحتفاظ بالتفضيل في localStorage
خارج النطاق:
- سمات الألوان المخصصة (عمل مستقبلي)
- تجاوزات السمات لكل صفحة
## النهج (Approach)
استخدام خصائص CSS المخصصة للمظهر مع سياق React لإدارة الحالة. اكتشاف تفضيل النظام عند التحميل الأول، والسماح بالتجاوز اليدوي.متى يتم تحديث المقترح:
- تغييرات في النطاق (تضييق أو توسيع).
- توضيح النية (فهم أفضل للمشكلة).
- تحول جوهري في النهج.
المواصفات (Specs - دلتا specs في specs/)
تصف مواصفات التغيير ما الذي يتغير مقارنة بالمواصفات الحالية. انظر مواصفات التغيير أدناه.
التصميم (design.md)
يلتقط التصميم النهج التقني وقرارات البنية المعمارية.
markdown
# تصميم: إضافة الوضع الداكن (Add Dark Mode)
## النهج التقني
إدارة حالة المظهر عبر React Context لتجنب تمرير الخصائص (prop drilling). تتيح خصائص CSS المخصصة التبديل في وقت التشغيل دون تبديل الفئات.
## قرارات البنية المعمارية
### القرار: السياق بدلاً من Redux
استخدام React Context لحالة المظهر لأن:
- حالة ثنائية بسيطة (فاتح/داكن)
- لا توجد تحولات معقدة للحالة
- يتجنب إضافة تبعية Redux
### القرار: خصائص CSS المخصصة
استخدام متغيرات CSS بدلاً من CSS-in-JS لأنه:
- يعمل مع ملف التنسيق الحالي
- لا يوجد حمل إضافي في وقت التشغيل
- حل أصلي للمتصفح (Browser-native solution)
## تدفق البيانات
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## تغييرات الملفات
- `src/contexts/ThemeContext.tsx` (جديد)
- `src/components/ThemeToggle.tsx` (جديد)
- `src/styles/globals.css` (معدل)متى يتم تحديث التصميم:
- يكشف التنفيذ أن النهج لن ينجح.
- اكتشاف حل أفضل.
- تغيير التبعيات أو القيود.
المهام (tasks.md)
المهام هي قائمة مراجعة التنفيذ — خطوات ملموسة مع مربعات اختيار.
markdown
# المهام (Tasks)
## 1. البنية التحتية للمظهر
- [ ] 1.1 إنشاء ThemeContext بحالة فاتح/داكن
- [ ] 1.2 إضافة خصائص CSS المخصصة للألوان
- [ ] 1.3 تنفيذ الاحتفاظ بالبيانات في localStorage
- [ ] 1.4 إضافة اكتشاف تفضيلات النظام
## 2. مكونات واجهة المستخدم (UI Components)
- [ ] 2.1 إنشاء مكون ThemeToggle
- [ ] 2.2 إضافة التبديل إلى صفحة الإعدادات
- [ ] 2.3 تحديث الرأس (Header) لتضمين تبديل سريع
## 3. التنسيق (Styling)
- [ ] 3.1 تحديد لوحة ألوان المظهر الداكن
- [ ] 3.2 تحديث المكونات لاستخدام متغيرات CSS
- [ ] 3.3 اختبار نسب التباين لسهولة الوصول (accessibility)أفضل ممارسات المهام:
- تجميع المهام ذات الصلة تحت عناوين رئيسية.
- استخدام ترقيم هرمي (1.1، 1.2، إلخ).
- إبقاء المهام صغيرة بما يكفي لإكمالها في جلسة واحدة.
- وضع علامة على المهام المكتملة عند الانتهاء منها.
مواصفات التغيير (Delta Specs)
مواصفات التغيير هي المفهوم الأساسي الذي يجعل OpenSpec يعمل للتطوير المستمر (brownfield development). إنها تصف ما الذي يتغير بدلاً من إعادة سرد المواصفة بأكملها.
الصيغة
markdown
# دلتا المصادقة (Delta for Auth)
## المتطلبات المضافة (ADDED Requirements)
### المتطلب: مصادقة العاملين بمصادقة ثنائية (Two-Factor Authentication)
يجب على النظام دعم المصادقة الثنائية القائمة على TOTP.
#### السيناريو: تسجيل العاملين بمصادقة ثنائية
- بالنظر إلى مستخدم بدون تفعيل 2FA
- عندما يقوم المستخدم بتفعيل 2FA في الإعدادات
- إذن يتم عرض رمز QR لتطبيق المصادق (authenticator app) للإعداد
- ويجب على المستخدم التحقق برمز قبل التنشيط
#### السيناريو: تسجيل الدخول باستخدام 2FA
- بالنظر إلى مستخدم مفعل لديه 2FA
- عندما يقدم المستخدم بيانات اعتماد صالحة
- إذن يتم تقديم تحدي OTP
- ولا يكتمل تسجيل الدخول إلا بعد رمز OTP صالح
## المتطلبات المعدلة (MODIFIED Requirements)
### المتطلب: انتهاء صلاحية الجلسة
يجب على النظام إنهاء الجلسات بعد 15 دقيقة من عدم النشاط.
(السابق: 30 دقيقة)
#### السيناريو: مهلة الخمول
- بالنظر إلى جلسة مصادقة
- عندما تمر 15 دقيقة دون نشاط
- إذن يتم إلغاء صلاحية الجلسة
## المتطلبات المحذوفة (REMOVED Requirements)
### المتطلب: تذكرني (Remember Me)
(تم استبداله بـ 2FA. يجب على المستخدمين إعادة المصادقة في كل جلسة.)أقسام الدلتا (Delta Sections)
| القسم | المعنى | ماذا يحدث عند الأرشفة |
|---|---|---|
## ADDED Requirements | سلوك جديد | يتم إلحاقه بالمواصفات الرئيسية |
## MODIFIED Requirements | سلوك متغير | يحل محل المتطلب الحالي |
## REMOVED Requirements | سلوك مهمل (Deprecated) | يُحذف من المواصفات الرئيسية |
لماذا الدلتا بدلاً من المواصفات الكاملة
الوضوح. توضح الدلتا بالضبط ما الذي يتغير. عند قراءة مواصفة كاملة، سيتعين عليك مقارنتها عقليًا بالنسخة الحالية.
تجنب التعارض. يمكن لتغييرين أن يلمسا نفس ملف المواصفات دون تعارض، طالما أنهما يعدلان متطلبات مختلفة.
كفاءة المراجعة. يرى المراجع التغيير، وليس السياق غير المتغير. التركيز على ما هو مهم.
الملاءمة للتطوير المستمر (Brownfield fit). معظم العمل يقوم بتعديل السلوك الحالي. تجعل الدلتا التعديلات من الدرجة الأولى، وليست فكرة لاحقة.
المخططات (Schemas)
تُعرّف المخططات أنواع العناصر (Artifacts) واعتمادياتها لسير العمل (workflow).
كيفية عمل المخططات
yaml
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # لا توجد تبعيات، يمكن إنشائه أولاً
- id: specs
generates: specs/**/*.md
requires: [proposal] # يحتاج إلى proposal قبل الإنشاء
- id: design
generates: design.md
requires: [proposal] # يمكن إنشاؤه بالتوازي مع specs
- id: tasks
generates: tasks.md
requires: [specs, design] # يحتاج إلى كل من specs و design أولاًتُشكّل العناصر (Artifacts) مخطط تبعيات:
proposal
(العقدة الجذرية)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(يحتاج إلى: (يحتاج إلى:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(يحتاج إلى:
specs, design)التبعيات هي عوامل تمكين، وليست حواجز. إنها تُظهر ما هو ممكن الإنشاء، وليس ما يجب عليك إنشائه تالياً. يمكنك تخطي التصميم (design) إذا لم تكن بحاجة إليه. يمكنك إنشاء specs قبل أو بعد التصميم — فكلاهما يعتمد فقط على proposal.
المخططات المُدمجة (Built-in Schemas)
spec-driven (افتراضي)
سير العمل القياسي للتطوير القائم على المواصفات:
proposal → specs → design → tasks → implementالأفضل لـ: معظم أعمال الميزات التي ترغب فيها في الاتفاق على المواصفات قبل التنفيذ.
المخططات المُخصصة (Custom Schemas)
قم بإنشاء مخططات مخصصة لسير عمل فريقك:
bash
# الإنشاء من الصفر
openspec schema init research-first
# أو استنساخ مخطط موجود
openspec schema fork spec-driven research-firstمثال لمخطط مُخصص:
yaml
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # قم بالبحث أولاً
- id: proposal
generates: proposal.md
requires: [research] # يتم إعداد Proposal بناءً على البحث
- id: tasks
generates: tasks.md
requires: [proposal] # تخطي specs/design، والانتقال مباشرة إلى المهام (tasks)راجع التخصيص للحصول على تفاصيل كاملة حول إنشاء واستخدام المخططات المُخصصة.
الأرشيف (Archive)
يكمل الأرشفة التغيير عن طريق دمج مواصفات التغيير (delta specs) في المواصفات الرئيسية والحفاظ على التغيير للسجل التاريخي.
ماذا يحدث عند الأرشفة؟
قبل الأرشفة:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ دُمج (merge)
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
بعد الأرشفة:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # يشمل الآن متطلبات 2FA
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # محفوظ للسجل التاريخي
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdعملية الأرشفة
دمج التغييرات (Merge deltas). يتم تطبيق كل قسم من مواصفات التغيير (ADDED/MODIFIED/REMOVED) على المواصفات الرئيسية المقابلة.
النقل إلى الأرشيف. تُنقل مجلد التغيير إلى
changes/archive/مع بادئة تاريخية لترتيب الأحداث زمنياً.الحفاظ على السياق. تظل جميع العناصر (Artifacts) سليمة في الأرشيف. يمكنك دائماً النظر إلى الوراء لفهم سبب إجراء التغيير.
لماذا الأرشفة مهمة؟
حالة نظيفة (Clean state). تُظهر التغييرات النشطة (changes/) العمل الجاري فقط. ينتقل العمل المكتمل خارج نطاق العرض.
مسار التدقيق (Audit trail). يحافظ الأرشيف على السياق الكامل لكل تغيير — ليس فقط ما تغير، ولكن الـ proposal الذي يوضح السبب، والتصميم (design) الذي يشرح الكيفية، والمهام (tasks) التي تظهر العمل المنجز.
تطور المواصفات. تنمو المواصفات بشكل عضوي مع أرشفة التغييرات. يقوم كل أرشيف بدمج تغييراته، مما يبني مواصفات شاملة بمرور الوقت.
كيف يتكامل كل شيء؟
┌──────────────────────────────────────────────────────────────────────────────┐
│ سير عمل OPENSPEC │
│ │
│ ┌────────────────┐ │
│ │ 1. البدء (START) │ /opsx:propose (core) or /opsx:new (expanded) │
│ │ التغيير │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. الإنشاء (CREATE) │ /opsx:ff or /opsx:continue (expanded workflow) │
│ │ العناصر │ ينشئ proposal → specs → design → tasks │
│ │ │ (بناءً على تبعيات المخطط - schema dependencies) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. التنفيذ (IMPLEMENT) │ /opsx:apply │
│ │ المهام │ العمل على المهام، ووضع علامة عليها عند إكمالها │
│ │ │◄──── تحديث العناصر أثناء التعلم │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. التحقق (VERIFY) │ /opsx:verify (اختياري) │
│ │ العمل │ فحص ما إذا كان التنفيذ يطابق المواصفات │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. الأرشفة (ARCHIVE) │────►│ تندمج مواصفات التغيير في المواصفات الرئيسية │ │
│ │ التغيير │ │ ينقل مجلد التغيير إلى archive/ │ │
│ └────────────────┘ │ المواصفات هي الآن المصدر الموثوق والمحدّث │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘الدورة الحميدة (The virtuous cycle):
- تصف المواصفات السلوك الحالي.
- تقترح التغييرات تعديلات (كمواصفات تغيير).
- يجعل التنفيذ التغييرات حقيقة.
- تقوم الأرشفة بدمج مواصفات التغيير في المواصفات الرئيسية.
- تصبح المواصفات الآن تصف السلوك الجديد.
- يبني التغيير التالي على المواصفات المحدّثة.
مسرد المصطلحات (Glossary)
| المصطلح | التعريف |
|---|---|
| Artifact | وثيقة داخل التغيير (proposal أو design أو tasks أو delta specs) |
| Archive | عملية إكمال التغيير ودمج مواصفات التغيير فيها في المواصفات الرئيسية |
| Change | تعديل مقترح للنظام، مُعبأ كمجلد يحتوي على العناصر (artifacts) |
| Delta spec | مواصفة تصف التغييرات (ADDED/MODIFIED/REMOVED) مقارنة بالمواصفات الحالية |
| Domain | مجموعة منطقية للمواصفات (مثل auth/ أو payments/) |
| Requirement | سلوك محدد يجب أن يتوفر للنظام |
| Scenario | مثال ملموس لمتطلب، عادةً بتنسيق Given/When/Then |
| Schema | تعريف لأنواع العناصر والتبعيات بينها |
| Spec | مواصفة تصف سلوك النظام، وتحتوي على المتطلبات و السيناريوهات |
| Source of truth | دليل openspec/specs/، الذي يحتوي على السلوك المتفق عليه حالياً |
الخطوات التالية (Next Steps)
- Getting Started - خطوات عملية للبدء
- Workflows - الأنماط الشائعة ومتى يجب استخدام كل منها
- Commands - مرجع كامل للأوامر
- Customization - إنشاء مخططات مخصصة وتكوين مشروعك