AI साक्षात्कार श्रृंखला 16: एक अच्छा spec कोडिंग कैसा होना चाहिए?

एक अच्छा Spec कोडिंग (स्पेक-चालित प्रोग्रामिंग) का मूल है "अस्पष्ट विचार" को "सटीक, सत्यापन योग्य, निष्पादन योग्य अनुबंध" में बदलना। यह सिर्फ एक दस्तावेज़ लिखना नहीं है, बल्कि मनुष्य और AI (या मनुष्य और मनुष्य) के बीच अस्पष्टता-रहित संचार भाषा स्थापित करना है। नीचे मैं स्पेक की सामग्री संरचना, लेखन सिद्धांत, AI के साथ सहयोग प्रक्रिया, गुणवत्ता सत्यापन चार आयामों से एक अच्छे spec का स्वरूप दूंगा।

1. स्पेक दस्तावेज़ का मानक ढाँचा (एक फीचर मॉड्यूल के उदाहरण के साथ)

अनुभाग	अनिवार्य सामग्री	उदाहरण
1. लक्ष्य और दायरा	एक वाक्य में क्या करना है, स्पष्ट रूप से क्या नहीं करना है	"उपयोगकर्ता पंजीकरण API लागू करें, ईमेल सत्यापन शामिल नहीं है"
2. इनपुट/आउटपुट अनुबंध	डेटा संरचना, प्रकार, अनिवार्य/वैकल्पिक फ़ील्ड, उदाहरण मान	`POST /register` अनुरोध निकाय `{email: string, password: string}`, प्रतिक्रिया `201` या `400` जिसमें त्रुटि कोड
3. व्यवहार और तर्क	व्यावसायिक नियम, सीमा स्थितियाँ, स्थिति परिवर्तन	"पासवर्ड की लंबाई 8-20 वर्ण, कम से कम एक अंक शामिल; ईमेल पहले से मौजूद होने पर `409` लौटाएं"
4. त्रुटि प्रबंधन	सभी संभावित अपवाद परिस्थितियाँ और संबंधित त्रुटि कोड/संदेश	"डेटाबेस कनेक्शन विफल → `503` लौटाएं, स्टैक का खुलासा न करें"
5. गैर-कार्यात्मक आवश्यकताएँ	प्रदर्शन (प्रतिक्रिया समय <200ms), सुरक्षा (पैरामीटराइज्ड क्वेरी), लॉगिंग, अवलोकन क्षमता	"सभी SQL को प्रीकम्पाइल्ड होना चाहिए; `email` लॉग करें लेकिन `password` नहीं"
6. परीक्षण मामले (महत्वपूर्ण)	कम से कम 3 विशिष्ट इनपुट + 2 सीमा/अपवाद इनपुट, अपेक्षित आउटपुट दें	नीचे तालिका देखें
7. निर्भरता और बाधाएँ	कौन सी लाइब्रेरी, संस्करण, पर्यावरण चर का उपयोग करें	"Python 3.10+, FastAPI, पर्यावरण चर `DB_URL`"

परीक्षण मामलों का उदाहरण (spec में एम्बेडेड)

परिदृश्य	इनपुट	अपेक्षित आउटपुट
सामान्य पंजीकरण	ईमेल: `a@b.com`, पासवर्ड: `Pass1234`	`201`, `user_id` लौटाएं
पासवर्ड बहुत छोटा	पासवर्ड: `Ab1`	`400`, त्रुटि कोड `WEAK_PASSWORD`
ईमेल पहले से मौजूद	वही ईमेल	`409`, त्रुटि कोड `EMAIL_EXISTS`

अच्छे Spec को पहले परीक्षण मामले लिखने चाहिए, क्योंकि AI उनके आधार पर सीधे यूनिट टेस्ट उत्पन्न कर सकता है और पूरा होने पर स्वचालित रूप से सत्यापित कर सकता है।

2. Spec लिखने के मुख्य सिद्धांत (SMART संस्करण)

सिद्धांत	व्याख्या	प्रतिउदाहरण
सटीक (Precise)	विशिष्ट संख्याओं, प्रकारों, बूलियन शर्तों का उपयोग करें; "जितना संभव हो", "आमतौर पर" जैसे शब्दों से बचें	❌ "पासवर्ड पर्याप्त सुरक्षित होना चाहिए" → ✅ "पासवर्ड कम से कम 8 वर्ण, बड़े अक्षर, छोटे अक्षर और अंक शामिल करें"
सत्यापन योग्य (Verifiable)	प्रत्येक आवश्यकता को स्वचालित परीक्षण या मानव निरीक्षण द्वारा पास/फेल के रूप में निर्धारित किया जा सकता है	❌ "कोड सुरुचिपूर्ण होना चाहिए" → ✅ "फ़ंक्शन की चक्रीय जटिलता ≤10, कोई डुप्लिकेट कोड ब्लॉक नहीं"
अस्पष्टता-रहित (Unambiguous)	एक ही शब्द का पूरे पाठ में समान अर्थ हो; आवश्यक होने पर शब्दावली दें	❌ "यदि उपयोगकर्ता मौजूद नहीं है, तो त्रुटि लौटाएं" → ✅ "उपयोगकर्ता मौजूद नहीं → `404` और `{code: 'USER_NOT_FOUND'}` लौटाएं"
पूर्ण (Complete)	हैप्पी पथ, सभी अपवाद पथ, गैर-कार्यात्मक आवश्यकताओं को कवर करें	❌ केवल सफल परिदृश्य लिखा → ✅ डेटाबेस टाइमआउट, अनुमति अपर्याप्तता आदि शामिल करें
परमाणु (Atomic)	एक spec केवल एक स्वतंत्र रूप से वितरित किए जा सकने वाले फीचर का वर्णन करे (AI के लिए एक बार में पूरा करना आसान)	❌ एक spec में "पूरी भुगतान प्रणाली" लिखना → ✅ "भुगतान आदेश उत्पन्न करना", "कॉलबैक हस्ताक्षर सत्यापन", "रिफंड" में विभाजित करें

