तुम्ही डेव्हलपमेंटला 'पॉज' करू शकत नाही. ही पहिली गोष्ट स्वीकारणे आवश्यक आहे. नवीन कामे (tickets) येत राहतात, ग्राहक शिपमेंटची अपेक्षा करतात आणि तुम्ही डॉक्युमेंटेशन करण्यासाठी निर्णय घेतला म्हणून तुमचा सध्याचा कोड थांबत नाही. कोणताही इंजिनिअरिंग मॅनेजर टीमला महिन्याभराची सुट्टी देणार नाही जेणेकरून टीमने असे स्पेसिफिकेशन लिहून काढता येईल जे पहिल्या दिवसापासून अस्तित्वात असायला हवे होते. OpenSpec वास्तवासाठी बनवले आहे, केवळ काल्पनिक (greenfield) कल्पनांसाठी नाही. तुमच्याकडे आधीपासून जे काही आहे, त्यात ते जोडले की ते सर्वोत्तम काम करते.

येथे उद्दिष्ट कोड पुन्हा लिहिणे (rewrite) हे नाही. तर ते प्रामाणिकपणे जुन्या गोष्टी शोधून काढणे (archaeology) आहे. प्रोडक्शनमध्ये प्रत्यक्षात काय चालले आहे ते तुम्ही शोधता, त्याचे अचूक वर्णन करता आणि तुमच्या कोडप्रमाणेच त्या वर्णनालाही विकसित होऊ देता. जेव्हा तुमचे स्पेसिफिकेशन तुमच्या सिस्टमशी जुळते, तेव्हा तुम्ही पुढच्या तिमाहीत येणाऱ्या इंजिनिअर्ससाठी आणि तुमच्या IDE मध्ये असलेल्या AI टूल्ससाठी काम सोपे करता. एकही रिलीज न चुकवता हे कसे करायचे ते खाली दिले आहे.

तुम्ही प्रत्यक्षात जे करता तिथून सुरुवात करा

तुमची रिपॉझिटरी उघडा आणि तुम्हाला controllers, models, services, आणि utils नावाची फोल्डर्स दिसतील. हे तांत्रिक स्तर (technical layers) आहेत आणि ते तुम्हाला दिशाभूल करू शकतात. ते तुमची सिस्टम व्यवसायासाठी काय करते याचे वर्णन करत नाहीत. JavaScript फाईल्सने भरलेले फोल्डर एखादा ऑर्डर शिपमेंटमध्ये कसा रूपांतरित होतो हे स्पष्ट करत नाही. OpenSpec लागू करण्यासाठी, तुम्हाला 'कार्यक्षमता' (capabilities) या दृष्टिकोनातून विचार करावा लागेल.

अशा स्थिर व्यावसायिक ऑपरेशन्सचा शोध घ्या जे तुम्ही संपूर्ण स्टॅक (stack) वेगळ्या भाषेत पुन्हा लिहिला तरी टिकून राहतील. बहुतेक प्रॉडक्ट कंपन्यांमध्ये, हे वारंवार दिसून येतात: Orders, Billing, Inventory, Customers, आणि Notifications. यापैकी पाच ते आठ मुख्य क्षमतांची (core capabilities) नावे घ्या.

प्रत्येक क्षमेसाठी, स्वतःला पाच विशिष्ट प्रश्न विचारण्यास भाग पाडा. ही क्षमता कोणत्या वास्तविक जगातील समस्येचे निराकरण करते? कोड प्रत्यक्षात कुठे आहे—एका सर्व्हिसमध्ये, तीन मायक्रोसर्व्हिसमध्ये, की एखाद्या लेगसी मॉड्यूलमध्ये ज्याला कोणीही स्पर्श करू इच्छित नाही? ते कशामुळे ट्रिगर होते: युजर क्लिक, शेड्युल केलेली cron job, की एखादा इनबाउंड webhook? काय डेटा इनपुट म्हणून जातो आणि काय आउटपुट म्हणून बाहेर येतो? आणि शेवटी, इतर कोणत्या सिस्टम्स त्यावर अवलंबून आहेत, म्हणजेच हा भाग काम करणे थांबवले तर काय बिघडेल?

अत्यंत प्रामाणिक राहा. जर तुमची "Customers" क्षमता एका Rails monolith, एका Node API आणि एका बाह्य CRM मध्ये विखुरलेली असेल, तर तसे तंतोतंत लिहा. तुमचा नकाशा प्रत्यक्ष भूभागासारखा (territory) दिसला पाहिजे, आर्किटेक्टच्या स्वप्नासारखा नाही.

