الأسئلة الشائعة (FAQ)

إجابات سريعة للأسئلة التي يطرحها الناس بشكل متكر. إذا كان سؤالك يتعلق بـ "شيء ما معطل"، فإن صفحة استكشاف الأخطاء هي الصفحة الأفضل. وإذا كنت ترغب في تعريف مصطلح، فراجع مسرد المصطلحات.

الأساسيات

ما هو OpenSpec، في جملة واحدة؟

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

لماذا قد أرغب في ذلك؟

لأن مساعدي الذكاء الاصطناعي واثق حتى عندما يكون مخطئًا. عندما تكون المتطلبات موجودة فقط في سلسلة محادثات (chat thread)، يملأ الذكاء الاصطناعي الفجوات بتخمينات، وتكتشف الأمر بعد وجود الكود. يقوم OpenSpec بتقديم هذا الاتفاق إلى وقت أبكر، حيث تكون الأخطاء رخيصة الإصلاح. راجع المفاهيم الأساسية بنظرة عامة للحصول على القصة الكاملة.

هل يجب علي استخدامه لكل شيء؟

لا. استخدمه حيث يكون الاتفاق مهمًا، وهو معظم الأعمال غير التافهة. بالنسبة لتصحيح خطأ مطبعي بحرف واحد، فمن المحتمل أن لا يستحق الأمر هذا الطقس، وهذا أمر جيد.

هل يمكنني استخدامه على قاعدة بيانات (codebase) موجودة وكبيرة، أم فقط للمشاريع الجديدة؟

قواعد البيانات الموجودة هي الحدث الرئيسي. OpenSpec مصمم للعمل في المشاريع القائمة أولاً (brownfield-first): أنت لا تقوم بتوثيق تطبيقك بالكامل مقدمًا. بل تكتب مواصفات (specs) لما يلمسه كل تغيير، وتتراكم هذه المواصفات مع مرور الوقت حول العمل الذي تقوم به بالفعل. يوجد دليل مخصص: استخدام OpenSpec في مشروع قائم.

هل هو مرتبط بأداة ذكاء اصطناعي واحدة؟

لا. يعمل OpenSpec مع أكثر من 25 مساعدًا، بما في ذلك Claude Code وCursor وWindsurf وGitHub Copilot وGemini CLI وCodex والمزيد. القائمة الكاملة وتفاصيل كل أداة موجودة في الأدوات المدعومة.

تشغيل الأوامر

أين أقوم بكتابة /opsx:propose؟

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

كيف "أبدأ الوضع التفاعلي"؟

لا يوجد وضع منفصل للبدء. أنت تفتح مساعد الذكاء الاصطناعي الخاص بك كالمعتاد وتكتب أمر شرطة (slash command) في محادثته. الأمر الشرطي هو الطريقة التي "تدخل" بها إلى OpenSpec. (الميزة التفاعلية الوحيدة حقًا في الطرفية هي openspec view، وهي لوحة تحكم لتصفح المواصفات والتغييرات). الشرح الكامل موجود في كيف تعمل الأوامر.

لقد كتبت أمر شرطة ولم يحدث شيء. لماذا؟

على الأرجح أنك كتبته في الطرفية بدلاً من محادثة الذكاء الاصطناعي، أو أن الأوامر لم يتم تثبيتها بعد. قم بتشغيل openspec update في مشروعك، وأعد تشغيل مساعدك، ثم حاول كتابة /opsx في المحادثة وراقب الإكمال التلقائي (autocomplete). يحتوي استكشاف الأخطاء على قائمة التحقق الكاملة.

لماذا الصيغة هي /opsx:propose في أداة وأخرى هي /opsx-propose؟

كل أداة ذكاء اصطناعي تعرض الأوامر المخصصة بطريقة مختلفة قليلاً. القصد هو نفسه؛ فقط علامات الترقيم تتغير. اكتب شرطة (slash) في محادثتك وسيعرض لك الإكمال التلقائي الشكل الذي تتوقعه أداتك. الجدول الخاص بكل أداة موجود في كيف تعمل الأوامر.

ما الفرق بين المهارة (skill) والأمر (command)؟