3. AI के साथ सहयोग करते समय Spec कोडिंग प्रक्रिया

मनुष्य spec लिखता है (उपरोक्त संरचना, विशेष रूप से परीक्षण मामले और फ़ंक्शन हस्ताक्षर अच्छी तरह से लिखें)।
spec को एक बार में AI को दें (संवादात्मक रूप से आवश्यकताएँ न जोड़ें, वाइब प्रदूषण से बचें)।
AI कोड + यूनिट टेस्ट आउटपुट करता है (AI को spec में परीक्षण मामलों के अनुसार निष्पादन योग्य परीक्षण उत्पन्न करने चाहिए)।
परीक्षण चलाएं: यदि सभी पास हो जाएं, तो अगले चरण पर जाएं; यदि नहीं, तो spec या कोड को सीधे सुधारें (इस समय छोटे लूप में जा सकते हैं, लेकिन परिवर्तन रिकॉर्ड करें)।
मानव समीक्षा: जाँचें कि क्या spec के बाहर की कार्यक्षमता (scope creep) शामिल है, सुरक्षा/प्रदर्शन की जाँच करें।
स्थायीकरण: spec दस्तावेज़ और अंतिम कोड एक साथ रिपॉजिटरी में जमा करें, स्थायी दस्तावेज़ के रूप में।

मुख्य अभ्यास: Spec कोडीकरण — spec.md + test_spec.py का उपयोग करें, जहाँ परीक्षण फ़ाइल सीधे spec के उदाहरणों से आती है, ताकि बाद में कोड संशोधित करते समय केवल परीक्षण चलाकर spec के टूटने की पुष्टि की जा सके।

4. अच्छे Spec के प्रभाव (स्वीकृति मानदंड के रूप में उपयोग किए जा सकते हैं)

निश्चितता: समान spec को विभिन्न AI (या विभिन्न लोगों) को देने पर समान कार्यान्वयन मिलता है।
परीक्षण क्षमता: कोड लिखने के तुरंत बाद 90% शुद्धता स्वचालित रूप से सत्यापित की जा सकती है।
रखरखाव क्षमता: छह महीने बाद कोई भी spec देखकर मूल डिज़ाइन के इरादे को समझ सकता है।
कम संचार लागत: टीम चर्चा केवल spec पर करती है, कोड की पंक्तियों पर नहीं।
सुरक्षा/गुणवत्ता अंतर्निहित: सुरक्षा आवश्यकताएँ (जैसे पैरामीटराइज्ड क्वेरी) और सीमा स्थितियाँ spec में लिखी जाती हैं, AI को उनका पालन करना होता है।

5. एक अच्छे Spec का उदाहरण (अति संक्षिप्त संस्करण)

# Spec: उपयोगकर्ता पंजीकरण API

## दायरा
- ईमेल, पासवर्ड प्राप्त करें
- सत्यापन ईमेल न भेजें, ईमेल की वास्तविकता की जाँच न करें

## अनुबंध
POST /register
Content-Type: application/json
अनुरोध: { "email": string, "password": string }
प्रतिक्रिया 201: { "user_id": string }
प्रतिक्रिया 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
प्रतिक्रिया 409: { "code": "EMAIL_ALREADY_EXISTS" }

## व्यवहार
- ईमेल को RFC 5322 मूल प्रारूप (a@b.c) का पालन करना चाहिए
- पासवर्ड: लंबाई 8-20, कम से कम एक अंक और एक बड़ा अक्षर शामिल
- bcrypt का उपयोग करके एन्क्रिप्ट करें, नमक लागत 10
- यदि डेटाबेस में डालने से पहले ईमेल पहले से मौजूद है → 409

## परीक्षण मामले (इनपुट -> अपेक्षित स्थिति कोड + प्रतिक्रिया फ़ील्ड)
| इनपुट ईमेल | पासवर्ड | अपेक्षित |
|------------|----------|----------|
| test@x.com | Pass1234  | 201, user_id मौजूद है |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (पहले से मौजूद ईमेल) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## गैर-कार्यात्मक
- SQL को पैरामीटराइज्ड क्वेरी का उपयोग करना चाहिए (इंजेक्शन से बचाव)
- लॉग में पंजीकरण स्रोत IP रिकॉर्ड करें, पासवर्ड न रिकॉर्ड करें
- प्रतिक्रिया समय 95% अनुरोध <100ms (bcrypt को छोड़कर)

## निर्भरताएँ
- Python 3.10+, FastAPI, bcrypt, asyncpg

अच्छा Spec कोडिंग = मनुष्य के "डिज़ाइन निर्णयों" को मशीन के "परीक्षण मामलों + प्रकार हस्ताक्षर + व्यवहार बाधाओं" में बदलना, जिससे AI केवल कार्यान्वयन भरने के लिए जिम्मेदार हो, जबकि मनुष्य हमेशा गुणवत्ता और दिशा पर नियंत्रण रखता है।