त्वरित शुरुआत

आपका पहला परिवर्तन, विचार से लेकर संग्रहित होने तक, किसी नए या मौजूदा प्रोजेक्ट में।

शुरू करने से पहले, आपको अपनी मशीन पर CLI चाहिए (इंस्टालेशन) और आपके प्रोजेक्ट में OpenSpec प्रारंभ किया हुआ होना चाहिए (अपना प्रोजेक्ट सेट अप करें)।

खाली प्रोजेक्ट से शुरू करें

आप बिना कोई स्टैक चुने या पूर्ण आर्किटेक्चर के भी शुरू कर सकते हैं। अपने प्रोजेक्ट फ़ोल्डर में OpenSpec प्रारंभ करें, फिर अपने एजेंट से कहें कि वह आपके साथ विकल्पों का पता लगाए। अपनी AI चैट में:

Help me explore a task tracker from scratch. I have not picked a stack. Compare the options and help me choose the first behavior to build.

तय करें कि पहले परिवर्तन को क्या चाहिए और आगे के आर्किटेक्चर विकल्पों को खुला रखें। अपने एजेंट से वह एक परिवर्तन प्रस्तावित करने को कहें, फिर नीचे दिए गए चरणों का पालन करें। प्रोजेक्ट बढ़ने के साथ आप आर्किटेक्चर पर फिर से विचार कर सकते हैं।

एक नज़र में चक्र

हर परिवर्तन इन्हीं पाँच चरणों से गुज़रता है: आप अपने एजेंट के साथ विचार पर सोच-विचार करते हैं, वह एक योजना का मसौदा तैयार करता है, कोई भी कोड बनने से पहले आप योजना को सुधारते हैं, एजेंट उससे निर्माण करता है, और संग्रह करना उस चीज़ के साथ आपकी स्पेक्स को अद्यतन करता है जो शिप हुई।

flowchart LR
    explore["1 · Explore<br/>think it through together"] --> propose["2 · Propose<br/>agent drafts the plan"]
    propose --> review["3 · Review<br/>you correct the plan"]
    review --> apply["4 · Apply<br/>agent builds, task by task"]
    apply --> archive["5 · Archive<br/>specs absorb the change"]
    archive -. "next change" .-> explore

नीचे दिए गए हर प्रॉम्प्ट को अपनी AI चैट में डालें, उसी जगह जहाँ आप कोड के लिए पूछते हैं। उदाहरण सरल भाषा का उपयोग करते हैं ताकि वे सभी टूल्स में काम करें। आप सीधे किसी स्किल को भी आमंत्रित कर सकते हैं; सिंटैक्स टूल के अनुसार बदलता है (समर्थित टूल्स)।

चरण 1: एक्सप्लोर करें

योजना माँगने से पहले अपने एजेंट के साथ विचार पर सोच-विचार करें। अपनी AI चैट में:

Help me explore how rate limiting should work in this app.

एक्सप्लोर एक सोचने का मोड है। एजेंट आपके कोडबेस की जाँच करता है, महत्वपूर्ण प्रश्न पूछता है, विकल्पों का रेखाचित्र बनाता है, और पूर्वधारणाओं को चुनौती देता है। यह कभी कोड नहीं लिखता। यह और कुछ नहीं लिखता जब तक आप इसे आपके निर्णयों को दर्ज करने के लिए न कहें, या जब यह प्रस्ताव दे तो हाँ न कहें। आउटपुट एक अधिक स्पष्ट विचार होता है।

जब तक समस्या की आवश्यकता हो, यहीं रहें। जब आकार सही लगे, तो इसे आगे सौंपें:

Propose the change we just discussed.

यह पंक्ति आपके लिए प्रस्ताव प्रारंभ करती है, जो भी आपने तय किया है उसे साथ लेकर। चरण 2 में पहला प्रॉम्प्ट छोड़ दें।

चरण 2: प्रस्ताव करें

प्रस्ताव विचार को एक समीक्षणीय योजना में बदल देता है। एक्सप्लोर से आ रहे हों तो यह पहले से चल रहा है। ठंडी शुरुआत में, जब परिवर्तन आपके मन में स्पष्ट हो, सीधे पूछें। अपनी AI चैट में:

