एक मौजूदा प्रोजेक्ट में OpenSpec का उपयोग करना

शुरुआत में आप अपने पूरे कोडबेस को दस्तावेज़ित नहीं करते हैं। आप केवल उन चीजों के लिए स्पेसिफिकेशन्स लिखते हैं जिन्हें आप बदलने वाले हैं। यह मौजूदा प्रोजेक्ट पर OpenSpec अपनाने के बारे में जानने वाली सबसे महत्वपूर्ण बात है, और यही कारण है कि OpenSpec को ब्राउनफील्ड-फर्स्ट (brownfield-first) बनाया गया है।

एक आम चिंता कुछ ऐसी लगती है: "मेरा ऐप 80,000 लाइनों पुराना है। क्या मुझे OpenSpec उपयोगी होने से पहले इसके लिए सब कुछ लिखना होगा?" नहीं। आप ऐसा पसंद नहीं करेंगे, और हम भी नहीं करते। OpenSpec एक बार में एक बदलाव के साथ आपके स्पेसिफिकेशन्स को बढ़ाता है। आपका पहला बदलाव उस स्लाइस (slice) को दस्तावेज़ित करता है जिसे वह छूता है, अगला बदलाव अपने स्लाइस को दस्तावेज़ित करता है, और महीनों में आपके स्पेसिफिकेशन्स स्वाभाविक रूप से उस काम के चारों ओर भर जाते हैं जो आप वास्तव में करते हैं।

यह गाइड आपको बिना "पूरे महासागर" (boiling the ocean) को समझने के पहले दिन ही शुरुआत करने का तरीका बताती है।

तीस सेकंड वाला संस्करण

$ cd your-existing-project
$ openspec init          # adds openspec/ and your AI tool's commands

फिर, अपने AI चैट में:

/opsx:explore            # optional: have the AI read the area you'll touch
/opsx:propose <a real, small change you actually need>
/opsx:apply
/opsx:archive

अब आपके स्पेसिफिकेशन्स ठीक उस सिस्टम के हिस्से का वर्णन करते हैं जिसे बदलाव ने छुआ है, और कुछ भी नहीं। यह सही है। आप बाकी 80,000 लाइनों की चिंता करना बंद कर सकते हैं।

डेल्टा-फर्स्ट क्यों संपूर्ण ट्रिक है

OpenSpec परिवर्तन डेल्टा के रूप में लिखे जाते हैं: ADDED, MODIFIED, REMOVED। एक डेल्टा बताता है कि वर्तमान व्यवहार के सापेक्ष क्या बदल रहा है, न कि पूरे सिस्टम के बारे में।

यह ठीक वही है जिसकी कोडिंग (brownfield) कार्य को आवश्यकता होती है।आप शायद ही शून्य से शुरुआत कर रहे हों। आप एक फ़ील्ड जोड़ रहे हैं, एक रीडायरेक्ट ठीक कर रहे हैं, या टाइमआउट को कस रहे हैं। एक डेल्टा आपको पहले इसके आसपास की हर चीज का 40-पृष्ठों का स्पेसिफिकेशन लिखने के बजाय उस एक बदलाव को सटीक रूप से निर्दिष्ट करने देता है।

इसलिए आपकी openspec/specs/ डायरेक्टरी भरी हुई और संपूर्ण शुरू नहीं होती है। यह लगभग खाली शुरू होती है और जमा होती जाती है। प्रत्येक आर्काइव किया गया परिवर्तन अपना डेल्टा मर्ज करता है। auth/ के लिए स्पेसिफिकेशन तभी व्यापक बनता है जब आप कई auth बदलाव कर चुके होते हैं, और यही वह समय होता है जब आप इसे व्यापक चाहते हैं।

यदि आप गहरी यांत्रिकी (deeper mechanics) जानना चाहते हैं, तो Concepts: Delta Specs देखें।

एक वास्तविक कोडबेस पर आपका पहला बदलाव

कुछ छोटा और वास्तविक चुनें। कोई खिलौना, कोई पुनर्लेखन (rewrite) नहीं। एक ऐसा बदलाव जो आप वैसे भी इस सप्ताह करने वाले थे। छोटे पहले के बदलाव आपको कम जोखिमों के साथ वर्कफ़्लो सिखाते हैं।

चरण 1: AI को प्रासंगिक क्षेत्र पढ़ने दें। यह वह जगह है जहाँ /opsx:explore किसी अपरिचित या बड़े कोडबेस पर अपनी उपयोगिता साबित करता है। इसे उस हिस्से की ओर इंगित करें जिसे आप छूने वाले हैं और कुछ प्रस्तावित करने से पहले चीजों के काम करने के तरीके को मैप करने दें।

You: /opsx:explore

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

