AI seriyali intervyu 16: Yaxshi spec coding qanday bo'lishi kerak?

Yaxshi Spec Coding (spetsifikatsiyaga asoslangan dasturlash) ning mohiyati "loyqa fikrlar"ni "aniq, tekshiriladigan va bajariladigan shartnoma"ga aylantirishdir. Bu shunchaki hujjat yozish emas, balki odam va AI (yoki odamlar o'rtasida) bir ma'noli muloqot tili yaratishdir. Quyida men spetsifikatsiya mazmuni tuzilishi, yozish tamoyillari, AI bilan hamkorlik jarayoni va sifatni tekshirish to'rt o'lchovidan yaxshi spec qanday bo'lishini ko'rsataman.

1. Spetsifikatsiya hujjatining standart tuzilishi (funksional modul misolida)

Bo'lim	Majburiy tarkib	Misol
1. Maqsad va doira	Bir gap bilan nima qilish, nima qilmaslikni aniqlash	"Foydalanuvchi ro'yxatdan o'tish API'ni amalga oshirish, email tasdiqlashni o'z ichiga olmaydi"
2. Kiritish/chiqarish shartnomasi	Ma'lumot tuzilishi, turi, majburiy/ixtiyoriy maydonlar, misol qiymatlar	`POST /register` so'rov tanasi `{email: string, password: string}`, javob `201` yoki `400` xato kodi bilan
3. Xatti-harakat va mantiq	Biznes qoidalari, chegara shartlari, holat o'tishlari	"Parol uzunligi 8-20 belgi, kamida bitta raqam bo'lishi kerak; email mavjud bo'lsa `409` qaytarish"
4. Xatolarni qayta ishlash	Barcha mumkin bo'lgan istisno stsenariylari va tegishli xato kodlari/xabarlari	"Ma'lumotlar bazasiga ulanish muvaffaqiyatsiz → `503` qaytarish, stekni ko'rsatmaslik"
5. Funktsional bo'lmagan talablar	Ishlash (javob vaqti < 200ms), xavfsizlik (parametrlashtirilgan so'rovlar), loglar, kuzatiluvchanlik	"Barcha SQL so'rovlari prekompilyatsiya qilingan bo'lishi kerak; `email`ni yozib olish, lekin `password`ni yozib olmaslik"
6. Test holatlari (muhim)	Kamida 3 ta tipik kiritish + 2 ta chegara/istisno kiritish, kutilgan chiqishni ko'rsatish	Quyidagi jadvalga qarang
7. Bog'liqlik va cheklovlar	Qaysi kutubxona, versiya, muhit o'zgaruvchilari ishlatiladi	"Python 3.10+, FastAPI, muhit o'zgaruvchisi `DB_URL`"

Spec ichiga o'rnatilgan test holatlari misoli

Stsenariy	Kiritish	Kutilgan chiqish
Oddiy ro'yxatdan o'tish	email: `a@b.com`, pwd: `Pass1234`	`201`, `user_id` qaytariladi
Parol juda qisqa	pwd: `Ab1`	`400`, xato kodi `WEAK_PASSWORD`
Email allaqachon mavjud	Yuqoridagi email	`409`, xato kodi `EMAIL_EXISTS`

Yaxshi Spec avval test holatlarini yozishi kerak, chunki AI ular asosida to'g'ridan-to'g'ri unit testlarni yaratishi va keyin avtomatik tekshirishi mumkin.

2. Spec yozishning asosiy tamoyillari (SMART varianti)

Tamoyil	Izoh	Qarshi misol
Aniq (Precise)	Aniq raqamlar, turlar, mantiqiy shartlarni ishlating; "iloji boricha", "odatda" kabi so'zlardan qoching	❌ "Parol yetarlicha xavfsiz bo'lishi kerak" → ✅ "Parol kamida 8 belgidan iborat, katta va kichik harflar hamda raqamni o'z ichiga olishi kerak"
Tekshiriladigan (Verifiable)	Har bir talab avtomatik test yoki qo'lda tekshirish orqali o'tish/muvaffaqiyatsizlikka aniqlanishi mumkin	❌ "Kod chiroyli bo'lishi kerak" → ✅ "Funksiyaning siklomatik murakkabligi ≤ 10, takrorlanuvchi kod bloklari yo'q"
Bir ma'noli (Unambiguous)	Bir xil atama butun matn bo'ylab bir xil ma'noga ega; zarur bo'lganda glossary bering	❌ "Agar foydalanuvchi topilmasa, xato qaytarish" → ✅ "Foydalanuvchi topilmasa → `404` va `{code: 'USER_NOT_FOUND'}` qaytarish"
To'liq (Complete)	Baxtli yo'lni, barcha istisno yo'llarini, funktsional bo'lmagan talablarni qamrab olish	❌ Faqat muvaffaqiyatli stsenariy yozilgan → ✅ Ma'lumotlar bazasi vaqti tugashi, ruxsat etishmasligi kabilarni o'z ichiga oladi
Atomik (Atomic)	Bitta spec faqat mustaqil yetkazib beriladigan funksiyani tavsiflaydi (AI bir marta bajarishi uchun qulay)	❌ "Butun to'lov tizimi"ni bitta spec bilan yozish → ✅ "To'lov slipini yaratish", "Qayta qo'ng'iroq imzosini tekshirish", "Pulni qaytarish"ga ajratish

