AI سیریز انٹرویو 16: اچھی Spec Coding کیسی ہونی چاہیے؟

ایک اچھی Spec Coding (اسپیک ڈرائیون پروگرامنگ) کا مرکز "مبہم خیالات" کو "درست، قابل تصدیق اور قابل عمل معاہدے" میں تبدیل کرنا ہے۔ یہ صرف ایک دستاویز لکھنا نہیں ہے، بلکہ انسان اور AI (یا انسان اور انسان) کے درمیان غیر مبہم مواصلاتی زبان قائم کرنا ہے۔ ذیل میں میں مواد کی ساخت، تحریر کے اصول، AI کے ساتھ تعاون کا عمل، اور معیار کی تصدیق کے چار جہتوں سے ایک اچھی spec کی شکل بیان کروں گا۔

一、اسپیک دستاویز کا معیاری ڈھانچہ (فنکشنل ماڈیول کی مثال کے ساتھ)

باب	لازمی مواد	مثال
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`"

ٹیسٹ کیسز کی مثال (اسپیک میں شامل)

منظر نامہ	ان پٹ	متوقع آؤٹ پٹ
عام رجسٹریشن	email: `a@b.com`, pwd: `Pass1234`	`201`، `user_id` لوٹائیں
پاس ورڈ بہت چھوٹا	pwd: `Ab1`	`400`، ایرر کوڈ `WEAK_PASSWORD`
ای میل پہلے سے موجود	وہی email	`409`، ایرر کوڈ `EMAIL_EXISTS`

اچھی Spec میں پہلے ٹیسٹ کیسز لکھنے چاہئیں، کیونکہ AI ان کی بنیاد پر براہ راست یونٹ ٹیسٹ بنا سکتا ہے اور تکمیل کے بعد خود بخود تصدیق کر سکتا ہے۔

二、اسپیک لکھنے کے بنیادی اصول (SMART کی تبدیلی)

اصول	وضاحت	متضاد مثال
درست (Precise)	مخصوص نمبر، اقسام، بولیئن شرائط استعمال کریں، "جتنا ممکن ہو"، "عام طور پر" سے گریز کریں	❌ "پاس ورڈ کافی محفوظ ہو" → ✅ "پاس ورڈ کم از کم 8 حروف، بڑی، چھوٹی حرف اور عدد پر مشتمل ہو"
قابل تصدیق (Verifiable)	ہر ضرورت خودکار ٹیسٹ یا دستی جانچ سے کامیاب/ناکام فیصلہ کی جا سکے	❌ "کوڈ خوبصورت ہو" → ✅ "فنکشن کی سائکلی میٹک کمپلیکسیٹی ≤ 10، کوئی ڈپلیکیٹ کوڈ بلاک نہ ہو"
غیر مبہم (Unambiguous)	ایک ہی اصطلاح پوری دستاویز میں ایک ہی معنی رکھتی ہو، ضرورت ہو تو لغت دیں	❌ "اگر صارف موجود نہیں ہے تو ایرر لوٹائیں" → ✅ "صارف موجود نہیں → `404` اور `{code: 'USER_NOT_FOUND'}` لوٹائیں"
مکمل (Complete)	خوشی کا راستہ، تمام غیر معمولی راستے، غیر فعالی کی ضروریات کا احاطہ کریں	❌ صرف کامیابی کا منظر نامہ لکھا → ✅ ڈیٹا بیس ٹائم آؤٹ، ناکافی اجازت وغیرہ شامل ہوں
ایٹمی (Atomic)	ایک اسپیک صرف ایک آزادانہ طور پر فراہم کردہ فیچر پوائنٹ بیان کرے (AI کے ایک بار مکمل کرنے کے لیے)	❌ ایک اسپیک میں "پورا ادائیگی کا نظام" لکھنا → ✅ "ادائیگی کا آرڈر بنانا"، "کال بیک دستخط کی تصدیق"، "ریفنڈ" میں تقسیم کریں

三、AI کے ساتھ تعاون میں Spec Coding کا عمل

انسان اسپیک لکھتا ہے (مندرجہ بالا ڈھانچہ، خاص طور پر ٹیسٹ کیسز اور فنکشن سگنیچر اچھی طرح لکھے)۔
اسپیک ایک ہی بار میں AI کو دیں (مکالمے کی صورت میں مزید ضروریات نہ شامل کریں، وائب آلودگی سے بچیں)۔
AI کوڈ + یونٹ ٹیسٹ آؤٹ پٹ کرتا ہے (AI کو اسپیک میں موجود ٹیسٹ کیسز کے مطابق قابل عمل ٹیسٹ بنانا ضروری ہے)۔
ٹیسٹ چلائیں: اگر سب کامیاب ہوں تو اگلے مرحلے پر جائیں؛ اگر نہ ہوں تو اسپیک میں ترمیم کریں یا براہ راست کوڈ درست کریں (اس وقت چھوٹا لوپ ممکن ہے لیکن تبدیلیاں ریکارڈ کریں)۔
انسانی جانچ: چیک کریں کہ اسپیک سے باہر کی کوئی فعالیت تو شامل نہیں (scope creep)، سیکیورٹی/کارکردگی چیک کریں۔
مستحکم کریں: اسپیک دستاویز اور حتمی کوڈ کو ایک ساتھ ریپوزٹری میں جمع کریں، مستقل دستاویز کے طور پر۔

اہم عمل: اسپیک کو کوڈ میں تبدیل کریں — spec.md + test_spec.py استعمال کریں، جہاں ٹیسٹ فائل براہ راست اسپیک کی مثالوں سے بنی ہو، تاکہ بعد میں کوڈ میں تبدیلی پر صرف ٹیسٹ چلا کر اسپیک کی خلاف ورزی کی تصدیق کی جا سکے۔

四、اچھی Spec کے اثرات (قبولیت کے معیار کے طور پر)

یقینیت: ایک ہی اسپیک مختلف AI (یا مختلف افراد) کو دے کر قریب قریب ایک جیسا نفاذ حاصل کیا جا سکے۔
قابل آزمائشیت: کوڈ لکھنے کے فوراً بعد 90% درستگی خود بخود تصدیق کی جا سکے۔
قابل برقراریت: چھ ماہ بعد کوئی بھی اسپیک دیکھ کر اصل ڈیزائن کے ارادے کو سمجھ سکے۔
کم مواصلاتی لاگت: ٹیم میں بحث صرف اسپیک پر ہو، کوڈ کی لائنوں پر نہیں۔
بلٹ ان سیکیورٹی/معیار: سیکیورٹی کی ضروریات (جیسے پیرامیٹرائزڈ کوئری) اور حدود کی شرائط اسپیک میں واضح ہوں، AI کو ان پر عمل کرنا ضروری ہو۔

五、ایک اچھی Spec کی مثال (انتہائی مختصر)

# Spec: یوزر رجسٹریشن API

## دائرہ کار
- email، password وصول کرتا ہے
- تصدیقی ای میل نہیں بھیجتا، ای میل کی حقیقت کی جانچ نہیں کرتا

## معاہدہ
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" }

## رویہ
- email RFC 5322 بنیادی فارمیٹ (a@b.c) پر پورا اترنا چاہیے
- password: لمبائی 8-20، کم از کم ایک عدد اور ایک بڑا حرف
- bcrypt سے انکرپٹ کر کے محفوظ کریں، نمک لاگت 10
- اگر ڈیٹا بیس میں ڈالنے سے پہلے email پہلے سے موجود ہے تو → 409

## ٹیسٹ کیسز (ان پٹ -> متوقع اسٹیٹس کوڈ+رسپانس فیلڈ)
| ان پٹ email | password | متوقع |
|------------|----------|------|
| 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 Coding = انسان کے "ڈیزائن کے فیصلوں" کو مشین کے "ٹیسٹ کیسز + ٹائپ سگنیچر + رویے کی پابندیوں" میں تبدیل کرنا، تاکہ AI صرف نفاذ بھرے، جبکہ انسان ہمیشہ معیار اور سمت پر قابو رکھے۔