آپ ڈویلپمنٹ کو روک نہیں سکتے۔ یہ پہلی چیز ہے جسے آپ کو تسلیم کرنا ہوگا۔ ٹکٹیں آتی رہتی ہیں، صارفین ترسیل (shipments) کی توقع رکھتے ہیں، اور آپ کا موجودہ کوڈ صرف اس لیے نہیں رکتا کیونکہ آپ نے اسے دستاویز (document) کرنے کا فیصلہ کیا ہے۔ کوئی بھی انجینئرنگ مینیجر ایک ماہ کے وقفے کی اجازت نہیں دے گا تاکہ ٹیم وہ سپیسیفیکیشن لکھ سکے جو پہلے دن سے موجود ہونی چاہیے تھی۔ OpenSpec حقیقت کے لیے بنایا گیا ہے، نہ کہ خیالی منصوبوں کے لیے۔ یہ اس وقت بہترین کام کرتا ہے جب آپ اسے اپنی موجودہ چیزوں کے ساتھ جوڑ دیتے ہیں، صارفین سمیت۔
یہاں مقصد دوبارہ لکھنا (rewrite) نہیں ہے۔ یہ ایک ایماندارانہ کھوج (archaeology) ہے۔ آپ اس چیز کو تلاش کرتے ہیں جو حقیقت میں پروڈکشن میں چل رہی ہے، اس کی درست وضاحت کرتے ہیں، اور جیسے جیسے آپ کا کوڈ بدلتا ہے، اس وضاحت کو بھی بدلنے دیتے ہیں۔ جب آپ کی سپیسیفیکیشن آپ کے سسٹم سے مطابقت رکھتی ہے، تو آپ ان انجینئرز کے لیے زندگی آسان بنا دیتے ہیں جو اگلی سہ ماہی میں شامل ہوں گے اور ان AI ٹولز کے لیے جو اب آپ کے IDE میں موجود ہیں۔ یہاں بتایا گیا ہے کہ ایک بھی ریلیز مس کیے بغیر یہ کیسے کیا جائے۔
اس سے شروع کریں جو آپ حقیقت میں کرتے ہیں
اپنی ریپوزٹری کھولیں اور آپ کو controllers، models، services اور utils کے نام سے فولڈرز نظر آئیں گے۔ یہ تکنیکی تہیں (technical layers) ہیں، اور یہ آپ سے جھوٹ بولتی ہیں۔ یہ اس بات کی وضاحت نہیں کرتیں کہ آپ کا سسٹم کاروبار کے لیے کیا کرتا ہے۔ JavaScript فائلوں سے بھرا ہوا ایک فولڈر یہ نہیں بتاتا کہ ایک آرڈر کیسے شپمنٹ بنتا ہے۔ OpenSpec کو ریٹرو فٹ کرنے کے لیے، آپ کو صلاحیتوں (capabilities) کے بارے میں سوچنے کی ضرورت ہے۔
ان مستحکم کاروباری آپریشنز کو تلاش کریں جو اس صورت میں بھی برقرار رہیں گے اگر آپ پورا اسٹیک کسی دوسری زبان میں دوبارہ لکھ دیں۔ زیادہ تر پروڈکٹ کمپنیوں میں، یہ بار بار سامنے آتے ہیں: Orders، Billing، Inventory، Customers، اور Notifications۔ ان میں سے پانچ سے آٹھ بنیادی صلاحیتوں کے نام لکھیں۔
ہر ایک کے لیے، خود کو پانچ مخصوص سوالات کے جواب دینے پر مجبور کریں۔ یہ صلاحیت حقیقی دنیا کے کس مسئلے کو حل کرتی ہے؟ کوڈ اصل میں کہاں موجود ہے—ایک سروس میں، تین مائیکرو سروسز میں، یا کسی ایسے لیگیسی ماڈیول میں جسے کوئی چھونا نہیں چاہتا؟ اسے کیا چیز ٹرگر کرتی ہے: صارف کا کلک، ایک شیڈول شدہ کرون جاب (cron job)، یا ان باؤنڈ ویب ہک (inbound webhook)؟ کون سا ڈیٹا اندر جاتا ہے اور کون سا ڈیٹا باہر آتا ہے؟ اور آخر میں، کون سے دوسرے سسٹم اس پر انحصار کرتے ہیں، یعنی اگر یہ حصہ کام کرنا بند کر دے تو کیا ٹوٹ جائے گا؟
بے حد ایماندار رہیں۔ اگر آپ کی "Customers" کی صلاحیت ایک Rails monolith، ایک Node API، اور ایک بیرونی CRM میں پھیلی ہوئی ہے، تو اسے بالکل ویسے ہی لکھیں۔ آپ کا نقشہ حقیقت کی طرح نظر آنا چاہیے، نہ کہ کسی آرکیٹیکٹ کے خواب کی طرح۔
سچ لکھیں، خواہشات کی فہرست نہیں
کسی بھی ڈاکومنٹیشن کی کوشش میں سب سے خطرناک جملہ یہ ہے، "جب ہم اسے لکھ ہی رہے ہیں، تو کیوں نہ اسے ٹھیک بھی کر لیا جائے۔" رک جائیں۔ آپ چیک آؤٹ فلو کو دوبارہ ڈیزائن نہیں کر رہے ہیں۔ آپ اس چیک آؤٹ فلو کی وضاحت کر رہے ہیں جو اس وقت حقیقی کریڈٹ کارڈز چارج کر رہا ہے۔
اگر آرڈر دینے سے فوری طور پر پیمنٹ کیپچر ٹرگر ہوتا ہے اور پھر بیک گراؤنڈ ورکر کے ذریعے ای میل بھیجی جاتی ہے، تو اسی ترتیب کو دستاویز کریں۔ وہ ایونٹ کیو (event queue) شامل نہ کریں جسے آپ اگلی سہ ماہی میں شامل کرنے کا منصوبہ بنا رہے ہیں۔ یہ ظاہر نہ کریں کہ ویلیڈیشن API ایج پر ہوتی ہے اگر وہ حقیقت میں کسی سروس کلاس کے اندر گہرائی میں موجود ہے۔ خواہش سے زیادہ درستگی کی اہمیت ہے۔
غلط ڈاکومنٹیشن نہ ہونے سے بھی بدتر ہے۔ یہ نئے ملازمین کو ایسی طرزِ عمل کی توقع کرنے کی تربیت دیتی ہے جو موجود ہی نہیں ہے۔ یہ AI کوڈنگ اسسٹنٹ کو خواہشات کی بنیاد پر خیالی راستوں پر لے جاتی ہے۔ جب آپ کی سپیسیفیکیشن پروڈکشن سے مطابقت رکھتی ہے، تو آپ ایک قابل اعتماد بنیاد بناتے ہیں۔ ڈی بگنگ تیز ہو جاتی ہے کیونکہ آپ "مقصود" فلو کے بارے میں اندازے لگانا چھوڑ دیتے ہیں۔ ریفیکٹورنگ محفوظ ہو جاتی ہے کیونکہ آپ جانتے ہیں کہ شروعاتی نقطہ حقیقی ہے۔
اپنی APIs سے کنٹریکٹس نکالیں
آپ کے API اینڈ پوائنٹس پہلے ہی قوانین نافذ کرتے ہیں۔ وہ بس انہیں غیر واضح (implicit) رکھتے ہیں۔ OpenSpec کو ریٹرو فٹ کرنے کا مطلب ان قوانین کو سامنے لانا ہے۔
ان پٹس اور ویلیڈیشن سے شروع کریں۔ اینڈ پوائنٹ اصل میں کیا قبول کرتا ہے؟ ٹائپس، ضروری فیلڈز، زیادہ سے زیادہ لمبائی، اور کراس فیلڈ ڈیپینڈنسیز کو دستاویز کریں۔ پھر کاروباری طرزِ عمل کی وضاحت کریں۔ کیا یہ کال کوئی ریکارڈ بناتی ہے، کوئی سائیڈ ایفیکٹ (side effect) پیدا کرتی ہے، یا صرف کسی دوسری سروس کے خلاف اسٹیٹ کی تصدیق کرتی ہے؟ مخصوص رہیں۔
آخر میں، رسپانسز کی فہرست بنائیں۔ کامیابی (success) کیا واپس کرتی ہے؟ درست ایرر کوڈز کیا ہیں اور کن حالات میں وہ ظاہر ہوتے ہیں؟ یہ نہ لکھیں کہ "ایرر واپس کرتا ہے۔" لکھیں کہ "جب بلنگ ایڈریس موجود نہ ہو تو 422 واپس کرتا ہے اور جب انوینٹری پہلے ہی کسی دوسرے عمل کے ذریعے ریزرو ہو چکی ہو تو 409 واپس کرتا ہے۔" درستگی کا یہ درجہ ایک مبہم روٹ کو ایک ایسے کنٹریکٹ میں بدل دیتا ہے جس پر فرنٹ اینڈ ٹیمیں، QA انجینئرز، اور خودکار ٹولز بھروسہ کر سکیں۔
چھپے ہوئے قوانین کی تلاش کریں
آپ کے سسٹم میں سب سے قیمتی معلومات اکثر ان خلاؤں میں چھپی ہوتی ہیں جن پر توجہ نہیں دی جاتی۔ یہ سروس کلاسز (service classes) کے اندر کنڈیشنل بلاکس میں دفن ہوتی ہیں، ڈیٹا بیس ٹرگرز (database triggers) میں چھپی ہوتی ہیں، یا ایسے اسٹورڈ پروسیجرز (stored procedures) میں لکھی ہوتی ہیں جنہیں دو سال سے کسی نے چھوا تک نہ ہو۔ یہ آپ کے بزنس رولز (business rules) ہیں، اور ان کا دوبارہ پتہ عام طور پر سسٹم کے تعطل (outages) کے دوران یا اس واحد انجینئر سے پوچھ کر چلتا ہے جو شروع سے وہاں موجود ہے۔
انہیں سامنے لائیں۔ ان سے شروع کریں جنہیں آپ پہلے سے جانتے ہیں۔ ایک خاص رقم سے زیادہ کے آرڈرز کو آگے بڑھنے سے پہلے منیجر کی منظوری کی ضرورت ہوتی ہے۔ غیر فعال صارف اکاؤنٹس نئے آرڈرز نہیں بنا سکتے۔ ریفنڈز صرف سیٹلمنٹ مکمل ہونے سے پہلے ہی ممکن ہیں۔ ہر رول کو اس کی متعلقہ صلاحیت (capability) کے ساتھ اس زبان میں لکھیں جو اتنی واضح ہو کہ ایک پروڈکٹ منیجر اسے کسی مترجم کے بغیر پڑھ سکے۔
جب آپ ان رولز کو ایک جگہ جمع کرتے ہیں، تو آپ صرف انہیں دستاویز نہیں بناتے بلکہ اس سے کہیں زیادہ کرتے ہیں۔ آپ تکرار (duplication) کو بے نقاب کرتے ہیں۔ آپ تضادات کو ظاہر کرتے ہیں۔ اور آپ پوری ٹیم کو پالیسی پر بحث کرنے کے لیے ایک واحد جگہ فراہم کرتے ہیں، تاکہ کوئی ایسا ایک لائن کا بدلاؤ نہ کر دے جو غلطی سے کسی ایسی پابندی (constraint) کی خلاف ورزی کر دے جسے آپ بھول چکے ہوں۔
سسٹم کے بنیادی ڈھانچے کا نقشہ بنائیں
جدید سسٹمز ایونٹس (events) پر چلتے ہیں۔ ایک سروس میں ہونے والا ایک عمل صارف تک کچھ نظر آنے سے پہلے درجن بھر دوسری سروسز پر اثر انداز ہوتا ہے۔ آپ کو ان اثرات کا نقشہ تیار کرنے کی ضرورت ہے۔ اپنے بنیادی ورک فلو (workflows) کے لیے ایک ایونٹ سے دوسرے ایونٹ تک کے بہاؤ کا نقشہ بنائیں۔ آرڈر تخلیق ہونے سے لے کر انوینٹری ریزرو ہونے تک، اور پھر ادائیگی کی تصدیق کا انتظار کرنے تک کا پورا سلسلہ بنائیں۔ مکمل زنجیر بنائیں، چاہے اس کے کچھ حصے کمزور محسوس ہوں یا مختلف پروٹوکولز استعمال کر رہے ہوں۔
صرف اندرونی ٹریفک پر نہ رکیں۔ بیرونی سروسز بھی آپ کے سسٹم کا حصہ ہیں، چاہے آپ انہیں اس طرح سمجھیں یا نہ سمجھیں۔ ہر انٹیگریشن (integration) کے لیے، اس کا مقصد، آپ کی ایپلی کیشن کس طرح آتھنٹیکیٹ (authenticate) کرتی ہے، اور وہ کس طرح فیل ہوتی ہے، اسے ریکارڈ کریں۔ کیا پیمنٹ گیٹ وے تیس سیکنڈ کے بعد ٹائم آؤٹ ہو جاتا ہے اور ایک عام 500 ایرر دیتا ہے؟ کیا شپنگ API ہفتہ وار تعطیلات پر غلط فارمیٹ شدہ (malformed) JSON واپس کرتی ہے؟ کیا آئیڈنٹیٹی فراہم کنندہ (identity provider) اپنی دستاویزات میں کیے گئے دعوے سے پہلے ہی ریفریش ٹوکن منسوخ کر دیتا ہے؟ یہ تفصیلات معمولی لگتی ہیں