كلاهما ملفات يكتبها OpenSpec حتى يتمكن مساعدك من تشغيل سير العمل (workflow). المهارات (.../skills/openspec-*/SKILL.md) هي المعيار الأحدث المشترك بين الأدوات؛ والأوامر (.../commands/opsx-*) هي الملفات القديمة الخاصة بكل أداة. لست بحاجة للاختيار. أنت فقط تكتب الأمر الشرطي، ويقوم OpenSpec بتثبيت ما تستخدمه أداتك.

سير العمل (The Workflow)

من أين يجب أن أبدأ إذا لم أكن متأكدًا مما يجب بناؤه؟

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

ما هو أبسط تدفق ممكن؟

/opsx:explore (اختياري)   ثم   /opsx:propose <ما تريده>   ثم   /opsx:apply   ثم   /opsx:archive

استكشف للتفكير في الأمر، واقترح لصياغة الخطة، وطبق للبناء، وأرشف للملف. تخطى الاستكشاف إذا كنت تعرف بالضبط ما تريده.

ما الفرق بين /opsx:propose و/opsx:new؟

/opsx:propose هو الأمر الافتراضي ذو الخطوة الواحدة: فهو ينشئ التغيير ويصيغ جميع نواتج التخطيط دفعة واحدة. أما /opsx:new فهو جزء من مجموعة الأوامر الموسعة ولا يقوم إلا بتجهيز تغيير فارغ، تاركًا لك إنشاء النواتج (artifacts) واحدًا تلو الآخر باستخدام /opsx:continue (أو كلها مرة واحدة باستخدام /opsx:ff). استخدم propose ما لم ترغب في التحكم خطوة بخطوة. راجع الأوامر.

ما هي الملفات الشخصية الأساسية (core) والموسعة (expanded)؟

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

هل أحتاج إلى تشغيل /opsx:sync؟

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

كيف أقوم بتحرير مقترح أو مواصفة أو مهمة بعد البدء؟

ما عليك سوى تحرير الملف. كل ناتج (artifact) هو ملف Markdown عادي في openspec/changes/<name>/، ولا توجد مرحلة مغلقة أو وضع تحرير خاص. قم بتغييره يدويًا، أو اطلب من الذكاء الاصطناعي مراجعته ("قم بتحديث التصميم لاستخدام طابور انتظار")، ثم استمر. يعمل الذكاء الاصطناعي دائمًا بناءً على محتويات الملف الحالية. الدليل الكامل: تحرير وتكرار التغييرات.

هل يمكنني العودة وتغيير الخطة بعد تنفيذ جزء منها؟

نعم، في أي وقت. سير العمل مرن، لذا فإن المراجعة والتحرير ليسا مراحل لا يمكنك الخروج منها. قم بتحرير الناتج (artifact)، ثم استمر. إذا كنت تريد فحصًا منظمًا للتأكد من أن الكود لا يزال يطابق الخطة، فقم بتشغيل /opsx:verify. راجع تحرير وتكرار التغييرات.

لقد قمت بتحرير الكود يدويًا. كيف أوفق ذلك مع المواصفة؟

أعدهما إلى حالة التزامن قبل الأرشفة، لأن الأرشفة تجعل مواصفاتك هي سجل الحقيقة. إذا كان الكود صحيحًا الآن، فقم بتحديث مواصفات الدلتا (delta spec) لتتوافق مع ما قمت بشحنه؛ وإذا كانت المواصفة صحيحة، استمر في البناء حتى يتفق الكود. يعرض /opsx:verify حالات عدم التوافق. راجع تحرير وتكرار التغييرات.

متى يجب علي تحديث تغيير موجود مقابل البدء بتغيير جديد؟

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

ماذا لو نفد سياق جلستي، أو تغيرت المتطلبات أثناء التنفيذ؟

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

هل يجب علي الالتزام (commit) بمجلد openspec/ إلى git؟

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

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

ما الذي يذهب في المواصفة (spec) مقابل التصميم (design)؟