Propose a change to add rate limiting.

एजेंट वह पूछता है जो आवश्यक हो, फिर एक परिवर्तन फ़ोल्डर लिखता है:

openspec/changes/add-rate-limiting/
├── proposal.md    क्यों, और क्या बदलता है
├── specs/         "पूर्ण" का क्या अर्थ है, परीक्षण योग्य आवश्यकताओं के रूप में
├── design.md      तकनीकी निर्णय (केवल जब परिवर्तन को इसकी आवश्यकता हो)
└── tasks.md       कार्यान्वयन चेकलिस्ट

अभी कोई कोड नहीं। प्रस्ताव योजना पर ही रुक जाता है।

चरण 3: योजना की समीक्षा करें और उसे सुधारें

योजना को तब सुधारें जब वह अभी भी शब्दों में हो और कुछ भी बना न हो। इस क्रम में पढ़ें:

• proposal.md: क्या यह सही समस्या है, सही आकार में?
• specs/: सबसे मूल्यवान पढ़ाई। क्या आप इन आवश्यकताओं को पूर्ण मानकर स्वीकार करेंगे?
• tasks.md: क्या कार्य स्पेक्स को कवर करते हैं, और उससे अधिक कुछ नहीं?

कुछ सुधारना हो तो, दोनों में से कोई भी तरीका काम करता है:

• फ़ाइल स्वयं संपादित करें। आर्टिफ़ैक्ट्स सादे markdown हैं, और फ़ाइलें ही योजना हैं।
• अपने एजेंट को बताएँ कि क्या गलत है ("स्पेक में अनप्रमाणित मामला छूट गया है")। वह आर्टिफ़ैक्ट्स को संशोधित करता है।

चरण 4: लागू करें

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

Apply the add-rate-limiting change.

एजेंट परिवर्तन फ़ोल्डर पढ़ता है, फिर tasks.md के माध्यम से काम करता है, हर कार्य को पूरा होने पर चेक करता जाता है।

• बाधित हुआ, या कॉन्टेक्स्ट से बाहर? एक नया सत्र खोलें और इसे फिर से लागू करने को कहें। यह पहले अनचेक किए गए कार्य से फिर शुरू करता है।
• योजना गलत निकली? आर्टिफ़ैक्ट्स को सुधारें (चरण 3 से कोई भी तरीका), फिर लागू करना जारी रखें।
• प्रगति tasks.md के चेकबॉक्स में रहती है। कोई छिपी हुई स्थिति नहीं है।

चरण 5: संग्रह करें

