उदाहरण और रेसिपी

वास्तविक परिवर्तन, शुरुआत से अंत तक। प्रत्येक रेसिपी उन कमांड्स को दिखाती है जिन्हें आप टाइप करेंगे और आपको क्या प्रतिक्रिया मिलेगी, ताकि आप अपनी स्थिति को किसी पैटर्न से मिला सकें और इसे कॉपी कर सकें। ये डिफॉल्ट कोर कमांड्स (propose, explore, apply, sync, archive) का उपयोग करती हैं; जहां विस्तारित सेट मदद करता है, वहां नोट किया गया है।

शुरू करने से पहले एक अनुस्मारक: /opsx:propose जैसे स्लैश कमांड्स आपके AI सहायक के चैट में जाते हैं, और openspec कमांड्स आपके टर्मिनल में जाते हैं। यदि यह नया है तो पहले कमांड्स कैसे काम करते हैं पढ़ें। नीचे दिए गए ट्रांसक्रिप्ट में, You: और AI: चैट हैं, और $ से शुरू होने वाली लाइनें टर्मिनल हैं।

अभी तक यह निश्चित नहीं है कि आप क्या बना रहे हैं? यदि आप पहले /opsx:explore के साथ शुरुआत करके इसे सोच लें तो इनमें से अधिकांश रेसिपीज़ अधिक प्रभावी होती हैं। रेसिपी 3 इसे कार्य में दिखाती है, और पहले एक्सप्लोर करें गाइड पूरा मामला प्रस्तुत करती है।

रेसिपी 1: एक छोटा फीचर, त्वरित मार्ग

इसका उपयोग कब करें: जब आप जानते हैं कि आप क्या चाहते हैं, और या एक सीमित कार्य है। यह सबसे आम रेसिपी है।

पूरा काम तीन कमांड्स में होता है: प्रस्ताव प्रस्तुत करें, बिल्ड करें, आर्काइव करें।

आप: /opsx:propose add-logout-button

एआई:  openspec/changes/add-logout-button/ बनाया गया
     ✓ proposal.md — क्यों और क्या
     ✓ specs/      — नया आवश्यकता और इसके परिदृश्य
     ✓ design.md   — तकनीकी दृष्टिकोण
     ✓ tasks.md    — कार्यान्वयन चेकलिस्ट
     कार्यान्वयन के लिए तैयार। /opsx:apply चलाएं।

अब योजना पढ़ें। प्रस्ताव और डेल्टा स्पेक दोनों खोलें। यह वह क्षण है जिसके लिए OpenSpec बनाया गया है: जब कोई गलत धारणा अभी एक पैराग्राफ में हो, 400 लाइन कोड में नहीं, उसे पकड़ना। यदि कुछ गलत है तो किसी भी आर्टिफैक्ट को सीधा संपादित करें, फिर आगे बढ़ें।

आप: /opsx:apply

एआई:  कार्यों को पूरा कर रहा हूं...
     ✓ 1.1 हेडर में लॉगआउट बटन जोड़ें
     ✓ 1.2 क्लिक पर सेशन साफ करें
     ✓ 1.3 पुष्टिकरण संवाद जोड़ें
     सभी कार्य पूरे हो गए!

आप: /opsx:archive

एआई:  add-logout-button को आर्काइव कर रहा हूं...
     ✓ स्पेक्स को openspec/specs/auth/spec.md में मर्ज किया गया
     ✓ openspec/changes/archive/2026-06-22-add-logout-button/ में स्थानांतरित किया गया
     हो गया। अगले परिवर्तन के लिए तैयार।

बस इतना ही। लॉगआउट व्यवहार अब आपके स्पेक्स का हिस्सा है, और परिवर्तन अपना पूरा संदर्भ साथ फाइल कर दिया गया है।

रेसिपी 2: एक बग फिक्स

इसका उपयोग कब करें: जब कुछ टूटा हुआ है और आप चाहते हैं कि फिक्स को व्यवहार के जानबूझकर किए गए परिवर्तन के रूप में रिकॉर्ड किया जाए, न कि एक रहस्यमय कमिट के रूप में।

बग फिक्स फीचर्स की तरह ही काम करते हैं। अंतर प्रस्ताव को कैसे फ्रेम करने में है: सही व्यवहार का वर्णन करें, केवल "बग फिक्स करें" नहीं।

