अच्छे स्पेक लिखना

आप शायद ही कभी एक खाली पृष्ठ से स्पेक लिखते हैं। आप किसी बदलाव को सादे भाषा में वर्णन करते हैं, /opsx:propose आवश्यकताओं और परिदृश्यों का मसौदा तैयार करता है, और फिर आप उन्हें सुधारते हैं। यह पृष्ठ उस आखिरी हिस्से के बारे में है — "अच्छा" क्या होता है, और AI को उस दिशा में कैसे मार्गदर्शन करें।

यह बदलाव की समीक्षा का सहायक दस्तावेज है: समीक्षा मसौदे में कमजोर स्थानों को पकड़ना है, लेखन यह जानना है कि एक मजबूत स्पेक किस चीज से बना होता है।

स्पेक कोड नहीं, व्यवहार का है

एक स्पेक बताता है कि आपका सिस्टम क्या करता है, ऐसे शब्दों में जिसे कोई भी जांच सके — न कि यह कैसे बनाया गया है। यह आवश्यकताओं (व्यवहार के बयान) और परिदृश्यों (उन्हें साबित करने वाले वास्तविक उदाहरण) से बना होता है।

### Requirement: Session Timeout
The system SHALL expire a session after 30 minutes of inactivity.

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass with no activity
- THEN the session is invalidated and the user must re-authenticate

इसके कैसे (how) हिस्से — जैसे क्यू, लाइब्रेरी, टेबल स्कीमा — को design.md या कोड में रखें। जब व्यवहार और कार्यान्वयन को एक ही आवश्यकता में मिला दिया जाता है, तो वह आवश्यकता परीक्षण योग्य होना बंद कर देती है और कोड बदलते ही उसका समय पुराना होने लगता है।

एक अच्छी आवश्यकता क्या बनाती है

एक अच्छी आवश्यकता एक ही व्यवहार होती है, इतनी सादे शब्दों में कही गई हो कि आप इसे किसी दूसरे को परीक्षण के लिए दे सकें।

• एक बयान, एक SHALL/MUST। यदि किसी आवश्यकता में तीन "और भी" खंड हों, तो वह वास्तव में तीन आवश्यकताएं हैं। उन्हें अलग कर लें।

• पर्यवेक्षणीय। कोड के बाहर के किसी व्यक्ति को यह तय करने में समर्थ होना चाहिए कि यह सत्य है या नहीं। "The system SHALL show an error banner when the upload exceeds 10 MB" पर्यवेक्षणीय है। "The system SHALL handle large uploads gracefully" पर्यवेक्षणीय नहीं है।

• सही मजबूती। OpenSpec RFC 2119 कीवर्ड का उपयोग करता है, और उनके अलग-अलग अर्थ होते हैं:

  कीवर्ड	अर्थ
  MUST / SHALL	एक कठोर आवश्यकता। बातचीत का दायरा नहीं।
  SHOULD	एक मजबूत सिफारिश, जिसमें तर्कसंगत अपवाद के लिए जगह होती है।
  MAY	वास्तव में वैकल्पिक।

  डिफॉल्ट रूप से MUST/SHALL का उपयोग करें। SHOULD का उपयोग तभी करें जब आप वास्तव में "जब तक कि ऐसा करने का कारण न हो" का अर्थ दे रहे हों।

आवश्यकता का परीक्षण: क्या कोई परीक्षक जिसने कोड कभी नहीं देखा है, यह तय कर सकता है कि यह पास हुआ है या नहीं? यदि नहीं, तो इसे सुधारने की जरूरत है।

एक अच्छा परिदृश्य क्या बनाता है

परिदृश्य वे हैं जहां आवश्यकता अपना मूल्य प्रदर्शित करती है। प्रत्येक परिदृश्य एक ठोस GIVEN / WHEN / THEN होता है जिसे स्वचालित परीक्षण में बदला जा सकता है।

• यह अपनी आवश्यकता का परीक्षण करता है। जो परिदृश्य बस आवश्यकता को दूसरे शब्दों में दोबारा कहता है, उससे कुछ परीक्षण नहीं होता। इसे एक विशिष्ट स्थिति और विशिष्ट परिणाम वाला बनाएं।
• उन मामलों को कवर करें जो मायने रखते हैं, केवल हैपी पाथ नहीं। वैध लॉगिन आसान है। खाली इनपुट, समाप्त टोकन, दूसरा क्लिक, वो चीज जो गलत हो जाती है — ये वे स्थान हैं जहां बग्स रहते हैं, और जहां परिदृश्य का सबसे ज्यादा मूल्य होता है।
• शीर्षक में मामले का नाम दें। "परिदृश्य: समाप्त टोकन को रद्द करता है" समीक्षक को एक नजर में क्या कवर किया गया है बता देता है; "परिदृश्य: टेस्ट 2" नहीं करता।

एक उपयोगी आदत: अनुमोदन करने से पहले, पूछें वो कौन सा एक मामला है जिसे टूटा देखकर मैं परेशान हो जाऊंगा? — और यह सुनिश्चित करें कि उसका एक परिदृश्य उसका नाम लेता है।

सही प्रकार का डेल्टा चुनें

एक बदलाव स्पेक्स में अपने संपादनों को तीन सेक्शन प्रकारों के साथ वर्णन करता है। सही प्रकार का उपयोग करने से आपके आर्काइव किए गए स्पेक्स सत्य रहते हैं:

• ## ADDED Requirements — पहले मौजूद नहीं था ऐसा बिल्कुल नया व्यवहार।
• ## MODIFIED Requirements — पहले मौजूद था और अब बदल रहा है ऐसा व्यवहार। समीक्षक को सहायता करने के लिए पूरा नया संस्करण शामिल करें; बदलाव पर एक संक्षिप्त नोट मददगार होता है।
• ## REMOVED Requirements — समाप्त हो रहा व्यवहार, साथ में क्यों समाप्त हो रहा है उसकी पंक्ति।

आर्काइव करते समय, ADDED को मुख्य स्पेक में जोड़ दिया जाता है, MODIFIED पुराने संस्करण को बदल देता है, और REMOVED को हटा दिया जाता है। यदि आप वास्तविक बदलाव को ADDED के रूप में मार्क करते हैं, तो आपके पास दो प्रतिस्पर्धी आवश्यकताएं आ जाती हैं; यदि आप नए व्यवहार को MODIFIED के रूप में वर्णन करते हैं, तो बदलने के लिए कुछ भी नहीं होता। संदेह में होने पर, वर्तमान स्पेक खोलें और देखें कि आवश्यकता पहले से मौजूद है या नहीं।

बदलाव को सही आकार दें

सबसे आम लेखन त्रुटि एक बुरी तरह से लिखी गई आवश्यकता नहीं है — यह एक ऐसा बदलाव है जो तीन बदलावों का काम करने की कोशिश कर रहा है।

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

बदलाव बहुत बड़ा होने के संकेत:

• प्रस्ताव का दायरा अनसंबंधित विशेषताओं की सूची जैसा दिखता है।
• इसे समीक्षा करने में एक दोपहर लग जाएगा, इसलिए कोई नहीं करेगा।
• दो लोग इसमें बिना टकराए काम नहीं कर पाएंगे।
• आधी टास्क अपने आप रिलीज हो सकती हैं।

छोटे बदलावों की समीक्षा करना आसान होता है, एक केंद्रित सत्र में उन्हें बनाना आसान होता है, और छह महीने बाद जब आर्काइव ही बचा हो उनके बारे में तर्क करना आसान होता है। आप हमेशा कई बदलावों को समांतर में चला सकते हैं — देखें संपादन और पुनरावृत्ति और वर्कफ्लो।

उल्टा भी होता है: एक लाइन में टाइपो फिक्स को तीन आवश्यकताओं और डिजाइन दस्तावेज की जरूरत नहीं होती है। अनुष्ठान को जोखिम के स्तर से मिलाएं।

AI को अच्छे मसौदे की ओर कैसे मार्गदर्शन करें

क्योंकि /opsx:propose पहला मसौदा तैयार करता है, आपको वापस मिलने वाली चीज की गुणवत्ता आपके दिए गए इनपुट की गुणवत्ता के अनुसार होती है। आपको आवश्यकताओं को हाथ से लिखने की जरूरत नहीं है — आपको AI को सही दिशा में मार्गदर्शन करना होता है:

• उद्देश्य और सीमा स्पष्ट रूप से बताएं। "डार्क मोड टॉगल जोड़ें जो पहली बार लोड होने पर OS सेटिंग का पालन करता हो — मौजूदा थीम API को मत छूए।" स्कोप से बाहर के हिस्से की उतनी ही मायने की चीज है जितनी स्कोप के अंदर के हिस्से की।
• उन मामलों का नाम लें जिनके बारे में आप चिंतित हैं। "यह सुनिश्चित करें कि उस उपयोगकर्ता के लिए एक परिदृश्य हो जिसने पहले ही मैन्युअली कोई थीम चुनी हो।" AI उन्हीं चीजों को कवर करता है जिन्हें आप इशारा करते हैं।
• फिर संपादित करें। यह सादा मार्कडाउन है। एक अस्पष्ट SHALL को तंग करें, जिस परिदृश्य को कुछ परीक्षण नहीं करता उसे हटा दें, उस मामले को जोड़ें जिसे यह छोड़ गया है — या AI से पूछें: "टाइमआउट आवश्यकता अस्पष्ट है, इसे 30 मिनट तक स्पष्ट कर दें।"

मसौदा तैयार करें, सुधारें, दोहराएं। इसके कुछ राउंड से एक ऐसा स्पेक बनता है जिस पर आप भरोसा कर सकें, जो कि पूरा लक्ष्य है।

एक त्वरित जांच सूची

• [ ] प्रत्येक आवश्यकता SHALL/MUST वाली एक ही पर्यवेक्षणीय व्यवहार होती है।
• [ ] आवश्यकताओं में कोई कार्यान्वयन विवरण शामिल नहीं होता है।
• [ ] प्रत्येक आवश्यकता का कम से कम एक ऐसा परिदृश्य होता है जो वास्तव में उसका परीक्षण करता है।
• [ ] महत्वपूर्ण किनारा और त्रुटि मामलों के लिए परिदृश्य हों, केवल हैपी पाथ नहीं।
• [ ] डेल्टा वर्तमान स्पेक के खिलाफ ADDED / MODIFIED / REMOVED का सही उपयोग करें।
• [ ] पूरा बदलाव उसका एक ही उद्देश्य होता है जिसे आप एक वाक्य में कह सकें।

आगे कहां जाएं

• बदलाव की समीक्षा — वह दो मिनट की समीक्षा पास जो कहीं छूट गई कमियों को पकड़ती है।
• अवधारणाएं — स्पेक्स, बदलावों और डेल्टा के पीछे का गहरा मॉडल।
• उदाहरण और रेसिपी — शुरू से अंत तक वास्तविक बदलाव।