المواصفة تصف السلوك القابل للملاحظة: ماذا يفعل النظام، ومدخلاته ومخرجاته وحالات الخطأ. أما التصميم فيصف كيف ستبنيه: النهج التقني وقرارات البنية والتغييرات في الملفات. إذا كان من الممكن تغيير التنفيذ دون تغيير السلوك المرئي خارجيًا، فإنه يندرج ضمن التصميم وليس المواصفة. المفاهيم يتعمق أكثر في هذا الأمر.

ما هي مواصفات الدلتا (delta spec)؟

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

أين تذهب التغييرات المؤرشفة؟

إلى openspec/changes/archive/YYYY-MM-DD-<name>/، مع الحفاظ على جميع النواتج. لا يتم حذف أي شيء؛ بل تنتقل التغييرة فقط خارج قائمة عملك النشطة.

الإعداد والتخصيص

كيف أخبر الذكاء الاصطناعي عن حزمة التقنيات (tech stack) الخاصة بي؟

ضعه في openspec/config.yaml تحت context:. يتم حقن هذا النص في كل طلب تخطيط، لذا يعرف الذكاء الاصطناعي دائمًا الحزمة والاصطلاحات الخاصة بك. راجع التخصيص.

هل يمكنني إنشاء مواصفات بلغة غير الإنجليزية؟

نعم. أضف تعليمات لغوية إلى context: في ملف التكوين (config). يحتوي متعدد اللغات على مقتطفات جاهزة للعديد من اللغات.

هل يمكنني تغيير سير العمل نفسه؟

نعم، باستخدام المخططات المخصصة (custom schemas). يحدد المخطط أي النواتج موجودة وكيف تعتمد على بعضها البعض. قم بتفرع (fork) الافتراضي باستخدام openspec schema fork spec-driven my-workflow، ثم حرره. راجع التخصيص.

النماذج والخصوصية والتحديثات

أي نموذج ذكاء اصطناعي يجب أن أستخدم؟

يعمل OpenSpec بشكل أفضل مع نماذج التفكير العالي (high-reasoning models). يوصي ملف README بنماذج مثل Codex 5.5 وOpus 4.7 لكل من التخطيط والتنفيذ. واحرص أيضًا على إبقاء نافذة السياق الخاصة بك نظيفة: قم بمسحها قبل التنفيذ للحصول على أفضل النتائج.

هل يجمع OpenSpec البيانات؟

إنه يجمع إحصائيات الاستخدام المجهولة (anonymous usage stats): أسماء الأوامر والنسخة فقط. لا يتم جمع أي وسائط أو مسارات أو محتوى أو بيانات شخصية، وهو مُعطّل تلقائيًا في CI. يمكنك الانسحاب باستخدام export OPENSPEC_TELEMETRY=0 أو export DO_NOT_TRACK=1.

كيف أقوم بالتحديث؟

خطوتان. قم بترقية الحزمة (npm install -g @fission-ai/openspec@latest)، ثم قم بتشغيل openspec update داخل كل مشروع لتحديث المهارات والأوامر المُولّدة.

كيف أقوم بإلغاء تثبيت OpenSpec؟

لا يوجد أمر لإلغاء التثبيت، لأنه مجرد حزمة عامة بالإضافة إلى ملفات في مشروعك. قم بإزالة الحزمة (npm uninstall -g @fission-ai/openspec)، واقم بحذف مجلد openspec/ وملفات الأدوات المُولّدة اختياريًا. الخطوات بالتفصيل، بما في ذلك ما هو آمن للاحتفاظ به، موجودة في التثبيت: إلغاء التثبيت.

الحصول على المساعدة

أين أطرح الأسئلة أو أبلغ عن الأخطاء؟

• Discord: discord.gg/YctCnvvshC
• مشاكل GitHub (GitHub Issues): github.com/Fission-AI/OpenSpec/issues
• من الطرفية الخاصة بك: openspec feedback "رسالتك" يفتح مشكلة على GitHub لك.

هذه الوثائق خاطئة أو مربكة. ماذا أفعل؟

أخبرنا، أو قم بتصحيحها. طلبات السحب (PRs) للوثائق مرحب بها ومقدرة. افتح مشكلة أو أرسل طلب سحب.