शुरुआत कैसे करें

यह मार्गदर्शिका बताती है कि OpenSpec कैसे काम करता है, इसे इंस्टॉल और इनिशियलाइज़ करने के बाद। इंस्टॉलेशन निर्देशों के लिए, मुख्य README देखें।

यह कैसे काम करता है

OpenSpec आपकी और आपके AI कोडिंग सहायक की मदद करता है ताकि कोई भी कोड लिखने से पहले यह तय हो सके कि क्या बनाना है।

डिफ़ॉल्ट त्वरित मार्ग (कोर प्रोफ़ाइल):

/opsx:propose ──► /opsx:apply ──► /opsx:archive

विस्तृत मार्ग (कस्टम वर्कफ़्लो चयन):

/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

डिफ़ॉल्ट ग्लोबल प्रोफ़ाइल core है, जिसमें propose, explore, apply, और archive शामिल हैं। आप openspec config profile और फिर openspec update का उपयोग करके विस्तृत वर्कफ़्लो कमांड सक्षम कर सकते हैं।

OpenSpec क्या बनाता है

openspec init चलाने के बाद, आपके प्रोजेक्ट में यह संरचना होती है:

openspec/
├── specs/              # सत्य का स्रोत (आपके सिस्टम का व्यवहार)
│   └── <domain>/
│       └── spec.md
├── changes/            # प्रस्तावित अपडेट (प्रति परिवर्तन एक फ़ोल्डर)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # डेल्टा स्पेक्स (क्या बदल रहा है)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # प्रोजेक्ट कॉन्फ़िगरेशन (वैकल्पिक)

दो मुख्य निर्देशिकाएँ:

• specs/ - सत्य का स्रोत। ये स्पेक्स बताते हैं कि आपका सिस्टम वर्तमान में कैसे व्यवहार करता है। डोमेन के अनुसार व्यवस्थित (जैसे, specs/auth/, specs/payments/)।

• changes/ - प्रस्तावित संशोधन। प्रत्येक परिवर्तन का अपना फ़ोल्डर होता है जिसमें सभी संबंधित कलाकृतियाँ होती हैं। जब कोई परिवर्तन पूरा हो जाता है, तो उसकी स्पेक्स मुख्य specs/ निर्देशिका में विलीन हो जाती हैं।

कलाकृतियों को समझना

प्रत्येक परिवर्तन फ़ोल्डर में कार्य का मार्गदर्शन करने वाली कलाकृतियाँ होती हैं:

कलाकृति	उद्देश्य
proposal.md	"क्यों" और "क्या" - इरादे, दायरे और दृष्टिकोण को कैप्चर करता है
specs/	जोड़े गए/संशोधित/हटाए गए आवश्यकताओं को दिखाने वाली डेल्टा स्पेक्स
design.md	"कैसे" - तकनीकी दृष्टिकोण और वास्तुकला निर्णय
tasks.md	चेकबॉक्स के साथ कार्यान्वयन चेकलिस्ट

कलाकृतियाँ एक-दूसरे पर बनती हैं:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            जैसे-जैसे आप सीखते हैं, अपडेट करें

आप कार्यान्वयन के दौरान और अधिक जानने पर हमेशा पहले की कलाकृतियों पर वापस जा सकते हैं और उन्हें परिष्कृत कर सकते हैं।

डेल्टा स्पेक्स कैसे काम करती हैं

डेल्टा स्पेक्स OpenSpec में मुख्य अवधारणा हैं। ये दिखाती हैं कि आपकी वर्तमान स्पेक्स के सापेक्ष क्या बदल रहा है।

प्रारूप

डेल्टा स्पेक्स परिवर्तन के प्रकार को इंगित करने के लिए अनुभागों का उपयोग करती हैं:

# Auth के लिए डेल्टा

## जोड़ी गई आवश्यकताएँ

### आवश्यकता: दो-कारक प्रमाणीकरण
सिस्टम को लॉगिन के दौरान दूसरे कारक की आवश्यकता होनी चाहिए।

#### परिदृश्य: OTP आवश्यक
- दिया गया है कि 2FA सक्षम एक उपयोगकर्ता
- जब उपयोगकर्ता मान्य क्रेडेंशियल प्रस्तुत करता है
- तो एक OTP चुनौती प्रस्तुत की जाती है

## संशोधित आवश्यकताएँ

### आवश्यकता: सत्र समय-सीमा
सिस्टम को निष्क्रियता के 30 मिनट बाद सत्रों की समय-सीमा समाप्त करनी चाहिए।
(पहले: 60 मिनट)

#### परिदृश्य: निष्क्रिय समय-सीमा
- दिया गया है कि एक प्रमाणित सत्र
- जब गतिविधि के बिना 30 मिनट बीत जाते हैं
- तो सत्र अमान्य हो जाता है

## हटाई गई आवश्यकताएँ

### आवश्यकता: मुझे याद रखें
(2FA के पक्ष में पदावनत)

संग्रह पर क्या होता है

जब आप कोई परिवर्तन संग्रहित करते हैं:

1. जोड़ी गई आवश्यकताएँ मुख्य स्पेक्स में जोड़ दी जाती हैं
2. संशोधित आवश्यकताएँ मौजूदा संस्करण को प्रतिस्थापित करती हैं
3. हटाई गई आवश्यकताएँ मुख्य स्पेक्स से हटा दी जाती हैं

परिवर्तन फ़ोल्डर ऑडिट इतिहास के लिए openspec/changes/archive/ में चला जाता है।

उदाहरण: आपका पहला परिवर्तन