आप: /opsx:propose fix-login-redirect-loop

एआई:  openspec/changes/fix-login-redirect-loop/ बनाया गया
     प्रस्ताव वर्तमान में टूटे हुए व्यवहार और इच्छित व्यवहार को कैप्चर करता है।
     डेल्टा स्पेक रिडायरेक्ट आवश्यकता को **परिवर्तित** करता है ताकि यह अब सटीक और परीक्षण योग्य हो।
     कार्यान्वयन के लिए तैयार।

क्योंकि फिक्स एक नए परिदृश्य के साथ MODIFIED आवश्यकता के रूप में लैंड होती है, अगला व्यक्ति (या अगला AI सत्र) केवल यह नहीं देखता कि आपने इसे फिक्स किया, बल्कि "सही" का क्या अर्थ है भी देखता है। फिर सामान्य की तरह /opsx:apply और /opsx:archive चलाएं।

सुझाव: फिक्स के लिए, एक अच्छा परिदृश्य प्रोस में रिग्रेशन टेस्ट होता है। "GIVEN a logged-out user, WHEN they submit valid credentials, THEN they land on the dashboard and are not redirected again." इसे लिखें, और कार्यान्वयन के पास एक स्पष्ट लक्ष्य हो जाएगा।

रेसिपी 3: कमिट करने से पहले एक्सप्लोर करना

इसका उपयोग कब करें: जब आपके पास एक समस्या है लेकिन अभी तक कोई योजना नहीं है। आप निश्चित नहीं हैं कि क्या बनाएं, या कौन सा दृष्टिकोण सही है।

/opsx:explore के साथ शुरुआत करें। यह कोई संरचना या बनाए गए आर्टिफैक्ट के बिना एक सोचने का साथी है। यह आपके कोडबेस को पढ़ता है और आपको निर्णय लेने में मदद करता है।

आप: /opsx:explore

एआई:  आप क्या एक्सप्लोर करना चाहेंगे?

आप: पेज लोड धीमे लग रहे हैं लेकिन मुझे नहीं पता कि समय कहां जा रहा है।

एआई:  चलिए मैं देखता हूं... मुझे तीन संभावित कारण मिले:
     1. प्रोडक्ट लिस्ट पर बड़े अनऑप्टिमाइज्ड इमेज
     2. रेंडर को ब्लॉक करने वाला सिंक्रोनस डेटा फेचिंग
     3. कॉन्टेक्स्ट चेंजेज द्वारा ट्रिगर किए गए री-रेंडर
     हमें पहले किससे संबोधन करना चाहिए?

आप: डेटा फेचिंग वाला।

आप: /opsx:propose optimize-product-list-fetching

एआई:  परिवर्तन बनाया गया, जिसमें हमने अभी जो कुछ ढूंढा है उससे जानकारी लेकर प्रस्ताव तैयार किया गया है। कार्यान्वयन के लिए तैयार।

एक्सप्लोरेशन आपके सोच को स्पष्ट करता है इससे पहले कि आप इस पर कोई परिवर्तन खर्च करें। जब अंतर्दृष्टि स्पष्ट हो जाती है, तो प्रस्ताव प्रस्तुत करें, और एआई संदर्भ को आगे ले जाता है।

रेसिपी 4: एक साथ दो परिवर्तनों को संभालना

इसका उपयोग कब करें: जब आप फीचर के बीच में हैं और एक जरूरी फिक्स कतार में आ जाती है।

परिवर्तन स्वतंत्र फोल्डर होते हैं, इसलिए समांतर कार्य में कोई टकराव नहीं होता। फिक्स शुरू करें, इसे शिप करें, फिर उसी बिंदु पर फीचर पर वापस लौटें जहां आपने छोड़ा था।

आप: मैं add-dark-mode के बीच में हूं, लेकिन मुझे अभी लॉगिन बग फिक्स करने की जरूरत है।

आप: /opsx:propose fix-login-redirect

एआई:  openspec/changes/fix-login-redirect/ बनाया गया। कार्यान्वयन के लिए तैयार।

आप: /opsx:apply

एआई:  फिक्स को लागू कर दिया गया है। सभी कार्य पूरे हो गए।

आप: /opsx:archive