You: मुझे अपने पब्लिक API पर रेट लिमिटिंग जोड़नी है, लेकिन मुझे यकीन नहीं है कि अनुरोध वर्तमान में मिडलवेयर (middleware) के माध्यम से कैसे प्रवाहित होते हैं।

AI:  मुझे इसे ट्रेस करने दें... [router, middleware stack, और config को पढ़ता है]
     अनुरोध Express पर हिट करते हैं, auth middleware से गुजरते हैं, फिर आपके controllers तक जाते हैं। आज कोई रेट-लिमिटिंग लेयर नहीं है। सबसे स्वच्छ सम्मिलन बिंदु (insertion point) auth के ठीक बाद एक मिडलवेयर है। क्या मैं इसे स्कोप करूँ?

ध्यान दें कि AI अब आपकी वास्तविक संरचना को समझता है, इसलिए जो प्रस्ताव यह लिखता है वह एक सामान्य टेम्पलेट पर नहीं, बल्कि आपके कोड में फिट होगा। एक बड़े कोडबेस पर, यह अकेली आदत सबसे अधिक दर्द बचाती है। Explore First देखें।

चरण 2: बदलाव प्रस्तावित करें। प्रस्ताव और उसका डेल्टा स्पेसिफिकेशन केवल इसी बदलाव को कैप्चर करते हैं।

You: /opsx:propose add-api-rate-limiting

चरण 3: /opsx:apply और /opsx:archive के साथ बिल्ड करें और आर्काइव करें, जैसा कि किसी भी बदलाव के साथ किया जाता है। आर्काइव करने के बाद, आपके पास रेट-लिमिटिंग व्यवहार के लिए एक वास्तविक स्पेसिफिकेशन होता है, जो वैसे भी आवश्यक एक बदलाव से पैदा हुआ है।

क्या आप एक निर्देशित टूर (guided tour) पसंद करते हैं? onboard का उपयोग करें

यदि आप अपने कोड पर नरेशन (narration) के साथ पूरे लूप को होते हुए देखना पसंद करते हैं, तो विस्तारित कमांड /opsx:onboard ठीक यही करता है: यह आपके कोडबेस को एक छोटे, सुरक्षित सुधार के लिए स्कैन करता है, फिर आपको इसे प्रस्तावित करने, बनाने और आर्काइव करने के माध्यम से मार्गदर्शन करता है, हर कदम की व्याख्या करता है।

पहले विस्तारित कमांड चालू करें:

$ openspec config profile      # select the expanded workflows
$ openspec update              # apply them to this project

फिर चैट में:

/opsx:onboard

यह एक वास्तविक प्रोजेक्ट पर सबसे कोमल परिचय है, और यह आपको एक वास्तविक (छोटा) बदलाव के साथ छोड़ता है जिसे आप रख सकते हैं या खारिज कर सकते हैं। Commands: /opsx:onboard देखें।

"लेकिन मेरे पास पहले से ही आवश्यकता दस्तावेज़ (requirements docs) हैं"

हो सकता है कि आपके पास एक PRD, एक SRS, एक औपचारिक स्पेसिफिकेशन हो, यहाँ तक कि TLA+ मॉडल भी हों। अच्छा है। आप उन्हें पूरी तरह से आयात नहीं करते हैं, और न ही आप उन्हें फेंक देते हैं।

मौजूदा दस्तावेज़ों को एक्सप्लोरेशन के लिए स्रोत सामग्री के रूप में मानें, न कि परिवर्तित करने के लिए स्पेसिफिकेशन्स के रूप में। जब आप कोई बदलाव शुरू करते हैं, तो AI पर प्रासंगिक अनुभाग पेस्ट करें या इंगित करें, और इसे उससे एक केंद्रित OpenSpec डेल्टा बनाने दें। यह डेल्टा उस व्यवहार को कैप्चर करता है जिसे आप अभी बदल रहे हैं, OpenSpec के परीक्षण योग्य आवश्यकता-और-परिदृश्य (testable requirement-and-scenario) रूप में। आपके मूल दस्तावेज़ पृष्ठभूमि में वहीं रहते हैं।

ईमानदार कारण: OpenSpec स्पेसिफिकेशन्स जानबूझकर व्यवहार-पहले (behavior-first) होते हैं और परिवर्तनों तक सीमित होते हैं। एक 40-पृष्ठों का PRD एक अलग कलाकृति है जिसका एक अलग काम है। एक बार की थोक रूपांतरण (bulk conversion) से आमतौर पर एक बड़ा, पुराना स्पेसिफिकेशन बनता है जिस पर कोई भरोसा नहीं करता। वास्तविक बदलावों से स्पेसिफिकेशन्स को बढ़ने देने से वे सटीक बने रहते हैं।

