FAQ

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

मूल बातें

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

एक हल्का-फुल्का स्तर जो आपको और आपके AI कोडिंग सहायक को किसी भी कोड लिखे जाने से पहले, लिखित रूप में निर्धारित करता है कि क्या बनाना है।

मुझे यह क्यों चाहिए?

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

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

नहीं। इसे वहाँ उपयोग करें जहाँ सहमति महत्वपूर्ण है, जो अधिकांश गैर-सरल कार्य हैं। एक अक्षर की टाइपो सुधार के लिए, यह प्रक्रिया शायद लायक नहीं है, और यह ठीक है।

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

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

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

नहीं。OpenSpec 30+ सहायकों के साथ काम करता है, जिनमें Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex, और अन्य शामिल हैं। पूर्ण सूची और टूल-विशिष्ट विवरण Supported Tools में हैं।

कमांड चलाएँ

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

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

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

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

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

सबसे संभावना है कि आपने इसे AI चैट के बजाय टर्मिनल में टाइप किया, आपने ऐसी वर्तनी का उपयोग किया जो आपका टूल पहचानता नहीं है, या कमांड अभी इंस्टॉल नहीं हुए हैं। यदि फ़ाइलें अनुपस्थित हैं — या आपने कभी टूल सेटअप नहीं किया — तो openspec init चलाएँ; openspec update केवल मौजूद फ़ाइलों को रीफ्रेश करता है। फिर अपना सहायक रीस्टार्ट करें और "Getting started" के नीचे छपे फ़ॉर्म का उपयोग करें — How To Invoke देखें। Troubleshooting में पूर्ण चेकलिस्ट है।

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

प्रत्येक AI टूल कस्टम कमांड थोड़े अलग तरीके से प्रदर्शित करता है, और OpenSpec उन्हें उसी तरह स्पेल करता है जिस तरह आपका टूल उस फ़ाइल को लोड करता है जिसे उसने लिखा है। opsx-propose.md नाम की कमांड फ़ाइल /opsx-propose के रूप में टाइप होती है; commands/opsx/ के अंतर्गत रखी गई फ़ाइल /opsx:propose के रूप में टाइप होती है। कमांड के बजाय skills लेने वाले टूल skill नाम का उपयोग करते हैं — Codex को $openspec-propose चाहिए, Kimi Code को /skill:openspec-propose। openspec init का "Getting started" लाइन पहले से ही आपके चुने हुए टूल के लिए सही फ़ॉर्म छापता है; पूर्ण तालिका How To Invoke में है।

skill और command में क्या अंतर है?

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

वर्कफ़्लो

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

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

सबसे सरल संभव फ़्लो क्या है?

/opsx:explore (optional)   then   /opsx:propose <what you want>   then   /opsx:apply   then   /opsx:archive

Explore करके सोचें, propose करके योजना तैयार करें, apply करके बनाएँ, archive करके फ़ाइल करें। जब आप पहले से ही ठीक जानते हैं कि आपको क्या चाहिए, तब explore छोड़ दें।

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

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

core और expanded profiles क्या हैं?

प्रोफ़ाइल तय करती है कि कौन से स्लैश कमांड इंस्टॉल होते हैं। Core (डिफ़ॉल्ट) आपको propose, explore, apply, update, sync, archive देता है। Expanded सेट new, continue, ff, verify, bulk-archive, और onboard जोड़ता है बेहतर नियंत्रण के लिए। openspec config profile से स्विच करें, फिर openspec update से लागू करें।

क्या मुझे /opsx:sync चलाना चाहिए?

आमतौर पर नहीं। Sync परिवर्तन के delta specs को आपके मुख्य specs में मर्ज करता है, और /opsx:archive आपको यह करने का प्रस्ताव देगा। सिर्फ़ तब sync मैनुअली चलाएँ जब आप चाहते हैं कि specs archive करने से पहले मर्ज हों, उदाहरण के लिए एक लंबे समय तक चलने वाले परिवर्तन पर。Commands देखें।

