مسرد المصطلحات

كل مصطلح من OpenSpec في مكان واحد، ومُعرَّف بلغة واضحة. ألقِ نظرة سريعة عليه وستقرأ بقية الوثائق بشكل أسرع.

يتم تجميع المصطلحات حسب الموضوع، ثم ترتيبها أبجديًا داخل كل مجموعة.

الأسماء الأساسية (The core nouns)

Spec. وثيقة تصف كيفية عمل جزء من نظامك. توجد الـ Specs في openspec/specs/، وهي منظمة حسب المجال ومكونة من متطلبات وسيناريوهات. الـ Spec هو الإجابة المتفق عليها على سؤال "ماذا يفعل هذا البرنامج؟" انظر المفاهيم.

Source of truth. مجلد openspec/specs/ بأكمله. إنه يحمل السلوك الحالي والمتفق عليه لنظامك. التغييرات تقترح تعديلات عليه؛ والتأرشف يطبقها.

Change. وحدة عمل واحدة، يتم تغليفها كمجلد تحت openspec/changes/<name>/. يحتوي الـ Change على كل شيء يتعلق بهذا العمل: اقتراحه وتصميمه ومهامه والتعديلات التي يُدخلها على الـ spec. تغيير واحد يعني ميزة أو إصلاح واحد.

Artifact. وثيقة داخل الـ change. المصادر القياسية للوثائق هي الاقتراح (proposal)، والـ delta specs، والتصميم (design)، والمهام (tasks). يتم إنشاؤها بترتيب التبعية وتغذي بعضها البعض.

Delta spec. هو spec موجود داخل الـ change ويصف فقط ما يتغير، باستخدام أقسام ADDED وMODIFIED وREMOVED، بدلاً من إعادة كتابة الـ spec بالكامل. هذا ما يسمح لـ OpenSpec بتعديل الأنظمة الموجودة بشكل نظيف. انظر المفاهيم.

Domain. مجموعة منطقية للـ specs، مثل auth/ أو payments/ أو ui/. أنت من يختار المجالات التي تتناسب طريقة تفكيرك في نظامك.

داخل الـ spec

Requirement. سلوك واحد يجب أن يتوفر للنظام، ويُكتب عادةً باستخدام كلمة مفتاحية من RFC 2119: "يجب على النظام انتهاء الجلسات بعد 30 دقيقة". المتطلبات تحدد ماذا وليس كيف.

Scenario. مثال ملموس وقابل للاختبار لمتطلب قيد التنفيذ، وعادةً ما يكون في شكل Given/When/Then. تجعل السيناريوهات المتطلب قابلاً للتحقق: يمكنك كتابة اختبار آلي منه.

RFC 2119 keywords. الكلمات MUST وSHALL وSHOULD وMAY، والتي تحمل معنى موحدًا حول مدى صرامة المتطلب. MUST وSHALL مطلقان. SHOULD هو توصية مع مجال للاستثناءات. MAY اختياري. يأتي الاسم من وثيقة المعايير للإنترنت التي عرّفتها.

المصادر (The artifacts)

Proposal (proposal.md). يمثل لماذا وماذا التغيير: نيته ونطاقه والنهج عالي المستوى. هو أول مصدر تقوم بإنشائه.

Design (design.md). يمثل كيف: النهج التقني وقرارات البنية المعمارية والملفات التي تتوقع لمسها. اختياري للتغييرات البسيطة.

Tasks (tasks.md). قائمة مراجعة التنفيذ، مع مربعات اختيار. يقوم الذكاء الاصطناعي بالعمل عليها أثناء /opsx:apply ويشطب العناصر أثناء العمل.

دورة الحياة (The lifecycle)

Archive. فعل إنهاء التغيير. يتم دمج الـ delta specs الخاصة به في الـ specs الرئيسية، وينتقل مجلد التغيير إلى openspec/changes/archive/YYYY-MM-DD-<name>/. بعد الأرشفة، تصف الـ specs الجديدة الواقع الجديد. انظر المفاهيم.

Sync. دمج الـ delta specs الخاصة بالتغيير في الـ specs الرئيسية دون أرشفة التغيير. عادةً ما يكون تلقائيًا (يقدم الأرشيف فرصة للقيام بذلك)، ولكنه متاح بشكل مستقل عبر /opsx:sync للتغييرات طويلة الأمد. انظر الأوامر.

سير العمل والأوامر (Workflow and commands)

OPSX. هو سير عمل OpenSpec القياسي الحالي، والمبني حول إجراءات مرنة بدلاً من مراحل جامدة. جميع أوامره التي تبدأ بـ /opsx:. انظر سير عمل OPSX.

Slash command. أمر تكتبه في محادثة مساعد الذكاء الاصطناعي الخاص بك، مثل /opsx:propose. الأوامر ذات الشرطة المائلة تقود سير العمل. إنها ليست أوامر طرفية (terminal commands). انظر كيف تعمل الأوامر.

Explore (/opsx:explore). أمر الشريك المفكر. يقرأ قاعدة الكود الخاصة بك، ويقارن الخيارات، ويوضح فكرة غامضة إلى خطة ملموسة، دون إنشاء أي مصادر أو كتابة أي كود. هي نقطة البداية الموصى بها كلما كانت لديك مشكلة ولكن لم تكن لديك خطة بعد. انظر استكشاف أولاً.

