अवधारणाएँ
यह मार्गदर्शिका OpenSpec के पीछे के मूल विचारों को समझाती है और बताती है कि वे एक साथ कैसे काम करते हैं। व्यावहारिक उपयोग के लिए, शुरुआत कैसे करें और कार्यप्रवाह देखें।
दर्शन
OpenSpec चार सिद्धांतों के इर्द-गिर्द बनाया गया है:
fluid not rigid — no phase gates, work on what makes sense
iterative not waterfall — learn as you build, refine as you go
easy not complex — lightweight setup, minimal ceremony
brownfield-first — works with existing codebases, not just greenfieldये सिद्धांत क्यों महत्वपूर्ण हैं
लचीला, न कि कठोर। पारंपरिक स्पेसिफिकेशन सिस्टम आपको चरणों में बांध देते हैं: पहले आप योजना बनाते हैं, फिर कार्यान्वयन करते हैं, और फिर काम हो जाता है। OpenSpec अधिक लचीला है — आप अपने काम के लिए जो भी क्रम उचित हो, उसमें कलाकृतियाँ बना सकते हैं।
आवर्ती, न कि जलप्रपात शैली का। आवश्यकताएँ बदलती हैं। समझ गहरी होती जाती है। शुरुआत में जो दृष्टिकोण अच्छा लगा, वह कोडबेस देखने के बाद शायद उतना उपयुक्त न रहे। OpenSpec इस वास्तविकता को अपनाता है।
सरल, न कि जटिल। कुछ स्पेसिफिकेशन फ्रेमवर्क को विस्तृत सेटअप, कठोर प्रारूपों, या भारी-भरकम प्रक्रियाओं की आवश्यकता होती है। OpenSpec आपके रास्ते में नहीं आता। सेकंडों में इनिशियलाइज़ करें, तुरंत काम शुरू करें, और केवल आवश्यकता पड़ने पर ही अनुकूलित करें।
ब्राउनफ़ील्ड-पहले। अधिकांश सॉफ़्टवेयर कार्य शुरू से नहीं बनते — वे मौजूदा सिस्टम को संशोधित करने का होता है। OpenSpec का डेल्टा-आधारित दृष्टिकोण मौजूदा व्यवहार में बदलावों को निर्दिष्ट करना आसान बनाता है, न कि केवल नए सिस्टम का वर्णन करना।
समग्र दृष्टिकोण
OpenSpec आपके कार्य को दो मुख्य क्षेत्रों में व्यवस्थित करता है:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ सत्य का स्रोत │◄─────│ प्रस्तावित संशोधन │ │
│ │ आपका सिस्टम वर्तमान │ merge│ प्रत्येक परिवर्तन = एक फ़ोल्डर │ │
│ │ में कैसे काम करता है │ │ कलाकृतियाँ + डेल्टा शामिल हैं │ │
│ │ │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘विनिर्देश (Specs) सत्य का स्रोत हैं — वे बताते हैं कि आपका सिस्टम वर्तमान में कैसे व्यवहार करता है।
परिवर्तन (Changes) प्रस्तावित संशोधन हैं — जब तक आप उन्हें मर्ज करने के लिए तैयार नहीं हो जाते, तब तक वे अलग-अलग फ़ोल्डरों में रहते हैं।
यह अलगाव महत्वपूर्ण है। आप बिना किसी टकराव के कई परिवर्तनों पर एक साथ काम कर सकते हैं। आप मुख्य विनिर्देशों को प्रभावित करने से पहले किसी परिवर्तन की समीक्षा कर सकते हैं। और जब आप किसी परिवर्तन को संग्रहित करते हैं, तो उसके डेल्टा सत्य के स्रोत में स्वच्छ रूप से मर्ज हो जाते हैं।
विनिर्देश (Specs)
विनिर्देश संरचित आवश्यकताओं और परिदृश्यों का उपयोग करके आपके सिस्टम के व्यवहार का वर्णन करते हैं।
संरचना
openspec/specs/
├── auth/
│ └── spec.md # प्रमाणीकरण व्यवहार
├── payments/
│ └── spec.md # भुगतान प्रसंस्करण
├── notifications/
│ └── spec.md # सूचना प्रणाली
└── ui/
└── spec.md # UI व्यवहार और थीमविनिर्देशों को डोमेन के अनुसार व्यवस्थित करें — तार्किक समूह जो आपके सिस्टम के लिए समझ में आते हैं। सामान्य पैटर्न:
- सुविधा क्षेत्र के अनुसार:
auth/,payments/,search/ - घटक के अनुसार:
api/,frontend/,workers/ - सीमांकित संदर्भ के अनुसार:
ordering/,fulfillment/,inventory/
विनिर्देश प्रारूप
एक विनिर्देश में आवश्यकताएँ होती हैं, और प्रत्येक आवश्यकता में परिदृश्य होते हैं:
markdown
# प्रमाणीकरण विनिर्देश
## उद्देश्य
एप्लिकेशन के लिए प्रमाणीकरण और सत्र प्रबंधन।
## आवश्यकताएँ
### आवश्यकता: उपयोगकर्ता प्रमाणीकरण
सिस्टम को सफल लॉगिन पर एक JWT टोकन जारी करना चाहिए।
#### परिदृश्य: मान्य क्रेडेंशियल्स
- दिया गया एक उपयोगकर्ता मान्य क्रेडेंशियल्स के साथ
- जब उपयोगकर्ता लॉगिन फ़ॉर्म सबमिट करता है
- तब एक JWT टोकन लौटाया जाता है
- और उपयोगकर्ता को डैशबोर्ड पर रीडायरेक्ट किया जाता है
#### परिदृश्य: अमान्य क्रेडेंशियल्स
- दिया गया अमान्य क्रेडेंशियल्स
- जब उपयोगकर्ता लॉगिन फ़ॉर्म सबमिट करता है
- तब एक त्रुटि संदेश प्रदर्शित होता है
- और कोई टोकन जारी नहीं किया जाता है
### आवश्यकता: सत्र समाप्ति
सिस्टम को 30 मिनट की निष्क्रियता के बाद सत्रों को समाप्त करना चाहिए।
#### परिदृश्य: निष्क्रिय टाइमआउट
- दिया गया एक प्रमाणित सत्र
- जब बिना गतिविधि के 30 मिनट बीत जाते हैं
- तब सत्र अमान्य हो जाता है
- और उपयोगकर्ता को पुनः प्रमाणित करना होगामुख्य तत्व:
| तत्व | उद्देश्य |
|---|---|
## उद्देश्य | इस विनिर्देश के डोमेन का उच्च-स्तरीय विवरण |
### आवश्यकता: | एक विशिष्ट व्यवहार जो सिस्टम के पास होना चाहिए |
#### परिदृश्य: | आवश्यकता का कार्यान्वयन में एक ठोस उदाहरण |
| SHALL/MUST/SHOULD | RFC 2119 कीवर्ड जो आवश्यकता की शक्ति दर्शाते हैं |
विनिर्देशों को इस तरह संरचित क्यों करें
आवश्यकताएँ "क्या" हैं — वे बताती हैं कि सिस्टम को क्या करना चाहिए, कार्यान्वयन निर्दिष्ट किए बिना।
परिदृश्य "कब" हैं — वे ठोस उदाहरण प्रदान करते हैं जिन्हें सत्यापित किया जा सकता है। अच्छे परिदृश्य:
- परीक्षण योग्य होते हैं (आप उनके लिए एक स्वचालित परीक्षण लिख सकते हैं)
- हैप्पी पाथ और एज केस दोनों को कवर करते हैं
- दिया गया/जब/तब या समान संरचित प्रारूप का उपयोग करते हैं
RFC 2119 कीवर्ड (SHALL, MUST, SHOULD, MAY) इरादे को संवाद करते हैं:
- MUST/SHALL — पूर्ण आवश्यकता
- SHOULD — अनुशंसित, लेकिन अपवाद मौजूद हैं
- MAY — वैकल्पिक
विनिर्देश क्या है (और क्या नहीं)
विनिर्देश एक व्यवहार अनुबंध है, कार्यान्वयन योजना नहीं।
अच्छी विनिर्देश सामग्री:
- उपयोगकर्ताओं या डाउनस्ट्रीम सिस्टम द्वारा निर्भर किया जाने वाला अवलोकन योग्य व्यवहार
- इनपुट, आउटपुट, और त्रुटि स्थितियाँ
- बाहरी बाधाएँ (सुरक्षा, गोपनीयता, विश्वसनीयता, संगतता)
- परिदृश्य जिन्हें परीक्षण या स्पष्ट रूप से सत्यापित किया जा सकता है
विनिर्देशों में इनसे बचें:
- आंतरिक क्लास/फ़ंक्शन नाम
- लाइब्रेरी या फ्रेमवर्क चयन
- चरण-दर-चरण कार्यान्वयन विवरण
- विस्तृत निष्पादन योजनाएँ (वे
design.mdयाtasks.mdमें होनी चाहिए)
त्वरित परीक्षण:
- यदि कार्यान्वयन बाहरी रूप से दिखाई देने वाले व्यवहार को बदले बिना बदला जा सकता है, तो यह संभवतः विनिर्देश में नहीं होना चाहिए।
इसे हल्का रखें: प्रगतिशील कठोरता
OpenSpec नौकरशाही से बचने का प्रयास करता है। सबसे हल्के स्तर का उपयोग करें जो अभी भी परिवर्तन को सत्यापन योग्य बनाता है।
लाइट विनिर्देश (डिफ़ॉल्ट):
- संक्षिप्त व्यवहार-प्रथम आवश्यकताएँ
- स्पष्ट दायरा और गैर-लक्ष्य
- कुछ ठोस स्वीकृति जाँचें
पूर्ण विनिर्देश (उच्च जोखिम के लिए):
- टीमों या रेपो के बीच परिवर्तन
- API/अनुबंध परिवर्तन, माइग्रेशन, सुरक्षा/गोपनीयता चिंताएँ
- परिवर्तन जहाँ अस्पष्टता के कारण महंगा पुनर्कार्य होने की संभावना है
अधिकांश परिवर्तन लाइट मोड में रहने चाहिए।
मानव + एजेंट सहयोग
कई टीमों में, मानव अन्वेषण करते हैं और एजेंट कलाकृतियाँ तैयार करते हैं। इच्छित लूप है:
- मानव इरादा, संदर्भ और बाधाएँ प्रदान करता है।
- एजेंट इसे व्यवहार-प्रथम आवश्यकताओं और परिदृश्यों में बदलता है।
- एजेंट कार्यान्वयन विवरण को
design.mdऔरtasks.mdमें रखता है,spec.mdमें नहीं। - सत्यापन कार्यान्वयन से पहले संरचना और स्पष्टता की पुष्टि करता है।
यह विनिर्देशों को मानवों के लिए पठनीय और एजेंटों के लिए सुसंगत रखता है।
परिवर्तन (Changes)
एक परिवर्तन आपके सिस्टम में एक प्रस्तावित संशोधन है, जिसे एक फ़ोल्डर के रूप में पैक किया जाता है जिसमें इसे समझने और लागू करने के लिए आवश्यक सब कुछ होता है।
परिवर्तन संरचना
openspec/changes/add-dark-mode/
├── proposal.md # क्यों और क्या
├── design.md # कैसे (तकनीकी दृष्टिकोण)
├── tasks.md # कार्यान्वयन चेकलिस्ट
├── .openspec.yaml # परिवर्तन मेटाडेटा (वैकल्पिक)
└── specs/ # डेल्टा विनिर्देश
└── ui/
└── spec.md # ui/spec.md में क्या बदल रहा हैप्रत्येक परिवर्तन स्व-निहित है। इसमें है:
- कलाकृतियाँ — दस्तावेज़ जो इरादा, डिज़ाइन और कार्यों को कैप्चर करते हैं
- डेल्टा विनिर्देश — विनिर्देश जो जोड़ा, संशोधित या हटाया जा रहा है
- मेटाडेटा — इस विशिष्ट परिवर्तन के लिए वैकल्पिक कॉन्फ़िगरेशन
परिवर्तन फ़ोल्डर क्यों हैं
एक परिवर्तन को फ़ोल्डर के रूप में पैक करने के कई लाभ हैं:
सब कुछ एक साथ। प्रस्ताव, डिज़ाइन, कार्य और विनिर्देश एक ही स्थान पर रहते हैं। अलग-अलग स्थानों में खोजने की आवश्यकता नहीं है।
समानांतर कार्य। कई परिवर्तन एक साथ मौजूद हो सकते हैं बिना टकराव के।
add-dark-modeपर काम करते समयfix-auth-bugभी प्रगति पर हो सकता है।स्वच्छ इतिहास। जब संग्रहित किया जाता है, तो परिवर्तन
changes/archive/में अपने पूर्ण संदर्भ के साथ स्थानांतरित हो जाते हैं। आप पीछे मुड़कर न केवल यह समझ सकते हैं कि क्या बदला, बल्कि क्यों बदला।समीक्षा-अनुकूल। एक परिवर्तन फ़ोल्डर की समीक्षा करना आसान है — इसे खोलें, प्रस्ताव पढ़ें, डिज़ाइन जाँचें, विनिर्देश डेल्टा देखें।
कलाकृतियाँ (Artifacts)
कलाकृतियाँ परिवर्तन के भीतर दस्तावेज़ हैं जो कार्य का मार्गदर्शन करते हैं।
कलाकृति प्रवाह
प्रस्ताव ──────► विनिर्देश ──────► डिज़ाइन ──────► कार्य ──────► कार्यान्वयन
│ │ │ │
क्यों क्या कैसे उठाने के
+ दायरा बदलाव दृष्टिकोण चरणकलाकृतियाँ एक-दूसरे पर बनती हैं। प्रत्येक कलाकृति अगले के लिए संदर्भ प्रदान करती है।
कलाकृति प्रकार
प्रस्ताव (proposal.md)
प्रस्ताव उच्च स्तर पर इरादा, दायरा और दृष्टिकोण को कैप्चर करता है।
markdown
# प्रस्ताव: डार्क मोड जोड़ें
## इरादा
उपयोगकर्ताओं ने रात्रि उपयोग के दौरान आँखों के तनाव को कम करने और सिस्टम प्राथमिकताओं से मेल खाने के लिए डार्क मोड विकल्प का अनुरोध किया है।
## दायरा
दायरे में:
- सेटिंग्स में थीम टॉगल
- सिस्टम प्राथमिकता पहचान
- localStorage में प्राथमिकता संग्रहित करना
दायरे से बाहर:
- कस्टम रंग थीम (भविष्य का कार्य)
- पृष्ठ-वार थीम ओवरराइड
## दृष्टिकोण
थीमिंग के लिए CSS कस्टम प्रॉपर्टीज़ का उपयोग करें और राज्य प्रबंधन के लिए React संदर्भ। पहली लोड पर सिस्टम प्राथमिकता का पता लगाएँ, मैनुअल ओवरराइड की अनुमति दें।प्रस्ताव को कब अपडेट करें:
- दायरा बदलता है (संकुचित या विस्तारित)
- इरादा स्पष्ट होता है (समस्या की बेहतर समझ)
- दृष्टिकोण मूलभूत रूप से बदलता है
विनिर्देश (specs/ में डेल्टा विनिर्देश)
डेल्टा विनिर्देश वर्तमान विनिर्देशों के सापेक्ष क्या बदल रहा है का वर्णन करते हैं। नीचे डेल्टा विनिर्देश देखें।
डिज़ाइन (design.md)
डिज़ाइन तकनीकी दृष्टिकोण और वास्तुकला निर्णयों को कैप्चर करता है।
markdown
# डिज़ाइन: डार्क मोड जोड़ें
## तकनीकी दृष्टिकोण
प्रॉप ड्रिलिंग से बचने के लिए React संदर्भ के माध्यम से थीम राज्य प्रबंधित।
CSS कस्टम प्रॉपर्टीज़ क्लास टॉगलिंग के बिना रनटाइम स्विचिंग को सक्षम बनाती हैं।
## वास्तुकला निर्णय
### निर्णय: कॉन्टेक्स्ट बनाम Redux
थीम स्टेट के लिए React Context का उपयोग कर रहे हैं क्योंकि:
- सरल बाइनरी स्टेट (लाइट/डार्क)
- कोई जटिल स्टेट ट्रांज़िशन नहीं
- Redux निर्भरता जोड़ने से बचते हैं
### निर्णय: CSS कस्टम प्रॉपर्टीज़
CSS-in-JS के बजाय CSS वेरिएबल्स का उपयोग कर रहे हैं क्योंकि:
- मौजूदा स्टाइलशीट के साथ काम करता है
- कोई रनटाइम ओवरहेड नहीं
- ब्राउज़र-नेटिव समाधान
## डेटा प्रवाह
```
ThemeProvider (context)
│
▼
ThemeToggle ◄──► localStorage
│
▼
CSS Variables (applied to :root)
```
## फ़ाइल परिवर्तन
- `src/contexts/ThemeContext.tsx` (नया)
- `src/components/ThemeToggle.tsx` (नया)
- `src/styles/globals.css` (संशोधित)
**डिज़ाइन को कब अपडेट करें:**
- कार्यान्वयन से पता चलता है कि दृष्टिकोण काम नहीं करेगा
- बेहतर समाधान मिल जाता है
- निर्भरताएँ या बाधाएँ बदल जाती हैं
#### कार्य (`tasks.md`)
कार्य **कार्यान्वयन चेकलिस्ट** हैं — चेकबॉक्स वाले ठोस कदम।
```markdown
# कार्य
## 1. थीम इन्फ्रास्ट्रक्चर
- [ ] 1.1 लाइट/डार्क स्टेट के साथ ThemeContext बनाएँ
- [ ] 1.2 रंगों के लिए CSS कस्टम प्रॉपर्टी जोड़ें
- [ ] 1.3 localStorage पर्सिस्टेंस लागू करें
- [ ] 1.4 सिस्टम प्रेफरेंस डिटेक्शन जोड़ें
## 2. UI कंपोनेंट्स
- [ ] 2.1 ThemeToggle कंपोनेंट बनाएँ
- [ ] 2.2 सेटिंग्स पेज में टॉगल जोड़ें
- [ ] 2.3 Header को क्विक टॉगल शामिल करने के लिए अपडेट करें
## 3. स्टाइलिंग
- [ ] 3.1 डार्क थीम कलर पैलेट परिभाषित करें
- [ ] 3.2 कंपोनेंट्स को CSS वेरिएबल्स का उपयोग करने के लिए अपडेट करें
- [ ] 3.3 एक्सेसिबिलिटी के लिए कंट्रास्ट अनुपात का परीक्षण करें
```
**कार्य की सर्वोत्तम प्रथाएँ:**
- शीर्षकों के अंतर्गत संबंधित कार्यों को समूहित करें
- पदानुक्रमित नंबरिंग का उपयोग करें (1.1, 1.2, आदि)
- कार्यों को इतना छोटा रखें कि वे एक सत्र में पूरे हो सकें
- जैसे-जैसे आप कार्य पूरे करते जाएँ, उन्हें चेक करते जाएँ
## डेल्टा स्पेक्स
डेल्टा स्पेक्स वह मुख्य अवधारणा है जो ब्राउनफ़ील्ड विकास के लिए OpenSpec को काम करने योग्य बनाती है। वे **क्या बदल रहा है** का वर्णन करते हैं, पूरी स्पेक को दोहराने के बजाय।
### प्रारूप
```markdown
# Auth के लिए डेल्टा
## जोड़े गए आवश्यकताएँ
### आवश्यकता: दो-कारक प्रमाणीकरण
सिस्टम को TOTP-आधारित दो-कारक प्रमाणीकरण का समर्थन करना **अनिवार्य** है।
#### परिदृश्य: 2FA नामांकन
- दिया गया है कि 2FA सक्षम नहीं है
- जब उपयोगकर्ता सेटिंग्स में 2FA सक्षम करता है
- तब प्रमाणक ऐप सेटअप के लिए एक QR कोड प्रदर्शित होता है
- और सक्रिय करने से पहले उपयोगकर्ता को एक कोड से सत्यापित करना होगा
#### परिदृश्य: 2FA लॉगिन
- दिया गया है कि 2FA सक्षम है
- जब उपयोगकर्ता मान्य क्रेडेंशियल प्रस्तुत करता है
- तब एक OTP चुनौती प्रस्तुत की जाती है
- और मान्य OTP के बाद ही लॉगिन पूरा होता है
## संशोधित आवश्यकताएँ
### आवश्यकता: सत्र समाप्ति
सिस्टम को 15 मिनट की निष्क्रियता के बाद सत्र समाप्त करना **अनिवार्य** है।
(पहले: 30 मिनट)
#### परिदृश्य: निष्क्रिय टाइमआउट
- दिया गया है कि एक प्रमाणित सत्र है
- जब गतिविधि के बिना 15 मिनट बीत जाते हैं
- तब सत्र अमान्य हो जाता है
## हटाई गई आवश्यकताएँ
### आवश्यकता: मुझे याद रखें
(2FA के पक्ष में अप्रचलित। उपयोगकर्ताओं को प्रत्येक सत्र में पुनः प्रमाणित करना चाहिए।)
```
### डेल्टा अनुभाग
| अनुभाग | अर्थ | संग्रह पर क्या होता है |
|---------|---------|------------------------|
| `## जोड़े गए आवश्यकताएँ` | नया व्यवहार | मुख्य स्पेक में जोड़ा जाता है |
| `## संशोधित आवश्यकताएँ` | बदला हुआ व्यवहार | मौजूदा आवश्यकता को प्रतिस्थापित करता है |
| `## हटाई गई आवश्यकताएँ` | अप्रचलित व्यवहार | मुख्य स्पेक से हटा दिया जाता है |
### डेल्टा क्यों, पूर्ण स्पेक्स क्यों नहीं
**स्पष्टता।** डेल्टा दिखाता है कि ठीक-ठीक क्या बदल रहा है। एक पूर्ण स्पेक पढ़ने पर, आपको इसे मानसिक रूप से वर्तमान संस्करण के विरुद्ध डिफ़ करना होगा।
**संघर्ष से बचाव।** दो परिवर्तन एक ही स्पेक फ़ाइल को छू सकते हैं बिना संघर्ष के, जब तक कि वे अलग-अलग आवश्यकताओं को संशोधित करते हैं।
**समीक्षा दक्षता।** समीक्षक परिवर्तन देखते हैं, अपरिवर्तित संदर्भ नहीं। महत्वपूर्ण चीज़ पर ध्यान केंद्रित करें।
**ब्राउनफ़ील्ड फ़िट।** अधिकांश कार्य मौजूदा व्यवहार को संशोधित करते हैं। डेल्टा संशोधनों को प्रथम-श्रेणी बनाते हैं, बाद की सोच नहीं।
## स्कीमाज़
स्कीमाज़ किसी वर्कफ़्लो के लिए आर्टिफ़ैक्ट प्रकार और उनकी निर्भरताएँ परिभाषित करते हैं।
### स्कीमाज़ कैसे काम करते हैं
```yaml
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # कोई निर्भरता नहीं, पहले बना सकते हैं
- id: specs
generates: specs/**/*.md
requires: [proposal] # बनाने से पहले proposal की आवश्यकता है
- id: design
generates: design.md
requires: [proposal] # specs के साथ समानांतर में बना सकते हैं
- id: tasks
generates: tasks.md
requires: [specs, design] # पहले specs और दोनों की आवश्यकता है
```
**आर्टिफ़ैक्ट्स एक निर्भरता ग्राफ़ बनाते हैं:**
```
proposal
(मूल नोड)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(निर्भरता: (निर्भरता:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(निर्भरता:
specs, design)
```
**निर्भरताएँ सक्षम करने वाले हैं, गेट नहीं।** वे दिखाते हैं कि क्या बनाना संभव है, न कि आपको अगला क्या बनाना है। यदि आपको इसकी आवश्यकता नहीं है तो आप design को छोड़ सकते हैं। आप specs को design से पहले या बाद में बना सकते हैं — दोनों केवल proposal पर निर्भर करते हैं।
### अंतर्निहित स्कीमाज़
**spec-driven** (डिफ़ॉल्ट)
स्पेक-संचालित विकास के लिए मानक वर्कफ़्लो:
```
proposal → specs → design → tasks → implement
```
सर्वोत्तम: अधिकांश फ़ीचर कार्य के लिए जहाँ आप कार्यान्वयन से पहले स्पेक्स पर सहमत होना चाहते हैं।
### कस्टम स्कीमाज़
अपनी टीम के वर्कफ़्लो के लिए कस्टम स्कीमाज़ बनाएँ:
```bash
# शुरू से बनाएँ
openspec schema init research-first
# या किसी मौजूदा को फ़ोर्क करें
openspec schema fork spec-driven research-first
```
**उदाहरण कस्टम स्कीमा:**
```yaml
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # पहले अनुसंधान करें
- id: proposal
generates: proposal.md
requires: [research] # अनुसंधान से सूचित proposal
- id: tasks
generates: tasks.md
requires: [proposal] # specs/design छोड़ें, सीधे कार्यों पर जाएँ
```
कस्टम स्कीमाज़ बनाने और उपयोग करने के पूर्ण विवरण के लिए [कस्टमाइज़ेशन](customization.md) देखें।
## संग्रह
संग्रह एक परिवर्तन को पूरा करता है, उसके डेल्टा स्पेक्स को मुख्य स्पेक्स में मिलाकर और इतिहास के लिए परिवर्तन को संरक्षित करके।
### संग्रह करने पर क्या होता है
```
संग्रह से पहले:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ मिलाना
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
संग्रह के बाद:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # अब 2FA आवश्यकताएँ शामिल हैं
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # इतिहास के लिए संरक्षित
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.md
```
### संग्रह प्रक्रिया
1. **डेल्टा मिलाएँ।** प्रत्येक डेल्टा स्पेक अनुभाग (जोड़े गए/संशोधित/हटाए गए) संबंधित मुख्य स्पेक पर लागू किया जाता है।
2. **संग्रह में ले जाएँ।** परिवर्तन फ़ोल्डर को कालानुक्रमिक क्रम के लिए तिथि उपसर्ग के साथ `changes/archive/` में ले जाया जाता है।
3. **संदर्भ संरक्षित करें।** सभी आर्टिफ़ैक्ट्स संग्रह में अक्षुण्ण रहते हैं। आप हमेशा पीछे देख सकते हैं कि परिवर्तन क्यों किया गया।
### संग्रह क्यों महत्वपूर्ण है
**स्वच्छ स्थिति।** सक्रिय परिवर्तन (`changes/`) केवल प्रगति में कार्य दिखाते हैं। पूर्ण कार्य रास्ते से हट जाते हैं।
**ऑडिट ट्रेल।** संग्रह हर परिवर्तन का पूर्ण संदर्भ संरक्षित करता है — न केवल क्या बदला, बल्कि क्यों बदला यह समझाने वाला proposal, कैसे बदला यह समझाने वाला design, और किया गया कार्य दिखाने वाले tasks।
**स्पेक विकास।** स्पेक्स परिवर्तनों के संग्रह के साथ जैविक रूप से बढ़ते हैं। प्रत्येक संग्रह अपने डेल्टा को मिलाता है, समय के साथ एक व्यापक विनिर्देश बनाता है।
## यह सब कैसे एक साथ फ़िट होता है
```
┌──────────────────────────────────────────────────────────────────────────────┐
│ OPENSPEC फ़्लो │
│ │
│ ┌────────────────┐ │
│ │ 1. शुरू करें │ /opsx:propose (कोर) या /opsx:new (विस्तारित) │
│ │ परिवर्तन │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. बनाएँ │ /opsx:ff या /opsx:continue (विस्तारित वर्कफ़्लो) │
│ │ आर्टिफ़ैक्ट्स │ proposal → specs → design → tasks बनाता है │
│ │ │ (स्कीमा निर्भरताओं के आधार पर) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. कार्यान्वयन │ /opsx:apply │
│ │ कार्य │ कार्यों पर काम करें, उन्हें चेक करें │
│ │ │◄──── जैसे-जैसे आप सीखते हैं आर्टिफ़ैक्ट्स अपडेट करें │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. सत्यापित │ /opsx:verify (वैकल्पिक) │
│ │ कार्य │ जाँचें कि कार्यान्वयन स्पेक्स से मेल खाता है │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. संग्रह │────►│ डेल्टा स्पेक्स मुख्य स्पेक्स में मिल जाते हैं │ │
│ │ परिवर्तन │ │ परिवर्तन फ़ोल्डर archive/ में चला जाता है │ │
│ └────────────────┘ │ स्पेक्स अब अद्यतन सत्य का स्रोत हैं │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
```
**सद्गुण चक्र:**
1. स्पेक्स वर्तमान व्यवहार का वर्णन करते हैं
2. परिवर्तन संशोधन प्रस्तावित करते हैं (डेल्टा के रूप में)
3. कार्यान्वयन परिवर्तनों को वास्तविक बनाता है
4. संग्रह डेल्टा को स्पेक्स में मिलाता है
5. स्पेक्स अब नए व्यवहार का वर्णन करते हैं
6. अगला परिवर्तन अद्यतन स्पेक्स पर निर्माण करता है
## शब्दावली
| शब्द | परिभाषा |
|------|------------|
| **आर्टिफैक्ट** | एक परिवर्तन के अंतर्गत एक दस्तावेज़ (प्रस्ताव, डिज़ाइन, कार्य, या डेल्टा विनिर्देश) |
| **संग्रह** | एक परिवर्तन को पूरा करने और उसके डेल्टा को मुख्य विनिर्देशों में मिलाने की प्रक्रिया |
| **परिवर्तन** | सिस्टम में एक प्रस्तावित संशोधन, जिसे आर्टिफैक्ट्स वाले फ़ोल्डर के रूप में पैक किया जाता है |
| **डेल्टा विनिर्देश** | एक विनिर्देश जो वर्तमान विनिर्देशों के सापेक्ष परिवर्तनों (जोड़ा गया/संशोधित/हटाया गया) का वर्णन करता है |
| **डोमेन** | विनिर्देशों के लिए एक तार्किक समूहन (जैसे, `auth/`, `payments/`) |
| **आवश्यकता** | वह विशिष्ट व्यवहार जो सिस्टम के पास होना चाहिए |
| **परिदृश्य** | एक आवश्यकता का एक ठोस उदाहरण, आमतौर पर Given/When/Then प्रारूप में |
| **स्कीमा** | आर्टिफैक्ट प्रकारों और उनकी निर्भरताओं की एक परिभाषा |
| **विनिर्देश** | सिस्टम व्यवहार का वर्णन करने वाला एक विनिर्देश, जिसमें आवश्यकताएँ और परिदृश्य शामिल हैं |
| **सत्य का स्रोत** | `openspec/specs/` निर्देशिका, जिसमें वर्तमान सहमत व्यवहार शामिल है |
## अगले कदम
- [शुरुआत करें](getting-started.md) - व्यावहारिक प्रारंभिक कदम
- [कार्यप्रवाह](workflows.md) - सामान्य पैटर्न और प्रत्येक का उपयोग कब करें
- [कमांड](commands.md) - पूर्ण कमांड संदर्भ
- [अनुकूलन](customization.md) - कस्टम स्कीमा बनाएँ और अपनी परियोजना को कॉन्फ़िगर करें