एक नज़र में मुख्य अवधारणाएँ

OpenSpec आपके और आपके AI के बीच एक हल्का समझौता परत (lightweight agreement layer) है। आप लिख देते हैं कि बदलाव को क्या करना चाहिए, AI विवरण तैयार करता है, आप दोनों एक ही योजना को देखते हैं, और तभी कोड लिखा जाता है। यह पेज एक स्क्रीन पर संपूर्ण मानसिक मॉडल (mental model) प्रस्तुत करता है। जब आपको विस्तृत संस्करण चाहिए, तो Concepts देखें।

यहाँ पाँच शब्दों में पूरी विचार प्रक्रिया दी गई है: पहले सहमत हों, फिर आत्मविश्वास के साथ निर्माण करें।

पाँच विचार

OpenSpec में सब कुछ पाँच अवधारणाओं से बना है। इन्हें सीख लें और बाकी विवरण स्वतः ही समझ आ जाएगा।

1. Specs सत्य हैं। एक spec बताता है कि आपकी प्रणाली अभी कैसे व्यवहार करती है। यह openspec/specs/ में रहता है, जिसे डोमेन (auth/, payments/, ui/) के अनुसार व्यवस्थित किया गया है। Specs आवश्यकताओं ("सिस्टम को 30 मिनट के बाद सेशन समाप्त करना चाहिए") और परिदृश्यों (concrete given/when/then उदाहरण) से बने होते हैं। Specs को "यह सॉफ्टवेयर क्या करता है?" इस प्रश्न का एकल सहमत उत्तर समझें।

2. एक बदलाव कार्य की एक इकाई है। जब आप व्यवहार में कुछ जोड़ना, संशोधित करना या हटाना चाहते हैं, तो आप एक बदलाव (change) बनाते हैं: openspec/changes/ में एक फ़ोल्डर जो उस काम के बारे में सब कुछ एक ही स्थान पर रखता है। इसमें एक प्रस्ताव, एक डिज़ाइन, कार्यों की सूची और spec संपादन शामिल होते हैं। एक बदलाव, एक फ़ोल्डर, एक सुविधा।

3. Delta specs बताते हैं कि क्या बदल रहा है, न कि पूरी दुनिया को। एक बदलाव के अंदर, आप पूरा spec फिर से नहीं लिखते हैं। आप एक छोटा delta लिखते हैं: इस आवश्यकता को ADDED किया गया, उस पर MODIFIED किया गया, इस अन्य को REMOVED कर दिया गया। यही वह तरकीब है जो OpenSpec को केवल ग्रीन-फील्ड (नए) सिस्टम ही नहीं, बल्कि मौजूदा सिस्टमों को संपादित करने में भी अच्छा बनाती है। आप गंतव्य स्थान (destination) का नहीं, अंतर (diff) का वर्णन करते हैं।

4. Artifacts एक दूसरे पर निर्मित होते हैं। एक बदलाव में कुछ दस्तावेज़ होते हैं, जिन्हें प्राकृतिक क्रम में बनाया जाता है, और हर एक अगले को पोषण देता है:

proposal ──► specs ──► design ──► tasks ──► implement
   why        what       how       steps      do it

आप कभी भी इनमें से किसी पर भी वापस जा सकते हैं। वे गेट (gate) नहीं, बल्कि सक्षमकर्ता (enablers) हैं। (इस बारे में और नीचे पढ़ें।)

5. Archiving बदलाव को सत्य में वापस डाल देता है। जब काम पूरा हो जाता है, तो आप बदलाव को archive कर देते हैं। इसके delta specs आपके मुख्य specs में विलय (merge) हो जाते हैं, और परिवर्तन फ़ोल्डर एक तारीख स्टैम्प के साथ changes/archive/ में चला जाता है। अब आपके specs नई वास्तविकता का वर्णन करते हैं, और आप अगले बदलाव के लिए तैयार हैं। चक्र पूरा होता है।

चित्र

┌─────────────────────────────────────────────────────────────────┐
│                          openspec/                              │
│                                                                 │
│   ┌──────────────────┐         ┌──────────────────────────┐    │
│   │     specs/       │         │        changes/          │    │
│   │                  │ ◄─────  │                          │    │
│   │ source of truth  │  merge  │ one folder per change    │    │
│   │ how things work  │  on     │ proposal · design ·      │    │
│   │ today            │ archive │ tasks · delta specs      │    │
│   └──────────────────┘         └──────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

दो फ़ोल्डर। specs/ वह है जो सत्य है। changes/ वह है जिसे आप प्रस्तावित कर रहे हैं। Archiving एक प्रस्ताव को सत्य में ले जाता है।

वह लूप जिसे आप वास्तव में चलाएंगे

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

/opsx:explore                   →  (वैकल्पिक) पहले AI के साथ विचार करना
/opsx:propose add-dark-mode     →  AI प्रस्ताव, specs, डिज़ाइन, कार्य तैयार करता है
        (आप योजना को पढ़ते हैं और समायोजित करते हैं)