आइए एप्लिकेशन में डार्क मोड जोड़ने की प्रक्रिया से गुजरें।

1. परिवर्तन शुरू करें (डिफ़ॉल्ट)

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

AI:  बनाया गया openspec/changes/add-dark-mode/
     ✓ proposal.md — हम यह क्यों कर रहे हैं, क्या बदल रहा है
     ✓ specs/       — आवश्यकताएँ और परिदृश्य
     ✓ design.md    — तकनीकी दृष्टिकोण
     ✓ tasks.md     — कार्यान्वयन चेकलिस्ट
     कार्यान्वयन के लिए तैयार!

यदि आपने विस्तृत वर्कफ़्लो प्रोफ़ाइल सक्षम की है, तो आप इसे दो चरणों में भी कर सकते हैं: /opsx:new फिर /opsx:ff (या /opsx:continue क्रमिक रूप से)।

2. क्या बनाया जाता है

proposal.md - इरादे को कैप्चर करता है:

# प्रस्ताव: डार्क मोड जोड़ें

## इरादा
उपयोगकर्ताओं ने रात के उपयोग के दौरान आँखों के तनाव को कम करने के लिए डार्क मोड विकल्प का अनुरोध किया है।

## दायरा
- सेटिंग्स में थीम टॉगल जोड़ें
- सिस्टम प्राथमिकता पहचान का समर्थन करें
- localStorage में प्राथमिकता संग्रहीत करें

## दृष्टिकोण
रंग-योजना के लिए CSS कस्टम प्रॉपर्टीज़ का उपयोग करें और राज्य प्रबंधन के लिए React संदर्भ।

specs/ui/spec.md - नई आवश्यकताओं को दिखाने वाली डेल्टा:

# UI के लिए डेल्टा

## जोड़ी गई आवश्यकताएँ

### आवश्यकता: थीम चयन
सिस्टम को उपयोगकर्ताओं को लाइट और डार्क थीम्स के बीच चयन करने की अनुमति देनी चाहिए।

#### परिदृश्य: मैनुअल टॉगल
- दिया गया है कि किसी भी पृष्ठ पर एक उपयोगकर्ता
- जब उपयोगकर्ता थीम टॉगल पर क्लिक करता है
- तो थीम तुरंत बदल जाती है
- और प्राथमिकता सत्रों में बनी रहती है

#### परिदृश्य: सिस्टम प्राथमिकता
- दिया गया है कि कोई सहेजी गई प्राथमिकता नहीं है
- जब एप्लिकेशन लोड होता है
- तो सिस्टम की पसंदीदा रंग योजना का उपयोग किया जाता है

tasks.md - कार्यान्वयन चेकलिस्ट:

# कार्य

## 1. थीम इन्फ्रास्ट्रक्चर
- [ ] 1.1 लाइट/डार्क राज्य के साथ ThemeContext बनाएँ
- [ ] 1.2 रंगों के लिए CSS कस्टम प्रॉपर्टीज़ जोड़ें
- [ ] 1.3 localStorage स्थायित्व लागू करें

## 2. UI घटक
- [ ] 2.1 ThemeToggle घटक बनाएँ
- [ ] 2.2 सेटिंग्स पृष्ठ में टॉगल जोड़ें
- [ ] 2.3 त्वरित टॉगल शामिल करने के लिए Header अपडेट करें

## 3. स्टाइलिंग
- [ ] 3.1 डार्क थीम रंग पैलेट परिभाषित करें
- [ ] 3.2 CSS चर का उपयोग करने के लिए घटक अपडेट करें

3. कार्यान्वयन करें

आप: /opsx:apply

AI:  कार्यों पर काम कर रहा है...
     ✓ 1.1 लाइट/डार्क राज्य के साथ ThemeContext बनाया गया
     ✓ 1.2 globals.css में CSS कस्टम प्रॉपर्टीज़ जोड़ी गईं
     ✓ 1.3 localStorage स्थायित्व लागू किया गया
     ✓ 2.1 ThemeToggle घटक बनाया गया
     ...
     सभी कार्य पूरे हुए!

कार्यान्वयन के दौरान, यदि आपको पता चलता है कि डिज़ाइन में समायोजन की आवश्यकता है, तो बस कलाकृति अपडेट करें और जारी रखें।

4. संग्रह करें

आप: /opsx:archive

AI:  add-dark-mode को संग्रहित कर रहा है...
     ✓ स्पेक्स को openspec/specs/ui/spec.md में विलीन किया गया
     ✓ openspec/changes/archive/2025-01-24-add-dark-mode/ में ले जाया गया
     पूर्ण! अगली सुविधा के लिए तैयार।

आपकी डेल्टा स्पेक्स अब मुख्य स्पेक्स का हिस्सा हैं, जो दस्तावेज़ करती हैं कि आपका सिस्टम कैसे काम करता है।

सत्यापन और समीक्षा

अपने परिवर्तनों की जाँच करने के लिए CLI का उपयोग करें:

# सक्रिय परिवर्तन सूचीबद्ध करें
openspec list

# परिवर्तन विवरण देखें
openspec show add-dark-mode

# स्पेक्स प्रारूप मान्य करें
openspec validate add-dark-mode

# इंटरैक्टिव डैशबोर्ड
openspec view

अगले कदम

• वर्कफ़्लो - सामान्य पैटर्न और प्रत्येक कमांड का उपयोग कब करें
• कमांड - सभी स्लैश कमांड के लिए पूर्ण संदर्भ
• अवधारणाएँ - स्पेक्स, परिवर्तनों और स्कीमा की गहरी समझ
• अनुकूलन - OpenSpec को अपने तरीके से काम करें