3. AI bilan hamkorlikda Spec Coding jarayoni

Inson spec yozadi (yuqoridagi tuzilmada, ayniqsa test holatlari va funksiya imzolarini yaxshi yozadi).
Specni bir vaqtning o'zida AI ga beradi (dialoq orqali talablarni qo'shib yubormang, vibe ifloslanishidan saqlaning).
AI kod + unit testlarni chiqaradi (AI spec'dagi test holatlari bo'yicha bajariladigan testlarni yaratishi kerak).
Testlarni ishga tushiring: agar hammasi o'tsa, keyingi bosqichga o'ting; aks holda specni o'zgartiring yoki kodni to'g'ridan-to'g'ri tuzating (kichik siklga kirish mumkin, lekin o'zgarishlarni yozib boring).
Inson tekshiruvi: specdan tashqari funksiyalar kiritilganligini (scope creep), xavfsizlik/ishlashni tekshiring.
Mustahkamlash: spec hujjatini va yakuniy kodni omborga birga joylang, doimiy hujjat sifatida.

Muhim amaliyot: Specni kodlashtirish – spec.md + test_spec.py dan foydalaning, test fayli to'g'ridan-to'g'ri spec'dagi misollardan olingan bo'lsin. Keyinchalik kodni o'zgartirganda testlarni ishga tushirib, spec buzilganligini tekshirish mumkin.

4. Yaxshi specning ta'siri (qabul qilish mezonlari sifatida)

Aniqlik: bir xil specni turli AI (yoki turli odamlar)ga berilsa, o'xshash amalga oshirish hosil bo'ladi.
Tekshiriluvchanlik: kod yozilgandan so'ng darhol 90% to'g'rilikni avtomatik tekshirish mumkin.
Qo'llab-quvvatlanuvchanlik: olti oydan keyin har kim specni o'qib, dastlabki dizayn maqsadini tushuna oladi.
Kam muloqot xarajati: jamoa muhokamasi faqat specga qaratiladi, aniq kod satrlariga emas.
O'rnatilgan xavfsizlik/sifat: xavfsizlik talablari (masalan, parametrlashtirilgan so'rovlar) va chegara shartlari specda yozilgan, AI ularga rioya qilishi kerak.

5. Yaxshi Spec namunasi (juda soddalashtirilgan)

# Spec: Foydalanuvchi ro'yxatdan o'tish API

## Doira
- email, password qabul qiladi
- Tasdiqlash xati yubormaydi, email haqiqiyligini tekshirmaydi

## Shartnoma
POST /register
Content-Type: application/json
So'rov: { "email": string, "password": string }
Javob 201: { "user_id": string }
Javob 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Javob 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Xatti-harakat
- email RFC 5322 asosiy formatiga mos kelishi kerak (a@b.c)
- password: uzunligi 8-20, kamida bitta raqam va bitta katta harf
- bcrypt bilan shifrlash, tuz qiymati 10
- Agar ma'lumotlar bazasiga saqlashdan oldin email mavjud bo'lsa → 409

## Test holatlari (kiritish -> kutilgan holat kodi+javob maydoni)
| email | password | Kutilgan |
|-------|----------|----------|
| test@x.com | Pass1234 | 201, user_id mavjud |
| test@x.com | pass | 400, INVALID_PASSWORD |
| bad | Pass1234 | 400, INVALID_EMAIL |
| (mavjud email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Funktsional bo'lmagan
- SQL so'rovlari parametrlashtirilgan bo'lishi kerak (in'ektsiyadan himoya)
- Logga ro'yxatdan o'tish manbai IP yoziladi, password yozilmaydi
- Javob vaqti 95% so'rov < 100ms (bcryptdan tashqari)

## Bog'liqlik
- Python 3.10+, FastAPI, bcrypt, asyncpg

Yaxshi Spec Coding = insonning "dizayn qarorlari"ni mashinaning "test holatlari + tur imzolari + xatti-harakat cheklovlari"ga aylantirish, AI faqat amalga oshirishni to'ldirishi bilan shug'ullanadi, inson esa sifat va yo'nalishni nazorat qiladi.