अक्सर पूछे जाने वाले प्रश्न (FAQ)

उन सवालों के त्वरित जवाब जो लोग सबसे अधिक पूछते हैं। यदि आपका सवाल वास्तव में "कुछ टूटा हुआ है" वाला है, तो Troubleshooting बेहतर पृष्ठ है। यदि आप किसी शब्द की परिभाषा चाहते हैं, तो Glossary देखें।

मूल बातें (The basics)

एक वाक्य में OpenSpec क्या है?

यह एक हल्का लेयर (lightweight layer) है जो कोड लिखे जाने से पहले आपको और आपके AI कोडिंग असिस्टेंट को इस बात पर सहमत कराता है कि क्या बनाना है, और उसे लिखित रूप में रखता है।

मैं इसकी आवश्यकता क्यों महसूस करूँगा?

क्योंकि AI असिस्टेंट गलत होने पर भी आत्मविश्वास रखते हैं। जब आवश्यकताएँ केवल एक चैट थ्रेड (chat thread) में मौजूद होती हैं, तो AI अनुमानों से कमियों को भर देता है, और आपको कोड बनने के बाद पता चलता है। OpenSpec इस समझौते को पहले आगे लाता है, जहाँ गलतियाँ सुधारने में सस्ती होती हैं। पूरी जानकारी के लिए Core Concepts at a Glance देखें।

क्या मुझे हर चीज़ के लिए इसका उपयोग करना होगा?

नहीं। इसे वहाँ उपयोग करें जहाँ सहमति मायने रखती है, यानी अधिकांश गैर-तुच्छिक (non-trivial) काम में। एक कैरेक्टर की टाइपो ठीक करने के लिए यह औपचारिकता शायद आवश्यक नहीं है, और यह ठीक है।

क्या मैं इसका उपयोग एक बड़ी मौजूदा codebase पर कर सकता हूँ, या केवल नए प्रोजेक्ट्स पर?

मौजूदा codebases मुख्य विषय हैं। OpenSpec brownfield-first है: आपको शुरुआत में अपने पूरे ऐप का दस्तावेज़ीकरण करने की आवश्यकता नहीं है। आप केवल उस चीज़ के लिए स्पेसिफिकेशन्स (specs) लिखते हैं जिसे हर बदलाव छूता है, और समय के साथ आपके स्पेसिफिकेशन्स उस काम के इर्द-गिर्द भर जाते हैं जो आप वास्तव में करते हैं। इसके लिए एक समर्पित गाइड है: Using OpenSpec in an Existing Project।

क्या यह किसी एक AI टूल से जुड़ा हुआ है?

नहीं। OpenSpec 25+ असिस्टेंट्स के साथ काम करता है, जिसमें Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Codex और अन्य शामिल हैं। पूर्ण सूची और प्रति-टूल विवरण Supported Tools में दिए गए हैं।

कमांड चलाना (Running commands)

मैं /opsx:propose कहाँ टाइप करता हूँ?

अपने टर्मिनल में नहीं, बल्कि अपने AI असिस्टेंट की चैट में। यह भ्रम का सबसे आम बिंदु है, इसलिए इसके लिए एक अलग पृष्ठ है: How Commands Work। संक्षिप्त संस्करण: openspec ... टर्मिनल में चलता है, /opsx:... चैट में चलता है।

मैं "इंटरैक्टिव मोड" कैसे शुरू करता हूँ?

शुरू करने के लिए कोई अलग मोड नहीं है। आप अपने AI असिस्टेंट को सामान्य रूप से खोलते हैं और उसकी चैट में एक स्लैश कमांड टाइप करते हैं। स्लैश कमांड वह तरीका है जिससे आप OpenSpec में "प्रवेश" करते हैं। (वास्तव में इंटरैक्टिव टर्मिनल सुविधा openspec view है, जो स्पेसिफिकेशन्स और परिवर्तनों को ब्राउज़ करने के लिए एक डैशबोर्ड है।) पूर्ण स्पष्टीकरण How Commands Work में है।