You: /opsx:explore
You: यह हमारे PRD का चेकआउट के बारे में अनुभाग है। मैं "गेस्ट चेकआउट" आवश्यकता को लागू कर रहा हूँ।
     [प्रासंगिक आवश्यकता पेस्ट करें]
AI:  [पढ़ता है, स्पष्ट करने वाले प्रश्न पूछता है, फिर बदलाव को स्कोप करने में मदद करता है]
You: /opsx:propose add-guest-checkout

एक बड़े कोडबेस में स्पेसिफिकेशन्स को व्यवस्थित करना

स्पेसिफिकेशन्स openspec/specs/ के तहत रहते हैं, जिन्हें डोमेन द्वारा समूहीकृत किया जाता है: एक तार्किक क्षेत्र जो उस तरह से मेल खाता है जिस तरह से आपकी टीम सिस्टम के बारे में सोचती है। आपको शुरुआत में पूरी वर्गीकरण (taxonomy) डिजाइन करने की आवश्यकता नहीं है। जब उस क्षेत्र में आपका पहला बदलाव आवश्यक हो तो एक डोमेन फ़ोल्डर बनाएं।

डोमेन को स्लाइस करने के सामान्य तरीके:

• फ़ीचर क्षेत्र द्वारा: auth/, payments/, search/
• घटक (component) द्वारा: api/, frontend/, workers/
• बाउंडेड कॉन्टेक्स्ट (bounded context) द्वारा: ordering/, fulfillment/, inventory/

जो कुछ भी एक नौसिखिए को सिर हिलाने के लिए मजबूर करे, उसे चुनें। आप बाद में सुधार कर सकते हैं। Concepts: Specs देखें।

मोनोरेपोज़ और ऐसे काम जो कई रिपॉजिटरी तक फैले हों

एक मोनोरेपो (monorepo) के लिए, सबसे सरल मॉडल रेपो रूट पर एक openspec/ डायरेक्टरी है, जिसमें डोमेन आपके पैकेजों या सेवाओं से मेल खाते हैं। यह अधिकांश टीमों को कवर करता है।

यदि आपका काम वास्तव में कई रिपॉजिटरी (या कई पैकेज जिन्हें आप अलग-अलग मानते हैं) तक फैला हुआ है, तो OpenSpec में एक बीटा स्टोर्स सुविधा है: योजना अपनी खुद की स्टैंडअलोन रेपो में रहती है जिसे आपकी किसी भी कोड रेपो द्वारा संदर्भित किया जा सकता है, ताकि योजना को किसी एक रेपो की openspec/ फ़ोल्डर के अंदर रहने की आवश्यकता न हो। यह बीटा है, इसलिए इसके कमांड और स्थिति (state) को विकसित होते हुए मानें। मानसिक मॉडल और सबसे छोटे उपयोगी रास्ते के लिए Stores User Guide से शुरुआत करें।

कुछ ईमानदार सावधानियां

• सब कुछ बैकफिल करने की इच्छा का विरोध करें। ऐसे कोड के लिए स्पेसिफिकेशन्स लिखना जिसे आप बदल नहीं रहे हैं, उत्पादक लगता है और आमतौर पर ऐसा नहीं होता। वे स्पेसिफिकेशन पुराने हो जाते हैं, क्योंकि कुछ भी उन्हें वास्तविकता को ट्रैक करने के लिए मजबूर नहीं करता। वास्तविक बदलावों को अपने स्पेसिफिकेशन्स चलाने दें।
• शुरुआती बदलाव छोटे रखें। आपके पहले कुछ बदलाव शिपिंग जितना ही सीखने की लय (rhythm) के बारे में हैं। एक तंग स्कोप लूप को तेज बनाता है और सबक सस्ते होते हैं।
• git में openspec/ कमिट करें। आपके स्पेसिफिकेशन्स और आर्काइव उस कोड के साथ संस्करण नियंत्रण (version control) में होने चाहिए जिसका वे वर्णन करते हैं।
• AI को संदर्भ दें। एक बड़े कोडबेस पर मजबूत परंपराओं के साथ, openspec/config.yaml में context: भरें ताकि हर प्रस्ताव आपके स्टैक और पैटर्न का सम्मान करे। Customization देखें।

आगे कहाँ जाना है

• Explore First - बदलाव करने से पहले कोड को समझने की मुख्य आदत
• Getting Started - पूर्ण पहला-बदलाव वॉकथ्रू (walkthrough)
• Editing & Iterating on a Change - सीखते समय एक बदलाव को समायोजित करना
• Concepts: Delta Specs - क्यों डेल्टा ब्राउनफील्ड कार्य को स्वच्छ बनाते हैं
• Customization - OpenSpec को आपके प्रोजेक्ट की परंपराएं सिखाना