एआई:  ✓ fix-login-redirect को आर्काइव कर दिया गया।

आप: डार्क मोड पर वापस।

आप: /opsx:apply add-dark-mode

एआई:  add-dark-mode फिर से शुरू कर रहा हूं। कार्य 2.3 पर वापस आ रहा हूं: हेडर अपडेट करें...

जब एक से ज़्यादा एक्टिव चेंज हो तो /opsx:apply add-dark-mode में चेंज का नाम देना ही एआई को किसी विशिष्ट चेंज की ओर इशारा करने का तरीका है। क्योंकि कार्यों को tasks.md में पूरा होने की ट्रैक रखी जाती है, एआई को बिल्कुल पता होता है कि आपने कहां रोका है।

जब एक साथ कई परिवर्तन पूरे हो जाते हैं, तो विस्तारित /opsx:bulk-archive उन्हें एक साथ फाइल करता है और वास्तव में लागू किए गए को चेक करके स्पेक कॉन्फ्लिक्ट्स को हल करता है। वर्कफ्लो देखें।

रेसिपी 5: व्यवहार में कोई बदलाव न होने वाला रिफैक्टर

इसका उपयोग कब करें: जब आप कोड को फिर से संरचना कर रहे हैं, और बाहरी रूप से दिखने वाला व्यवहार समान रहना चाहिए।

यह दिलचस्प मामला है, क्योंकि एक प्यूर रिफैक्टर में आपके स्पेक्स में कुछ भी जोड़ने के लिए नहीं होता। व्यवहार कॉन्ट्रैक्ट बदलता नहीं; केवल कार्यान्वयन बदलता है। इसलिए कार्य डिजाइन और कार्यों में रहता है, और स्पेक डेल्टा खाली या अनुपस्थित होता है।

आप: /opsx:propose refactor-payment-module

एआई:  परिवर्तन बनाया गया। प्रस्ताव लक्ष्य (पेमेंट मॉड्यूल को अलग करें, व्यवहार में कोई बदलाव नहीं) को बताता है और डिजाइन नई संरचना को कैप्चर करता है। कोई स्पेक बदलाव नहीं, क्योंकि व्यवहार समान है।
     कार्यान्वयन के लिए तैयार।

खाली डेल्टा को स्पष्ट रूप से घोषित करने के लिए चेंज के .openspec.yaml में skip_specs: true सेट करें:

schema: spec-driven
skip_specs: true

मार्कर के बिना, openspec validate शून्य डेल्टा वाले परिवर्तन को रद्द करता है (ताकि भूल जाए गए स्पेक्स फेज भी पकड़ा जा सके); मार्कर के साथ, वैलिडेशन पास हो जाती है और openspec status स्पेक्स स्टेज को पेंडिंग के बजाय स्पष्ट रूप से स्किप किए हुए के रूप में दिखाता है। यदि आखिरकार रिफैक्टर व्यवहार बदल देता है, तो .openspec.yaml से skip_specs हटा दें और डेल्टा स्पेक्स लिखें — वैलिडेशन मार्कर और स्पेक फाइलों को कॉन्फ्लिक्ट के रूप में ट्रीट करता है, इसलिए पुराना मार्कर चुपचाप नहीं रह सकता।

मार्क वाले चेंज को आर्काइव करने के लिए किसी अतिरिक्त फ्लैग की जरूरत नहीं होती (मर्ज करने के लिए कोई डेल्टा नहीं है)। अलग से, --skip-specs फ्लैग टर्मिनल कमांड को स्पेक स्टेप को स्पष्ट रूप से स्किप करने के लिए बताता है:

$ openspec archive refactor-payment-module --skip-specs

यही फ्लैग टूलिंग, CI और केवल डॉक्स परिवर्तनों के लिए उपयोगी होता है। सिद्धांत: स्पेक्स व्यवहार का वर्णन करते हैं, इसलिए यदि व्यवहार नहीं बदला है तो स्पेक भी नहीं बदलना चाहिए। कॉन्सेप्ट्स देखें।

रेसिपी 6: स्टेप बाय स्टेप कंट्रोल (विस्तारित कमांड्स)

इसका उपयोग कब करें: जब कोई जटिल या जोखिम भरा परिवर्तन है जिसमें आप आगे बढ़ने से पहले प्रत्येक आर्टिफैक्ट की समीक्षा करना चाहते हैं।