मैंने एक स्लैश कमांड टाइप किया और कुछ नहीं हुआ। क्यों?

सबसे अधिक संभावना यह है कि आपने इसे अपने AI चैट के बजाय टर्मिनल में टाइप किया, या कमांड अभी तक इंस्टॉल नहीं हुए हैं। अपने प्रोजेक्ट में openspec update चलाएँ, अपने असिस्टेंट को पुनरारंभ करें, फिर चैट में /opsx टाइप करने का प्रयास करें और ऑटोकम्प्लीट (autocomplete) देखें। Troubleshooting में पूरी चेकलिस्ट है।

एक टूल में सिंटैक्स /opsx:propose क्यों है और दूसरे में /opsx-propose क्यों है?

प्रत्येक AI टूल कस्टम कमांड्स को थोड़ा अलग तरीके से प्रदर्शित करता है। इरादा समान है; केवल विराम चिह्न बदल जाते हैं। अपनी चैट में एक स्लैश टाइप करें और ऑटोकम्प्लीट आपको वह फॉर्म दिखाता है जिसकी आपका टूल अपेक्षा करता है। प्रति-टूल तालिका How Commands Work में है।

स्किल (skill) और कमांड (command) में क्या अंतर है?

ये दोनों फाइलें हैं जिन्हें OpenSpec लिखता है ताकि आपका असिस्टेंट वर्कफ़्लो चला सके। स्किल्स (.../skills/openspec-*/SKILL.md) नए क्रॉस-टूल मानक हैं; कमांड्स (.../commands/opsx-*) पुराने प्रति-टूल स्लैश फ़ाइल हैं। आपको कोई एक चुनने की ज़रूरत नहीं है। आप बस स्लैश कमांड टाइप करते हैं, और OpenSpec वह इंस्टॉल कर देता है जिसका उपयोग आपका टूल करता है।

वर्कफ़्लो (The workflow)

यदि मैं निश्चित नहीं हूँ कि क्या बनाना है तो मुझे कहाँ से शुरुआत करनी चाहिए?

/opsx:explore के साथ। यह एक बिना जोखिम वाला विचार भागीदार (no-stakes thinking partner) है जो आपकी codebase को पढ़ता है, विकल्पों को प्रस्तुत करता है, और किसी भी बदलाव या कोड के होने से पहले ही एक अस्पष्ट समस्या को एक ठोस योजना में बदल देता है। यह डिफ़ॉल्ट प्रोफ़ाइल में है, इसलिए यह हमेशा उपलब्ध है। जब योजना स्पष्ट हो जाती है, तो यह /opsx:propose को सौंपता है। यह वह सबसे अच्छी आदत है जिसे आप बना सकते हैं, क्योंकि यह एक उत्सुक AI को गलत चीज़ बनाने से रोकता है। Explore First देखें।

सबसे सरल संभव प्रवाह क्या है?

/opsx:explore (वैकल्पिक)   फिर   /opsx:propose <आप क्या चाहते हैं>   फिर   /opsx:apply   फिर   /opsx:archive

सोचने के लिए Explore करें, योजना का मसौदा तैयार करने के लिए Propose करें, इसे बनाने के लिए Apply करें, और फ़ाइल में रखने के लिए Archive करें। यदि आप पहले से ही ठीक-ठीक जानते हैं कि आपको क्या चाहिए तो explore को छोड़ दें।

/opsx:propose और /opsx:new में क्या अंतर है?

/opsx:propose डिफ़ॉल्ट वन-स्टेप कमांड है: यह एक साथ बदलाव बनाता है और सभी योजना कलाकृतियों (planning artifacts) का मसौदा तैयार करता है। /opsx:new विस्तारित कमांड सेट का हिस्सा है और केवल एक खाली बदलाव को स्कैफोल्ड (scaffolds) करता है, जिससे आपको /opsx:continue के साथ धीरे-धीरे या /opsx:ff के साथ सब कुछ एक साथ कलाकृतियाँ बनाने की आवश्यकता होती है। यदि आप चरण-दर-चरण नियंत्रण नहीं चाहते हैं तो propose का उपयोग करें। Commands देखें।

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 चलाएँ जब आप आर्काइव करने से पहले स्पेसिफिकेशन्स को मर्ज करना चाहते हैं, उदाहरण के लिए एक लंबे समय तक चलने वाले बदलाव पर। Commands देखें।

