OpenSpec

الأسئلة الشائعة ​

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

الأساسيات ​

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

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

لماذا أريد ذلك؟ ​

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

هل يجب أن أستخدمه لكل شيء؟ ​

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

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

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

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

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

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

أين أكتب /opsx:propose؟ ​

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

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

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

كتبتُ أمر شلش ولم يحدث شيء. لماذا؟ ​

الأرجح أنك كتبته في الطرفية بدلاً من محادثة الذكاء الاصطناعي، أو استخدمت تهجئة لا تتعرف عليها الأداة، أو أن الأوامر غير مثبتة بعد. إذا كانت الملفات مفقودة — أو لم تقم بإعداد الأداة أبداً — شغّل openspec init؛ openspec update يحدّث فقط الملفات الموجودة مسبقاً. ثم أعد تشغيل مساعدك واستخدم الصيغة المطبوعة تحت "البدء" — راجع كيف تستدعي. استكشاف الأخطاء وإصلاحها يحتوي على القائمة الكاملة.

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

كل أداة ذكاء اصطناعي تعرض الأوامر المخصصة بطريقة مختلفة قليلاً، وOpenSpec يكتبها بالطريقة التي تقرأ بها الأداة الملف الذي كتبه. ملف أمر مسمى opsx-propose.md يُكتب /opsx-propose؛ وملف موضوع تحت commands/opsx/ يُكتب /opsx:propose. الأدوات التي تستخدم المهارات بدلاً من الأوامر تستخدم اسم المهارة — Codex يحتاج $openspec-propose، وKimi Code /skill:openspec-propose. سطر "البدء" في openspec init يطبع بالفعل الصيغة الصحيحة للأدوات التي اخترتها؛ الجدول الكامل موجود في كيف تستدعي.

ما الفرق بين المهارة والأمر؟ ​

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

سير العمل ​

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

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

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

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

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

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

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

ما هي ملفات core والملفات الموسعة؟ ​

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

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

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

كيف أحرّر اقتراحاً أو مواصفة أو مهمة بعد أن بدأت؟ ​

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

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

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

حرّرتُ الكود يدوياً. كيف أوفقه مع المواصفة؟ ​

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

متى أحدّث تغييراً قائماً مقابل بدء واحد جديد؟ ​

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

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

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

هل يجب أن ألتزم بملف openspec/ في git؟ ​

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

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

ماذا توضع في المواصفة مقابل التصميم؟ ​

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

ما هي مواصفة الدلتا؟ ​

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

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

إلى openspec/changes/archive/YYYY-MM-DD-<name>/، مع الحفاظ على جميع عناصر التغيير. ينتقل التغيير خارج قائمتك النشطة. يمكن لتغيير يعلن صراحةً retire_capabilities: true أيضاً حذف مواصفة قدرة رئيسية عندما يزيل المتطلب الأخير لتلك القدرة.

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

كيف أخبر الذكاء الاصطناعي عن تقنياتي؟ ​

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

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

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

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

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

النماذج والخصوصية والترقيات ​

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

يعمل OpenSpec بشكل أفضل مع نماذج الاستدلال العالي. يوصي README بنماذج مثل Codex 5.5 وOpus 4.7 لكل من التخطيط والتنفيذ. حافظ أيضاً على نافذة سياقك نظيفة: امسحها قبل التنفيذ لأفضل النتائج.

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

يجمع إحصاءات استخدام مجهولة: أسماء الأوامر والإصدار فقط. لا حِجج، مسارات، محتوى، أو بيانات شخصية، وهي معطّلة تلقائياً في 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/ وملفات الأدوات المولّدة. خطوة بخطوة، بما في ذلك ما هو آمن للإبقاء عليه، موجود في التثبيت: إلغاء التثبيت.

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

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

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

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