CLI. برنامج openspec الذي تشغله في الطرفية (terminal). يقوم بإعداد المشاريع، وإدراج وتصديق التغييرات، وفتح لوحة التحكم، والأرشفة. هو الجزء الخاص بالطرفية من OpenSpec. انظر CLI.

Skill. مجلد من التعليمات (.../skills/openspec-*/SKILL.md) يكتشف مساعد الذكاء الاصطناعي تلقائيًا ويتبعها. الـ Skills هي المعيار الناشئ عبر الأدوات لتوصيل سير عمل OpenSpec إلى المساعد الخاص بك.

Command file. ملف أمر ذي شرطة مائلة خاص بأداة معينة (.../commands/opsx-*). هو آلية التوصيل الأقدم، ولا يزال مدعومًا جنبًا إلى جنب مع الـ skills. نادرًا ما تحتاج إلى التعامل معها مباشرةً.

Profile. مجموعة أوامر الشرطة المائلة المثبتة في مشروعك. Core (الافتراضي) هي propose وexplore وapply وsync وarchive. المجموعة الموسعة (expanded) تضيف new وcontinue وff وverify وbulk-archive وonboard. قم بتغييره باستخدام openspec config profile.

Delivery. ما إذا كان OpenSpec يقوم بتثبيت الـ skills أو ملفات الأوامر، أو كليهما لأدواتك. يتم تكوينه عالميًا ويتم تطبيقه باستخدام openspec update.

التخصيص (Customization)

Schema. تعريف المصادر التي يمتلكها سير العمل وكيف تعتمد على بعضها البعض. الإعداد الافتراضي المدمج هو spec-driven (اقتراح ← specs ← تصميم ← مهام). يمكنك اشتقاقه أو كتابة الخاص بك. انظر التخصيص.

Template. ملف Markdown داخل الـ schema يشكل ما يولده الذكاء الاصطناعي لمصدر معين. تغيير القالب يغير مخرجات الذكاء الاصطناعي على الفور، دون الحاجة إلى إعادة بناء.

Project config (openspec/config.yaml). إعدادات خاصة بالمشروع: الـ schema الافتراضي، وcontext: الذي يتم حقنه في كل طلب تخطيط، وrules: الخاصة بكل مصدر. هي أسهل طريقة لتعليم OpenSpec حول حزمتك والاصطلاحات المتبعة. انظر التخصيص.

Context injection. وضع خلفية المشروع في حقل context: الخاص بـ config.yaml بحيث يتم إضافته تلقائيًا إلى كل مصدر يولده الذكاء الاصطناعي. هذا أكثر موثوقية من الأمل في أن يقرأ الذكاء الاصطناعي ملفًا منفصلاً.

Dependency graph. الرسم البياني الموجه الذي تتكون منه علاقات requires: بين المصادر. إنه رسم بياني غير دوري موجه (DAG: الأسهم تشير إلى الأمامد فقط، ولا تعود أبدًا)، ويستخدمه OpenSpec لمعرفة ما يمكنك إنشائه تاليًا.

Enablers, not gates. المبدأ القائل بأن تبعيات المصادر تُظهر ما يصبح ممكنًا تالياً، وليس ما هو مطلوب تالياً. يمكنك مراجعة وتعديل أي مصدر في أي وقت. انظر المفاهيم الأساسية بنظرة عامة.

التنسيق عبر المستودعات (beta)

تنطبق هذه المصطلحات فقط إذا كان تخطيطك يمتد على أكثر من مستودع واحد. إنها في مرحلة تجريبية (beta). يمكن للمستخدمين معظمهم تجاهلها. انظر الدليل للمخازن.

Store. مستودع مستقل مهمته الوحيدة هي التخطيط. يمتلك نفس شكل openspec/ الذي تعرفه بالفعل (specs وchanges) بالإضافة إلى ملف هوية صغير. تسجله على جهازك مرة واحدة، بالاسم، ومن ثم يمكن لأي أمر من OpenSpec العمل فيه من أي مكان.

Reference. إعلان، في ملف openspec/config.yaml الخاص بمستودع الكود، لمخزن يعتمد عليه هذا المستودع. المراجع للقراءة فقط: يحتفظ المستودع بأصله، ويحصل على openspec instructions فهرس لمصادر المخزن المشار إليه، وكل منها مع الأمر الدقيق لجلبها.

Working context. ما يقوم openspec context بتجميعه للمستودع الحالي: جذر OpenSpec الخاص به بالإضافة إلى كل مخزن يشير إليه، وكيفية جلب كل منهما. الإجابة على سؤال "مع ماذا أعمل؟"

Workset. مجموعة شخصية من المجلدات المحلية التي تفتحها معًا (مخزن بجانب مستودعات الكود التي تعمل عليها). يتم إنشاؤه صراحةً باستخدام openspec workset create؛ ولا شيء من تلك المسارات المحلية يُلتزم به في المستودع المشترك للتخطيط.

انظر أيضًا

• المفاهيم الأساسية بنظرة عامة: الأفكار الخمسة، في صفحة واحدة
• المفاهيم: الشرح المفصل
• كيف تعمل الأوامر: أوامر الشرطة المائلة مقابل CLI