सत्य लिहा, इच्छासूची (wishlist) नाही

कोणत्याही डॉक्युमेंटेशन प्रयत्नातील सर्वात धोकादायक वाक्य म्हणजे, "आम्ही हे लिहून घेताना, आपण ते सुधारून घेऊया." थांबा. तुम्ही चेकआउट फ्लो (checkout flow) पुन्हा डिझाइन करत नाही आहात. तुम्ही सध्या रिअल क्रेडिट कार्ड्स चार्ज करत असलेल्या चेकआउट फ्लोचे वर्णन करत आहात.

जर ऑर्डर देणे हे त्वरित पेमेंट कॅप्चर ट्रिगर करत असेल आणि त्यानंतर बॅकग्राउंड वर्करद्वारे ईमेल पाठवत असेल, तर त्या नेमक्या क्रमाने त्याचे डॉक्युमेंटेशन करा. तुम्ही पुढच्या तिमाहीत जोडण्याचे नियोजन करत असलेल्या इव्हेंट क्यू (event queue) चा त्यात समावेश करू नका. जर व्हॅलिडेशन प्रत्यक्षात एखाद्या सर्व्हिस क्लासच्या आत खोलवर असेल, तर ते API एजवर होते असे भासवू नका. महत्त्वाकांक्षा (aspiration) पेक्षा अचूकता (accuracy) अधिक महत्त्वाची आहे.

चुकीचे डॉक्युमेंटेशन नसण्यापेक्षाही वाईट असते. ते नवीन कर्मचाऱ्यांना अशा वर्तनाची अपेक्षा करण्यास प्रशिक्षित करते जे अस्तित्वातच नाही. ते AI कोडिंग असिस्टंट्सना केवळ इच्छांवर आधारित काल्पनिक मार्गांवर नेऊन चुकवते. जेव्हा तुमचे स्पेसिफिकेशन प्रोडक्शनशी जुळते, तेव्हा तुम्ही एक विश्वासार्ह बेसलाईन तयार करता. डीबगिंग (debugging) जलद होते कारण तुम्ही "अपेक्षित" फ्लोबद्दल अंदाज लावणे थांबवता. रिफॅक्टरिंग (refactoring) अधिक सुरक्षित होते कारण तुम्हाला माहित असते की सुरुवातीचा बिंदू वास्तविक आहे.

तुमच्या APIs मधून कॉन्ट्रॅक्ट्स (Contracts) काढा

तुमचे API एंडपॉइंट्स आधीच नियम लागू करतात. ते फक्त ते सुप्त (implicit) स्वरूपात ठेवतात. OpenSpec लागू करणे म्हणजे त्या नियमांना स्पष्टपणे समोर आणणे होय.

इनपुट आणि व्हॅलिडेशनपासून सुरुवात करा. एंडपॉइंट प्रत्यक्षात काय स्वीकारते? डेटाचे प्रकार (types), आवश्यक फील्ड्स (required fields), कमाल लांबी (maximum lengths) आणि क्रॉस-फील्ड डिपेंडन्सीजचे डॉक्युमेंटेशन करा. त्यानंतर व्यावसायिक वर्तनाचे (business behavior) वर्णन करा. हे कॉल एखादा रेकॉर्ड तयार करते, एखादा साईड इफेक्ट (side effect) ट्रिगर करते की केवळ दुसऱ्या सर्व्हिसविरुद्ध स्टेट (state) व्हॅलिडेट करते? नेमकेपणाने सांगा.

शेवटी, रिस्पॉन्सची (responses) यादी करा. यश (success) मिळाल्यावर काय परत मिळते? नेमके एरर कोड्स काय आहेत आणि कोणत्या परिस्थितीत ते दिसतात? "returns an error" असे लिहू नका. "billing address नसल्यास 422 परत करते आणि इन्व्हेंटरी आधीच दुसऱ्या प्रक्रियेद्वारे आरक्षित असल्यास 409 परत करते" असे लिहा. अचूकतेची ही पातळी एका अस्पष्ट रूटला अशा कॉन्ट्रॅक्टमध्ये रूपांतरित करते ज्यावर फ्रंटएंड टीम्स, QA इंजिनिअर्स आणि ऑटोमेटेड टूल्स विश्वास ठेवू शकतात.

लपलेले नियम शोधा