संग्रह करना दो काम करता है: यह आपकी मुख्य स्पेक्स को परिवर्तन की आवश्यकताओं के साथ अद्यतन करता है, और परिवर्तन फ़ोल्डर को संग्रह फ़ोल्डर में ले जाता है (/openspec/changes/archive/* में)।

जब tasks.md का हर बॉक्स चेक हो जाए, अपनी AI चैट में:

Archive the add-rate-limiting change.

संग्रह करना क्या करता है, इसे चरण-दर-चरण देखें:

## तैयार परिवर्तन
> कार्यान्वयन पूरा हो गया है। डेल्टा स्पेक (यह परिवर्तन जो जोड़ता है) अभी भी परिवर्तन फ़ोल्डर के अंदर है; specs/ को अभी रेट-लिमिटिंग के बारे में पता नहीं है।
  openspec/
  ├── specs/                                   (अभी तक कोई रेट-लिमिटिंग स्पेक नहीं)
  └── changes/
      └── add-rate-limiting/
          ├── proposal.md
          ├── tasks.md                         हर बॉक्स चेक किया गया
          └── specs/
              └── rate-limiting/
                  └── spec.md                  डेल्टा: जोड़ी गई आवश्यकताएँ

## आवश्यकताएँ specs/ में पहुँचती हैं
> डेल्टा में प्रत्येक आवश्यकता मुख्य स्पेक में पहुँचती है: जोड़ी गई आवश्यकताएँ जुड़ जाती हैं, संशोधित आवश्यकताएँ अपने पुराने संस्करण को बदल देती हैं। एक नई क्षमता को एक नई स्पेक फ़ाइल मिलती है।
  openspec/
  ├── specs/
+ │   └── rate-limiting/
+ │       └── spec.md                          "Requirement: Rate limiting" प्राप्त करता है
  └── changes/
      └── add-rate-limiting/
          └── specs/
              └── rate-limiting/
                  └── spec.md                  डेल्टा, विलय का स्रोत

## फ़ोल्डर archive/ में जाता है
> पूरा परिवर्तन फ़ोल्डर, डेल्टा सहित, तिथि उपसर्ग के अंतर्गत संग्रह में चला जाता है। कुछ भी हटाया नहीं जाता।
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md
  └── changes/
-     └── add-rate-limiting/
+     └── archive/
+         └── 2026-08-08-add-rate-limiting/
+             ├── proposal.md
+             ├── tasks.md
+             └── specs/rate-limiting/spec.md

## स्पेक्स सिस्टम को जैसा बना है वैसा वर्णित करती हैं
> changes/ अगले परिवर्तन के लिए साफ़ है। specs/ इस बात का सत्य-स्रोत है कि सिस्टम क्या करता है; archive/ इस बात का इतिहास है कि यह वहाँ कैसे पहुँचा।
  openspec/
  ├── specs/
  │   └── rate-limiting/
  │       └── spec.md                          जैसा बना है वह स्पेक
  └── changes/
      └── archive/
          └── 2026-08-08-add-rate-limiting/

Git एक अलग विषय है। परिवर्तन फ़ोल्डर को कोड के साथ कमिट करें, और आपके वर्कफ़्लो के बारे में और कुछ नहीं बदलता।

संग्रहित परिवर्तनों को रखें या हटाएँ

openspec/changes/archive/ प्रत्येक पूर्ण परिवर्तन के लिए प्रस्ताव, डिज़ाइन, कार्य और डेल्टा रखता है। ऊपर के संग्रह प्रवाह में, डेल्टा पहले ही openspec/specs/ को अद्यतन कर चुका है।

• पूरा परिवर्तन फ़ोल्डर रखें जब आप वर्तमान चेकआउट में एक स्व-निहित रिकॉर्ड चाहते हैं।
• किसी संग्रहित परिवर्तन का specs/ फ़ोल्डर हटाएँ जब Git आपका स्पेक इतिहास हो। पहले संग्रह को कमिट करें, फिर openspec/changes/archive/<change>/specs/ हटाएँ। प्रस्ताव, डिज़ाइन, और कार्य चेकआउट में रहते हैं। openspec validate --archived अभी भी काम करता है क्योंकि यह कार्य पूर्णता की जाँच करता है, लागू किए गए डेल्टा की नहीं।
• पूरा परिवर्तन फ़ोल्डर हटाएँ केवल तब जब आपको चेकआउट में इसके प्रस्ताव, डिज़ाइन, या कार्य इतिहास की आवश्यकता न हो। वर्तमान स्पेक्स नहीं बदलतीं, लेकिन openspec validate --archived और चेकआउट की खोजें उस परिवर्तन को शामिल नहीं करेंगी।

WARNING

यदि आप चाहते हैं कि Git हटाई गई फ़ाइलों को बनाए रखे, तो संग्रह कमिट को अपनी रिपॉज़िटरी इतिहास में रखें। संग्रह और सफ़ाई कमिट्स को एक साथ स्क्वैश करने से वह मध्यवर्ती स्नैपशॉट हट जाता है।

OpenSpec संग्रहित परिवर्तनों को स्वचालित रूप से नहीं हटाता और न ही कोई रिटेंशन सेटिंग प्रदान करता है।

आगे बढ़ना

• डेल्टा स्पेक्स: डेल्टा स्पेक में व्यवहार परिवर्तन कैसे लिखें।
• प्रोफ़ाइल्स: मुख्य सेट से परे वैकल्पिक वर्कफ़्लो (संग्रह से पहले सत्यापन, वृद्धिशील योजना)।

उन्नत गाइड

अभी तक नहीं लिखे गए; गाइड जो हम जोड़ने की योजना बना रहे हैं:

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