क्या मैं शुरू करने के बाद किसी प्रस्ताव (proposal), spec, या कार्य को संपादित कर सकता हूँ?

बस फ़ाइल को संपादित करें। हर कलाकृति openspec/changes/<name>/ में सादा Markdown है, और कोई लॉक किया हुआ चरण या विशेष संपादन मोड नहीं है। इसे हाथ से बदलें, या अपने AI से इसे संशोधित करने के लिए कहें ("एक कतार (queue) का उपयोग करने के लिए डिज़ाइन अपडेट करें"), फिर आगे बढ़ें। AI हमेशा वर्तमान फ़ाइल सामग्री से काम करता है। पूर्ण गाइड: Editing & Iterating on a Change।

क्या मैं कुछ लागू करने के बाद योजना में वापस जा सकता हूँ और उसे बदल सकता हूँ?

हाँ, किसी भी समय। वर्कफ़्लो तरल (fluid) होता है, इसलिए समीक्षा (review) और संपादन ऐसे चरण नहीं हैं जिनसे आप बाहर हो जाते हैं। कलाकृति को संपादित करें, फिर जारी रखें। यदि आप एक संरचित जाँच चाहते हैं कि कोड अभी भी योजना से मेल खाता है या नहीं, तो /opsx:verify चलाएँ। Editing & Iterating on a Change देखें।

मैंने हाथ से कोड संपादित किया है। मैं इसे spec के साथ कैसे मिलाऊँ (reconcile)?

आर्काइव करने से पहले उन्हें सिंक में लाएँ, क्योंकि आर्काइव आपके स्पेसिफिकेशन्स को सत्य का रिकॉर्ड बनाता है। यदि कोड अब सही है, तो शिप किए गए काम से मेल खाने के लिए डेल्टा spec को अपडेट करें; यदि spec सही है, तो तब तक बनाते रहें जब तक कि कोड सहमत न हो जाए। /opsx:verify विसंगतियों (mismatches) को सामने लाता है। Editing & Iterating on a Change देखें।

मुझे मौजूदा बदलाव को अपडेट करना चाहिए या नया शुरू करना चाहिए?

अपडेट करें जब यह वही काम हो, जिसे परिष्कृत किया गया हो। तब नया शुरू करें जब इरादा मौलिक रूप से बदल गया हो या दायरा विभिन्न कार्यों में फट गया हो (exploded)। Workflows में एक निर्णय फ्लोचार्ट और उदाहरण हैं।

क्या होगा यदि मेरा सत्र संदर्भ (context) खत्म हो जाता है, या कार्यान्वयन के दौरान आवश्यकताएँ बदल जाती हैं?

यहीं स्पेसिफिकेशन्स अपना महत्व कमाते हैं। चूंकि योजना फ़ाइलों में रहती है (केवल चैट इतिहास में नहीं), इसलिए आप अपना संदर्भ साफ़ कर सकते हैं, एक नया AI सत्र शुरू कर सकते हैं, और /opsx:apply के साथ उठा सकते हैं; यह कलाकृतियों को पढ़ता है और पहले अनचेक किए गए कार्य से फिर से शुरू करता है। यदि आवश्यकताएँ बदलती हैं, तो नई वास्तविकता से मेल खाने के लिए कलाकृतियों को संपादित करें और जारी रखें। एक स्वच्छ संदर्भ विंडो बनाए रखना भी बेहतर परिणाम देता है; कार्यान्वयन से पहले इसे साफ़ करें।

क्या मुझे openspec/ फ़ोल्डर को git में commit करना चाहिए?