शुरू करने के बाद मैं proposal, spec, या task कैसे एडिट करूँ?

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

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

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

मैंने कोड हाथ से एडिट किया। मैं इसे spec के साथ कैसे समझौता करूँ?

archive करने से पहले उन्हें फिर से sync में लाएँ, क्योंकि archiving आपके specs को सत्य की रिकॉर्ड बना देता है। यदि कोड अब सही है, तो delta spec को अपडेट करें जो आपने shipped किया है उससे मेल खाए; यदि spec सही है, तो बनाते रहें जब तक कोड सहमत न हो जाए। /opsx:verify mismatch दिखाता है। Editing & Iterating on a Change देखें।

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

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

यदि मेरी session का context खत्म हो जाए, या requirements mid-implementation में बदल जाएँ?

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

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

हाँ। आपके specs, सक्रिय परिवर्तन, और archive आपके प्रोजेक्ट के इतिहास का हिस्सा हैं। इन्हें किसी अन्य source की तरह commit करें。विशेष रूप से archive आपके सिस्टम के इस तरह काम करने के कारण की स्थायी रिकॉर्ड बन जाता है।

Specs और Changes

spec में क्या जाता है और design में क्या?

Spec observable व्यवहार का वर्णन करता है: सिस्टम क्या करता है, इसके inputs, outputs, और error conditions। Design वर्णन करता है कि आप इसे कैसे बनाएँगे: तकनीकी दृष्टिकोण, architecture निर्णय, फ़ाइल परिवर्तन। यदि implementation बिना बाहरी रूप से दृश्य व्यवहार बदले बदल सकता है, तो यह design में आता है, spec में नहीं। Concepts गहराई से देखता है।

Delta spec क्या है?

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

Archived changes कहाँ जाते हैं?

openspec/changes/archive/YYYY-MM-DD-<name>/ में, सभी change artifacts संरक्षित रहते हैं। परिवर्तन आपके सक्रिय सूची से बाहर हो जाता है। एक परिवर्तन जो स्पष्ट रूप से retire_capabilities: true घोषित करता है, वह उस capability के अंतिम requirement को हटाने पर मुख्य capability spec को भी हटा सकता है।

Configuration और Customization

मैं AI को अपने tech stack के बारे में कैसे बताऊँ?

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

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

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

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

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

Models, Privacy, और Upgrades

मैं कौन सा AI model उपयोग करूँ?

OpenSpec high-reasoning models के साथ सबसे अच्छा काम करता है। README में Codex 5.5 और Opus 4.7 जैसे models की सिफ़ारिश planning और implementation दोनों के लिए की गई है। साथ ही अपना context window साफ़ रखें: सबसे अच्छे परिणामों के लिए implementation से पहले इसे साफ़ करें।

क्या OpenSpec data collect करता है?

यह anonymous usage stats collect करता है: केवल command names और version। कोई arguments, paths, content, या personal data नहीं, और यह CI में स्वतः बंद हो जाता है। export OPENSPEC_TELEMETRY=0 या export DO_NOT_TRACK=1 से opt-out करें।

मैं कैसे upgrade करूँ?

दो चरण। Package को upgrade करें (npm install -g @fission-ai/openspec@latest), फिर हर project के अंदर openspec update चलाएँ ताकि generated skills और commands रीफ्रेश हों।

मैं OpenSpec को कैसे uninstall करूँ?

कोई uninstall command नहीं है, क्योंकि यह केवल एक global package और आपके project में फ़ाइलें हैं। Package को हटाएँ (npm uninstall -g @fission-ai/openspec), और वैकल्पिक रूप से openspec/ directory और generated tool files को delete करें। Step-by-step, जिसमें क्या सुरक्षित रखना है वह भी शामिल है, Installation: Uninstalling में है।

मदद प्राप्त करें

मैं प्रश्न पूछने या bugs report कहाँ करूँ?

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

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

हमें बताएँ, या इसे ठीक करें। Documentation PR स्वागत योग्य और मूल्यवान हैं। एक issue खोलें या pull request भेजें।