المفاهيم
تشرح هذه الدليل الأفكار الأساسية وراء OpenSpec وكيفية ارتباطها ببعضها البعض. للاستخدام العملي، راجع البدء السريع وسير العمل.
الفلسفة
يُبنى OpenSpec حول أربعة مبادئ:
fluid not rigid — no phase gates, work on what makes sense
iterative not waterfall — learn as you build, refine as you go
easy not complex — lightweight setup, minimal ceremony
brownfield-first — works with existing codebases, not just greenfieldلماذا تهم هذه المبادئ
مرن لا جامد. تقفل أنظمة المواصفات التقليدية عملك في مراحل محددة: تخطط أولاً، ثم تنفّذ، ثم تنتهي. أما OpenSpec فهو أكثر مرونة — يمكنك إنشاء المخرجات بأي ترتيب منطقي يناسب عملك.
تكراري لا شلالي. المتطلبات تتغيّر. الفهم يتعمّق. ما بدا كنهج جيد في البداية قد لا يصمد بعد أن ترى قاعدة الشيفرة. OpenSpec يتقبّل هذه الحقيقة.
سهل لا معقد. بعض أطر المواصفات تتطلب إعداداً مكثفاً أو صيغاً صارمة أو عمليات ثقيلة. OpenSpec لا يعيقك. يُهيّأ في ثوانٍ، تبدأ العمل فوراً، وتخصّصه فقط إذا احتجت إلى ذلك.
الأولوية للمشاريع القائمة. معظم العمل البرمجي لا يتعلق بالبناء من الصفر — بل بتعديل الأنظمة القائمة. النهج القائم على الفروق (delta-based) في OpenSpec يجعل من السهل تحديد التغييرات على السلوك الحالي، لا مجرد وصف أنظمة جديدة.
الصورة الكبيرة
ينظّم OpenSpec عملك في مجالين رئيسيين:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ مصدر الحقيقة │◄─────│ التعديلات المقترحة │ │
│ │ كيف يعمل نظامك │ merge│ كل تغيير = مجلد واحد │ │
│ │ حالياً │ │ يحتوي على مخرجات ودلتا │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘المواصفات (Specs) هي مصدر الحقيقة — فهي تصف كيف يتصرف نظامك حالياً.
التغييرات (Changes) هي تعديلات مقترحة — وهي موجودة في مجلدات منفصلة حتى تصبح جاهزاً لدمجها.
هذا الفصل أمر أساسي. يمكنك العمل على تغييرات متعددة بالتوازي دون تعارضات. يمكنك مراجعة تغيير قبل أن يؤثر على المواصفات الرئيسية. وعندما تؤرشف تغييراً، تُدمج دلتا الخاص به بسلاسة في مصدر الحقيقة.
المواصفات (Specs)
تصف المواصفات سلوك نظامك باستخدام متطلبات وسيناريوهات منظمة.
البنية
openspec/specs/
├── auth/
│ └── spec.md # سلوك المصادقة
├── payments/
│ └── spec.md # معالجة الدفعات
├── notifications/
│ └── spec.md # نظام الإشعارات
└── ui/
└── spec.md # سلوك واجهة المستخدم والسماتنظّم المواصفات حسب المجال — مجموعات منطقية تناسب نظامك. الأنماط الشائعة:
- حسب منطقة الميزة:
auth/،payments/،search/ - حسب المكوّن:
api/،frontend/،workers/ - حسب السياق المحدد:
ordering/،fulfillment/،inventory/
تنسيق المواصفة
تحتوي المواصفة على متطلبات، ولكل مطلب سيناريوهات:
# مواصفة المصادقة
## الغرض
إدارة المصادقة والجلسات للتطبيق.
## المتطلبات
### المطلب: مصادقة المستخدم
يجب على النظام إصدار رمز JWT عند تسجيل الدخول بنجاح.
#### السيناريو: بيانات اعتماد صحيحة
- GIVEN مستخدم ببيانات اعتماد صحيحة
- WHEN يرسل المستخدم نموذج تسجيل الدخول
- THEN يتم إرجاع رمز JWT
- AND يتم توجيه المستخدم إلى لوحة التحكم
#### السيناريو: بيانات اعتماد غير صحيحة
- GIVEN بيانات اعتماد غير صحيحة
- WHEN يرسل المستخدم نموذج تسجيل الدخول
- THEN يتم عرض رسالة خطأ
- AND لا يتم إصدار أي رمز
### المطلب: انتهاء الجلسة
يجب على النظام إنهاء الجلسات بعد 30 دقيقة من عدم النشاط.
#### السيناريو: انتهاء المهلة بسبب الخمول
- GIVEN جلسة مصادق عليها
- WHEN يمر 30 دقيقة دون نشاط
- THEN يتم إبطال الجلسة
- AND يجب على المستخدم إعادة المصادقةالعناصر الأساسية:
| العنصر | الغرض |
|---|---|
## الغرض | وصف عالي المستوى لمجال هذه المواصفة |
### المطلب: | سلوك محدد يجب أن يمتلكه النظام |
#### السيناريو: | مثال ملموس للمطلب قيد التنفيذ |
| SHALL/MUST/SHOULD | كلمات RFC 2119 الأساسية التي تشير إلى قوة المطلب |
لماذا هيكلة المواصفات بهذه الطريقة
المتطلبات هي "ماذا" — فهي توضح ما يجب أن يفعله النظام دون تحديد التنفيذ.
السيناريوهات هي "متى" — فهي توفر أمثلة ملموسة يمكن التحقق منها. السيناريوهات الجيدة:
- قابلة للاختبار (يمكنك كتابة اختبار آلي لها)
- تغطي المسار السعيد والحالات الحدودية
- تستخدم صيغة Given/When/Then أو صيغة منظمة مشابهة
كلمات RFC 2119 الأساسية (SHALL، MUST، SHOULD، MAY) تنقل القصد:
- MUST/SHALL — مطلب مطلق
- SHOULD — موصى به، لكن توجد استثناءات
- MAY — اختياري
ما هي المواصفة (وما ليست كذلك)
المواصفة هي عقد سلوك، وليست خطة تنفيذ.
محتوى المواصفة الجيد:
- سلوك قابل للملاحظة يعتمد عليه المستخدمون أو الأنظمة اللاحقة
- المدخلات والمخرجات وحالات الخطأ
- القيود الخارجية (الأمان، الخصوصية، الموثوقية، التوافق)
- سيناريوهات يمكن اختبارها أو التحقق منها صراحةً
تجنّب في المواصفات:
- أسماء الفئات/الدوال الداخلية
- اختيارات المكتبات أو الأطر
- تفاصيل التنفيذ خطوة بخطوة
- خطط التنفيذ المفصلة (تلك تخص
design.mdأوtasks.md)
اختبار سريع:
- إذا كان يمكن أن يتغير التنفيذ دون تغيير السلوك المرئي خارجياً، فمن المرجح أنه لا ينتمي إلى المواصفة.
إبقاؤها خفيفة: الدقة التدريجية
يهدف OpenSpec إلى تجنب البيروقراطية. استخدم أخف مستوى لا يزال يجعل التغيير قابلاً للتحقق.
مواصفة خفيفة (الافتراضي):
- متطلبات قصيرة تركز على السلوك أولاً
- نطاق واضح وغير أهداف
- بعض فحوصات القبول الملموسة
مواصفة كاملة (للمخاطر الأعلى):
- تغييرات عبر الفرق أو عبر المستودعات
- تغييرات API/العقود، الترحيلات، مخاوف الأمان/الخصوصية
- التغييرات التي من المرجح أن يسبب فيها الغموض إعادة عمل مكلفة
يجب أن تبقى معظم التغييرات في الوضع الخفيف.
التعاون بين الإنسان والوكيل
في العديد من الفرق، يستكشف البشر ويقوم الوكلاء بصياغة المخرجات. الحلقة المقصودة هي:
- يقدم الإنسان القصد والسياق والقيود.
- يحوّل الوكيل ذلك إلى متطلبات وسيناريوهات تركز على السلوك أولاً.
- يبقي الوكيل تفاصيل التنفيذ في
design.mdوtasks.md، وليس فيspec.md. - يؤكد التحقق من البنية والوضوح قبل التنفيذ.
هذا يحافظ على قابلية قراءة المواصفات للبشر واتساقها للوكلاء.
التغييرات (Changes)
التغيير هو تعديل مقترح على نظامك، معبأ في مجلد يحتوي على كل ما يلزم لفهمه وتنفيذه.
بنية التغيير
openspec/changes/add-dark-mode/
├── proposal.md # لماذا وماذا
├── design.md # كيف (النهج التقني)
├── tasks.md # قائمة تحقق التنفيذ
├── .openspec.yaml # بيانات وصفية للتغيير (اختياري): schema, created, skip_specs, retire_capabilities
└── specs/ # مواصفات الدلتا
└── ui/
└── spec.md # ما الذي يتغير في ui/spec.mdكل تغيير مكتفي بذاته. يحتوي على:
- المخرجات (Artifacts) — وثائق تلتقط القصد والتصميم والمهام
- مواصفات الدلتا (Delta specs) — مواصفات لما يتم إضافته أو تعديله أو إزالته
- البيانات الوصفية — إعدادات اختيارية لهذا التغيير المحدد
لماذا التغييرات هي مجلدات
تعبئة التغيير كمجلد لها عدة فوائد:
كل شيء معاً. الاقتراح والتصميم والمهام والمواصفات تعيش في مكان واحد. لا بحث في مواقع مختلفة.
عمل متوازٍ. يمكن أن توجد تغييرات متعددة في نفس الوقت دون تعارض. اعمل على
add-dark-modeبينماfix-auth-bugقيد التنفيذ أيضاً.تاريخ نظيف. عند الأرشفة، تنتقل التغييرات إلى
changes/archive/مع الحفاظ على سياقها الكامل. يمكنك النظر إلى الخلف وفهم ليس فقط ما تغير، ولكن لماذا.سهولة المراجعة. مجلد التغيير سهل المراجعة — افتحه واقرأ الاقتراح وتحقق من التصميم وشاهد دلتا المواصفات.
المخرجات (Artifacts)
المخرجات هي الوثائق داخل التغيير التي توجه العمل.
تدفق المخرجات
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
لماذا ماذا كيف خطوات
+ النطاق التغييرات النهج للتنفيذتبني المخرجات على بعضها البعض. كل مخرج يوفر سياقاً للمخرج التالي.
أنواع المخرجات
الاقتراح (proposal.md)
يلتقط الاقتراح القصد والنطاق والنهج على مستوى عالٍ.
# الاقتراح: إضافة الوضع الداكن
## القصد
طلب المستخدمون خيار الوضع الداكن لتقليل إجهاد العين
أثناء الاستخدام الليلي ومطابقة تفضيلات النظام.
## النطاق
ضمن النطاق:
- مفتاح السمة في الإعدادات
- اكتشاف تفضيل النظام
- حفظ التفضيل في localStorage
خارج النطاق:
- سمات الألوان المخصصة (عمل مستقبلي)
- تجاوزات السمة لكل صفحة
## النهج
استخدام خصائص CSS المخصصة للسمات مع React context
لإدارة الحالة. اكتشاف تفضيل النظام عند التحميل الأول،
والسماح بالتجاوز اليدوي.متى يتم تحديث الاقتراح:
- يتغير النطاق (تضييقاً أو توسيعاً)
- يتضح القصد (فهم أفضل للمشكلة)
- يتغير النهج جوهرياً
المواصفات (مواصفات الدلتا في specs/)
تصف مواصفات الدلتا ما الذي يتغير بالنسبة للمواصفات الحالية. انظر مواصفات الدلتا أدناه.
التصميم (design.md)
يلتقط التصميم النهج التقني وقرارات البنية.
# التصميم: إضافة الوضع الداكن
## النهج التقني
إدارة حالة السمة عبر React Context لتجنب prop drilling.
تمكن خصائص CSS المخصصة من التبديل أثناء التشغيل دون تبديل الفئات.
## قرارات البنية
### القرار: Context بدلاً من Redux
استخدام React Context لحالة السمة لأن:
- حالة ثنائية بسيطة (فاتح/داكن)
- لا انتقالات حالة معقدة
- تجنب إضافة تبعية Redux
### القرار: خصائص CSS المخصصة
استخدام متغيرات CSS بدلاً من CSS-in-JS لأن:
- تعمل مع ورقة الأنماط الحالية
- لا عبء وقت تشغيل
- حل أصلي من المتصفح
## تدفق البيانات
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## تغييرات الملفات
- `src/contexts/ThemeContext.tsx` (جديد)
- `src/components/ThemeToggle.tsx` (جديد)
- `src/styles/globals.css` (معدل)متى يتم تحديث التصميم:
- يكشف التنفيذ أن النهج لن يعمل
- اكتشاف حل أفضل
- تغير التبعيات أو القيود
المهام (tasks.md)
المهام هي قائمة تحقق التنفيذ — خطوات ملموسة مع مربعات اختيار.
# المهام
## 1. بنية السمة
- [ ] 1.1 إنشاء ThemeContext بحالة فاتح/داكن
- [ ] 1.2 إضافة خصائص CSS مخصصة للألوان
- [ ] 1.3 تنفيذ الحفظ في localStorage
- [ ] 1.4 إضافة اكتشاف تفضيل النظام
## 2. مكونات واجهة المستخدم
- [ ] 2.1 إنشاء مكوّن ThemeToggle
- [ ] 2.2 إضافة المفتاح إلى صفحة الإعدادات
- [ ] 2.3 تحديث الترويسة لتشمل مفتاحاً سريعاً
## 3. التنسيق
- [ ] 3.1 تحديد لوحة ألوان السمة الداكنة
- [ ] 3.2 تحديث المكونات لاستخدام متغيرات CSS
- [ ] 3.3 اختبار نسب التباين للوصوليةأفضل ممارسات المهام:
- جمّع المهام ذات الصلة تحت عناوين
- استخدم ترقيماً هرمياً (1.1، 1.2، إلخ)
- اجعل المهام صغيرة بما يكفي لإكمالها في جلسة واحدة
- علّم على المهام عند إكمالها
مواصفات الدلتا (Delta Specs)
مواصفات الدلتا هي المفهوم الأساسي الذي يجعل OpenSpec يعمل لتطوير البنى القائمة (brownfield). تصف ما الذي يتغير بدلاً من إعادة ذكر المواصفة بأكملها.
التنسيق
# دلتا للمصادقة
## المتطلبات المضافة ADDED
### المطلب: المصادقة الثنائية (2FA)
يجب على النظام دعم المصادقة الثنائية القائمة على TOTP.
#### السيناريو: تفعيل 2FA
- GIVEN مستخدم بدون تفعيل 2FA
- WHEN يقوم المستخدم بتفعيل 2FA في الإعدادات
- THEN يتم عرض رمز QR لإعداد تطبيق المصادقة
- AND يجب على المستخدم التحقق برمز قبل التفعيل
#### السيناريو: تسجيل الدخول بـ 2FA
- GIVEN مستخدم مع تفعيل 2FA
- WHEN يقدم المستخدم بيانات اعتماد صحيحة
- THEN يتم عرض تحدي OTP
- AND يكتمل تسجيل الدخول فقط بعد OTP صالح
## المتطلبات المعدلة MODIFIED
### المطلب: انتهاء الجلسة
يجب على النظام إنهاء الجلسات بعد 15 دقيقة من عدم النشاط.
(سابقاً: 30 دقيقة)
#### السيناريو: انتهاء المهلة بسبب الخمول
- GIVEN جلسة مصادق عليها
- WHEN يمر 15 دقيقة دون نشاط
- THEN يتم إبطال الجلسة
## المتطلبات المزالة REMOVED
### المطلب: تذكرني (Remember Me)
(أُلغي لصالح 2FA. يجب على المستخدمين إعادة المصادقة في كل جلسة.)أقسام الدلتا
| القسم | المعنى | ما يحدث عند الأرشفة |
|---|---|---|
## المتطلبات المضافة ADDED | سلوك جديد | يُلحق بالمواصفة الرئيسية |
## المتطلبات المعدلة MODIFIED | سلوك متغير | يستبدل المطلب الحالي |
## المتطلبات المزالة REMOVED | سلوك مُلغى | يُحذف من المواصفة الرئيسية؛ إزالة المطلب الأخير ينهي الإمكانية ويحذف ملف المواصفة عندما يعلن التغيير retire_capabilities: true |
## الغرض Purpose | الغرض من إمكانية جديدة كلياً | يغذي الغرض من المواصفة الرئيسية الجديدة التي يتم إنشاؤها؛ يُتجاهل عندما تكون المواصفة موجودة بالفعل |
لماذا الدلتا بدلاً من المواصفات الكاملة
الوضوح. تُظهر الدلتا بالضبط ما الذي يتغير. عند قراءة مواصفة كاملة، سيتعين عليك مقارنتها ذهنياً مع النسخة الحالية.
تجنب التعارض. يمكن لتغييرين لمس نفس ملف المواصفة دون تعارض، طالما أنهما يعدلان متطلبات مختلفة.
كفاءة المراجعة. يرى المراجعون التغيير، وليس السياق غير المتغير. التركيز على ما يهم.
ملاءمة البنى القائمة. معظم العمل يعدل سلوكاً موجوداً. تجعل الدلتا التعديلات عنصراً أساسياً، وليست فكرة لاحقة.
المخططات (Schemas)
تحدد المخططات أنواع العناصر الناتجة (Artifacts) والتبعيات الخاصة بها ضمن سير العمل.
كيف تعمل المخططات
# 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 مسبقاًتشكّل العناصر الناتجة رسم بيانيًا للتبعيات:
proposal
(العقدة الجذرية)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(يتطلب: (يتطلب:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(يتطلب:
specs, design)التبعيات هي عوامل تمكين وليست حواجز. فهي توضح ما هو ممكن إنشاؤه، وليس ما يجب عليك إنشاؤه بالضرورة في الخطوة التالية. يمكنك تخطي مرحلة التصميم إذا لم تكن بحاجة إليها. يمكنك إنشاء المواصفات (specs) قبل أو بعد التصميم — وكلاهما يعتمد فقط على الـ proposal.
المخططات المدمجة
spec-driven (الافتراضي)
سير العمل القياسي لتطوير قائم على المواصفات:
proposal → specs → design → tasks → implementالأفضل لـ: معظم أعمال الميزات حيث ترغب في الاتفاق على المواصفات قبل التنفيذ.
مخططات مخصصة
أنشئ مخططات مخصصة تناسب سير عمل فريقك:
# إنشاء من الصفر
openspec schema init research-first
# أو نسخ مخطط موجود
openspec schema fork spec-driven research-firstمثال لمخطط مخصص:
# 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، وانتقل مباشرة إلى المهامانظر إلى التخصيص للحصول على التفاصيل الكاملة حول إنشاء واستخدام المخططات المخصصة.
الأرشيف
يكمل الأرشفة التغيير من خلال دمج مواصفاته الجزئية (delta specs) في المواصفات الرئيسية والحفاظ على التغيير للأغراض التاريخية.
ماذا يحدث عند الأرشفة
قبل الأرشفة:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ دمج
├── 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عملية الأرشفة
دمج التغيرات الجزئية. يتم تطبيق كل قسم من أقسام المواصفة الجزئية (ADDED/MODIFIED/REMOVED) على المواصفة الرئيسية المقابلة.
النقل إلى الأرشيف. ينتقل مجلد التغيير إلى
changes/archive/مع بادئة تاريخية للترتيب الزمني.الحفاظ على السياق. تبقى جميع العناصر الناتجة سليمة في الأرشيف. يمكنك دائمًا الرجوع للخلف لفهم سبب إجراء التغيير.
لماذا تعتبر الأرشفة مهمة
حالة نظيفة. يُظهر التغييرات النشطة (changes/) العمل قيد التنفيذ فقط. الأعمال المكتملة تنتقل خارج المسار الرئيسي.
سجل التدقيق. يحفظ الأرشيف السياق الكامل لكل تغيير — ليس فقط ما تغير، بل أيضًا الـ proposal الذي يشرح السبب، والتصميم الذي يشرح الكيفية، والمهام التي تظهر العمل المنجز.
تطور المواصفات. تنمو المواصفات بشكل عضوي مع أرشفة التغييرات. يقوم كل أرشفة بدمج تغييراتها الجزئية، مما يبني مواصفة شاملة مع مرور الوقت.
كيف ينسجم كل شيء معًا
┌──────────────────────────────────────────────────────────────────────────────┐
│ تدفق OPENSPEC │
│ │
│ ┌────────────────┐ │
│ │ 1. ابدأ │ /opsx:propose (أساسي) أو /opsx:new (موسع) │
│ │ التغيير │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. أنشئ │ /opsx:ff أو /opsx:continue (سير عمل موسع) │
│ │ العناصر │ ينشئ proposal → specs → design → tasks │
│ │ │ (بناءً على تبعيات المخطط) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. نفّذ │ /opsx:apply │
│ │ المهام │ اعبر المهام، واضبطها كمنجزة │
│ │ │◄──── حدّث العناصر أثناء تعلمك │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. تحقق │ /opsx:verify (اختياري) │
│ │ العمل │ تأكد من مطابقة التنفيذ للمواصفات │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. أرشفة │────►│ دمج المواصفات الجزئية في المواصفات الرئيسية│ │
│ │ التغيير │ │ ينتقل مجلد التغيير إلى archive/ │ │
│ └────────────────┘ │ أصبحت المواصفات الآن المصدر الوحيد للحقيقة │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘الدورة الإيجابية:
- تصف المواصفات السلوك الحالي
- تقترح التغييرات تعديلات (على شكل تغييرات جزئية)
- يجعل التنفيذ هذه التغييرات حقيقة واقعة
- يدمج الأرشفة التغييرات الجزئية في المواصفات
- تصف المواصفات الآن السلوك الجديد
- يبني التغيير التالي على المواصفات المحدثة
مصطلحات
| المصطلح | التعريف |
|---|---|
| عنصر ناتج (Artifact) | وثيقة داخل تغيير معين (proposal، design، مهام، أو مواصفات جزئية) |
| أرشفة (Archive) | عملية إكمال تغيير ودمج تغييراته الجزئية في المواصفات الرئيسية |
| تغيير (Change) | تعديل مقترح للنظام، مُعبَّأ كمجلد يحتوي على عناصر ناتجة |
| مواصفة جزئية (Delta spec) | مواصفة تصف التغييرات (ADDED/MODIFIED/REMOVED) مقارنة بالمواصفات الحالية |
| نطاق (Domain) | مجموعة منطقية للمواصفات (مثل auth/، payments/) |
| متطلب (Requirement) | سلوك محدد يجب أن يتوفره النظام |
| سيناريو (Scenario) | مثال ملموس لمتطلب، عادةً بتنسيق Given/When/Then |
| مخطط (Schema) | تعريف لأنواع العناصر الناتجة وتبعياتها |
| مواصفة (Spec) | مواصفة تصف سلوك النظام، وتتضمن المتطلبات والسيناريوهات |
| المصدر الوحيد للحقيقة (Source of truth) | دليل openspec/specs/، والذي يحتوي على السلوك المتفق عليه حاليًا |