हाँ। आपके स्पेसिफिकेशन्स, सक्रिय बदलाव और आर्काइव आपके प्रोजेक्ट के इतिहास का हिस्सा हैं। उन्हें किसी अन्य स्रोत की तरह commit करें। विशेष रूप से आर्काइव इस बात का एक टिकाऊ रिकॉर्ड बन जाता है कि आपका सिस्टम जिस तरह से काम करता है वह क्यों करता है।

Specs और Changes

spec में क्या जाता है बनाम design में?

एक spec अवलोकन योग्य व्यवहार (observable behavior) का वर्णन करता है: सिस्टम क्या करता है, उसके इनपुट, आउटपुट और त्रुटि की स्थितियाँ। एक design बताता है कि आप इसे कैसे बनाएंगे: तकनीकी दृष्टिकोण, वास्तुकला निर्णय, फ़ाइल परिवर्तन। यदि कार्यान्वयन बाहरी रूप से दिखाई देने वाले व्यवहार को बदले बिना बदल सकता है, तो यह spec में नहीं, बल्कि design में संबंधित है। Concepts गहराई में जाता है।

delta spec क्या है?

एक ऐसा spec जो केवल उस चीज़ का वर्णन करता है जो बदल रही है, जिसमें ADDED, MODIFIED, और REMOVED सेक्शन होते हैं, न कि पूरे spec को दोहराता है। यह वह तरीका है जिससे OpenSpec मौजूदा सिस्टमों में संपादन (edits) को साफ तरीके से संभालता है। Concepts देखें।

आर्काइव किए गए बदलाव कहाँ जाते हैं?

openspec/changes/archive/YYYY-MM-DD-<name>/ पर, जिसमें सभी कलाकृतियाँ संरक्षित हों। कुछ भी डिलीट नहीं होता; बदलाव बस आपकी सक्रिय सूची से बाहर चला जाता है।

कॉन्फ़िगरेशन और अनुकूलन (Configuration and customization)

मैं AI को अपने टेक स्टैक के बारे में कैसे बताता हूँ?

इसे openspec/config.yaml में context: के तहत रखें। यह टेक्स्ट हर योजना अनुरोध में इंजेक्ट किया जाता है, इसलिए AI हमेशा आपके स्टैक और परंपराओं को जानता है। Customization देखें।

क्या मैं अंग्रेजी के अलावा किसी अन्य भाषा में specs उत्पन्न कर सकता हूँ?

हाँ। अपने config की context: में एक भाषा निर्देश जोड़ें। Multi-Language में कई भाषाओं के लिए कॉपी-पेस्ट स्निपेट हैं।

क्या मैं वर्कफ़्लो को स्वयं बदल सकता हूँ?

हाँ, कस्टम स्कीमा (custom schemas) के साथ। एक स्कीमा परिभाषित करता है कि कौन सी कलाकृतियाँ मौजूद हैं और वे एक दूसरे पर कैसे निर्भर करती हैं। openspec schema fork spec-driven my-workflow के साथ डिफ़ॉल्ट को फोर्क करें, फिर इसे संपादित करें। Customization देखें।

मॉडल, गोपनीयता और अपग्रेड (Models, privacy, and upgrades)

मुझे कौन सा AI मॉडल उपयोग करना चाहिए?

OpenSpec उच्च तर्क क्षमता वाले मॉडलों के साथ सबसे अच्छा काम करता है। 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/ डायरेक्टरी और उत्पन्न टूल फ़ाइलों को हटा दें। चरण-दर-चरण, जिसमें क्या सुरक्षित रखना है वह शामिल है, Installation: Uninstalling में दिया गया है।

सहायता प्राप्त करना (Getting help)

मैं प्रश्न कहाँ पूछूँ या बग रिपोर्ट करूँ?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• अपने टर्मिनल से: openspec feedback "your message" आपके लिए एक GitHub issue खोलता है।

ये दस्तावेज़ गलत या भ्रमित करने वाले हैं। मैं क्या करूँ?

हमें बताएं, या इसे ठीक करें। दस्तावेज़ीकरण PRs का स्वागत है और उन्हें महत्व दिया जाता है। एक इशूअर (issue) खोलें या पुल रिक्वेस्ट (pull request) भेजें।