तुमच्या सिस्टममधील काही सर्वात मौल्यवान माहिती ही तफावतींमध्ये (gaps) दडलेली असते. ती सर्व्हिस क्लासेसमधील कंडिशनल ब्लॉक्समध्ये गाडलेली असते, डेटाबेस ट्रिगर्समध्ये लपलेली असते, किंवा अशा स्टोर्ड प्रोसिजर्समध्ये लिहिलेली असते ज्यांना गेल्या दोन वर्षांत कोणीही स्पर्श केलेला नाही. हे तुमचे बिझनेस रूल्स आहेत, आणि ते सहसा सिस्टम आउटेजच्या वेळी किंवा सुरुवातीपासून कार्यरत असलेल्या एकमेव इंजिनिअरला शोधून काढल्यावरच पुन्हा समोर येतात.

त्यांना प्रकाशात आणा. तुम्हाला आधीच माहित असलेल्या नियमांपासून सुरुवात करा. ठराविक मूल्यापेक्षा जास्त असलेल्या ऑर्डर्ससाठी प्रक्रिया पुढे नेण्यापूर्वी मॅनेजरची मंजुरी आवश्यक असते. निष्क्रिय युजर अकाउंट्स नवीन ऑर्डर्स तयार करू शकत नाहीत. सेटलमेंट पूर्ण होण्यापूर्वीच रिफंडची परवानगी दिली जाते. प्रत्येक नियम ज्या कार्यक्षमतेशी संबंधित आहे, त्याच्या शेजारी तो अशा स्पष्ट भाषेत लिहा की एखादा प्रोडक्ट मॅनेजर कोणत्याही ट्रान्सलेटरशिवाय तो वाचू शकेल.

जेव्हा तुम्ही हे नियम केंद्रीकृत करता, तेव्हा तुम्ही केवळ त्यांचे दस्तऐवजीकरण करत नाही. तुम्ही ड्युप्लिकेशन (duplication) समोर आणता. तुम्ही संघर्षांचे (conflicts) दर्शन घडवता. आणि तुम्ही संपूर्ण टीमला धोरणावर चर्चा करण्यासाठी एकच जागा देता, जेणेकरून कोणीतरी असा एक-ओळीचा बदल (one-line change) करू नये ज्यामुळे चुकून अशा एखाद्या मर्यादेचे (constraint) उल्लंघन होईल जी तुम्ही विसरला होतात.

प्लंबिंग मॅप करा

आधुनिक सिस्टम्स इव्हेंट्सवर (events) चालतात. एका सर्व्हिसमधील कृती युजरपर्यंत काही दृश्य पोहोचण्यापूर्वी इतर सहा सर्व्हिसेसवर परिणाम (ripples) करते. तुम्हाला या परिणामांचा नकाशा तयार करण्याची गरज आहे. तुमच्या मुख्य वर्कफ्लोसाठी एका इव्हेंटपासून दुसऱ्या इव्हेंटपर्यंतचा प्रवाह मॅप करा. 'ऑर्डर तयार झाली' (Order created) मुळे 'इन्व्हेंटरी रिझर्व्ह' (inventory reserved) होते, त्यानंतर 'पेमेंट कन्फर्म' (payment confirmed) होण्याची प्रतीक्षा केली जाते. संपूर्ण साखळी काढा, जरी त्यातील काही दुवे कमकुवत वाटत असले किंवा वेगळे प्रोटोकॉल्स वापरत असले तरीही.

केवळ अंतर्गत ट्रॅफिकपुरते मर्यादित राहू नका. तुम्ही त्यांना तसे मानत असो वा नसो, बाह्य सर्व्हिसेस (external services) तुमच्या सिस्टमचा भाग असतात. प्रत्येक इंटिग्रेशनसाठी, त्याचा उद्देश, तुमचे ॲप्लिकेशन कसे ऑथेंटिकेट (authenticate) करते आणि ते कसे फेल होते, याची नोंद करा. पेमेंट गेटवे तीस सेकंदांनंतर टाइमआउट होतो आणि सामान्य ५०० एरर देतो का? शिपिंग API वीकेंडला मॅलफॉर्मड JSON (malformed JSON) परत करते का? आयडेंटिटी प्रोव्हायडर त्याच्या स्वतःच्या डॉक्युमेंटेशनपेक्षा लवकर रिफ्रेश टोकन्स रद्द करतो का? हे तपशील साधे वाटू शकतात