कोर /opsx:propose सभी चीजों को एक बार में ड्राफ्ट करता है। जब आप एक बार में एक स्टेप लेना पसंद करें, तो विस्तारित कमांड्स को ऑन करें:

$ openspec config profile      # विस्तारित वर्कफ्लो का चयन करें
$ openspec update              # उन्हें इस प्रोजेक्ट पर लागू करें

अब आप इंक्रिमेंटली स्कैफोल्ड और बिल्ड कर सकते हैं:

आप: /opsx:new add-2fa

एआई:  openspec/changes/add-2fa/ बनाया गया। प्रस्ताव बनाने के लिए तैयार।

आप: /opsx:continue

एआई:  proposal.md बनाया गया। अब उपलब्ध: स्पेक्स, डिजाइन।

आप: /opsx:continue

एआई:  specs/auth/spec.md बनाया गया। अब उपलब्ध: डिजाइन।

जैसे ही कोई आर्टिफैक्ट लैंड हो, उसकी समीक्षा करें, स्वतंत्र रूप से संपादित करें, और जब आप संतुष्ट हों तो आगे बढ़ें। जब आप बाकी को एक बार में ड्राफ्ट करना चाहें, तो /opsx:ff बचे हुए प्लानिंग आर्टिफैक्ट्स को फास्ट-फॉरवर्ड करता है। आर्काइव करने से पहले, /opsx:verify जांचता है कि कार्यान्वयन वास्तव में स्पेक्स से मेल खाता है या नहीं। वर्कफ्लो देखें।

रेसिपी 7: पूरे लूप को हाथ से सीखना

इसका उपयोग कब करें: जब आपने OpenSpec इंस्टॉल कर लिया है और किसी खिलौने उदाहरण के बजाय अपने स्वयं के कोड पर वर्कफ्लो को अनुभव करना चाहते हैं।

विस्तारित कमांड्स को ऑन करें (रेसिपी 6 देखें), फिर:

आप: /opsx:onboard

एआई:  OpenSpec में आपका स्वागत है! मैं आपके वास्तविक कोडबेस का उपयोग करके एक पूरे परिवर्तन के माध्यम से आपका साथ दूंगा।
     चलिए मैं एक छोटे, सुरक्षित सुधार के लिए स्कैन करता हूं जिसे हम साथ मिलकर कर सकते हैं...

/opsx:onboard एक वास्तविक (छोटे) सुधार को ढूंढता है, इसके लिए एक परिवर्तन बनाता है, इसे लागू करता है, और इसे आर्काइव करता है, हर कदम की कहानी सुनाता है। इसमें 15 से 30 मिनट लगते हैं और आपको एक वास्तविक परिवर्तन छोड़ जाता है जिसे आप रख सकते हैं या फेंक सकते हैं। यह सीखने का सबसे आसान तरीका है। कमांड्स देखें।

टर्मिनल से अपना काम जांचें

किसी भी समय, अपने टर्मिनल से, आप चीजों की स्थिति की जांच कर सकते हैं:

$ openspec list                      # एक्टिव परिवर्तन
$ openspec show add-dark-mode        # एक परिवर्तन का विस्तार से विवरण
$ openspec validate add-dark-mode    # संरचना की जांच करें
$ openspec view                      # इंटरैक्टिव डैशबोर्ड

ये रीड-एंड-इंस्पेक्ट टूल्स हैं। प्रस्तावित करना और बिल्ड करना अभी भी चैट में स्लैश कमांड्स के माध्यम से होता है। पूरा विवरण CLI रेफरेंस में उपलब्ध है।

आगे कहां जाएं

• पहले एक्सप्लोर करें: जब आप अनिश्चित हों तो शुरुआत करने का अनुशंसित तरीका
• वर्कफ्लो: ऊपर दिए गए पैटर्न, प्रत्येक का उपयोग कब करें इस पर निर्णय मार्गदर्शन के साथ
• कमांड्स: हर स्लैश कमांड का विस्तार से विवरण
• गेटिंग स्टार्टेड: पहले परिवर्तन करने का मानक वॉकथ्रू
• कॉन्सेप्ट्स: टुकड़े क्यों इस तरह एक दूसरे के साथ फिट होते हैं