/opsx:apply                     →  AI इसे बनाता है, कार्यों की जाँच करता है
/opsx:archive                   →  specs अपडेट किए गए, बदलाव archive कर दिया गया

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

ये स्लैश कमांड हैं, जिन्हें आपके AI असिस्टेंट की चैट में टाइप किया जाता है। सेटअप (openspec init) आपके टर्मिनल में होता है। यदि यह विभाजन आपको नया लगता है, तो पहले How Commands Work पढ़ें; यह सबसे आम भ्रम का बिंदु है।

"सक्षमकर्ता, गेट नहीं"

यह वाक्यांश OpenSpec में हर जगह आता है, इसलिए इसका सरल शब्दों में क्या मतलब है, यहाँ बताया गया है।

पुराने स्कूल के spec प्रक्रिया झरने (waterfalls) की तरह होते हैं: योजना पूरी करें, फिर आपको कार्यान्वयन करने की अनुमति है, और पीछे लौटना दर्दनाक होता है। OpenSpec इसे अस्वीकार करता है। proposal → specs → design → tasks का क्रम दिखाता है कि आगे क्या संभव हो सकता है, न कि आपको अगले क्या करना पड़ता है।

क्या आप कार्यान्वयन के दौरान पाते हैं कि डिज़ाइन गलत था? design.md को संपादित करें और जारी रखें। क्या महसूस होता है कि दायरे (scope) को छोटा होना चाहिए? प्रस्ताव को अपडेट करें। कुछ भी लॉक नहीं होता। निर्भरताएं केवल इसलिए मौजूद होती हैं ताकि AI के पास आवश्यक संदर्भ हो (आप specs पर आधारित अच्छे कार्य नहीं लिख सकते, न कि उन्हें सीमित करने के लिए)।

यहाँ ताकत ईमानदारी में है: वास्तविक काम गन्दा और पुनरावृत्ति वाला होता है, और OpenSpec इसे होने देता है। ट्रेडऑफ़ अनुशासन का है: क्योंकि कुछ भी आपको आगे बढ़ने के लिए मजबूर नहीं करता है, इसलिए यह आप पर निर्भर है कि आप बदलाव को फैलने देने के बजाय केंद्रित रखें। Workflows गाइड इसके लिए अच्छी आदतें प्रदान करता है।

यह छोटे ओवरहेड के लायक क्यों है

सीधी बात: OpenSpec एक कदम जोड़ता है। निर्माण करने से पहले आप एक छोटी योजना लिखते हैं। तो आपको इसके बदले में क्या मिलता है?

• आप गलत मोड़ लेने से पहले ही पकड़ लेते हैं, इससे पहले कि वे आपको लागत दें। एक पैराग्राफ के प्रस्ताव में गलतफहमी को ठीक करना मुफ्त है। इसे AI द्वारा 400 लाइनें लिखने के बाद ठीक करना नहीं है।
• योजना और कोड उसी repo में रहते हैं। छह महीने बाद भी, spec आपको (और अगले AI सत्र को) बताता है कि सिस्टम जिस तरह से काम करता है वह क्यों करता है।
• बदलावों की समीक्षा की जा सकती है। एक बदलाव फ़ोल्डर एक व्यवस्थित पैकेज होता है: प्रस्ताव पढ़ें, deltas पर नज़र डालें, कार्यों की जाँच करें। चैट इतिहास में पुरातत्व विज्ञान (archaeology) नहीं करना पड़ेगा।
• यह मौजूदा कोडबेस में फिट बैठता है। Deltas का मतलब है कि आप पूरे दस्तावेज़ीकरण के बिना 50,000 लाइन वाले ऐप में बदलाव निर्दिष्ट कर सकते हैं।

और ईमानदार ट्रेडऑफ़: एक वास्तव में तुच्छ (trivial) एक-पंक्ति सुधार के लिए, यह समारोह (ceremony) शायद फल न दे, और यह ठीक है। OpenSpec हल्का होने के लिए डिज़ाइन किया गया है, लेकिन यह मुफ्त नहीं है। इसका उपयोग वहाँ करें जहाँ समझौते का महत्व हो, जो AI के साथ काम करने पर अधिकांश समय होता है जो आत्मविश्वास से वह सब कुछ बना देगा जिसके बारे में आपने अस्पष्ट रूप से पूछा था।

आगे कहाँ जाएँ

• नए हैं? Getting Started पहले बदलाव को पूरी तरह से समझाता है।
• अभी तक यह तय नहीं किया है कि क्या बनाना है? Explore First वह जगह है जहाँ आपको शुरुआत करनी चाहिए।
• कमांड कहाँ चलते हैं, इस बारे में भ्रमित हैं? How Commands Work।
• ऊपर दिए गए हर चीज़ का गहन संस्करण चाहते हैं? Concepts।
• उदाहरणों से सीखें? Examples & Recipes।
• किसी शब्द की परिभाषा चाहिए? Glossary।