AI сериясы 16: Жакшы spec coding кандай болушу керек?

Жакшы Spec Coding (спецификация менен башкаруу програмдоо) негизинен "түшүнүксүз ойду" "так, текшерилүүчү жана аткарылуучу келишимге" айландырат. Бул жөн гана документ жазуу эмес, адам менен AI (же адам менен адам) ортосунда эки маанисиз байланыш тилин түзүү. Төмөндө спецификациянын мазмун структурасы, жазуу принциптери, AI менен кызматташуу процесси, сапатты текшерүү деген төрт өлчөмдөн жакшы specтин көрүнүшүн берем.

I. Спецификация документинин стандарттык структурасы (функция модулу менен мисал)

Бөлүм	Милдеттүү мазмун	Мисал
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ке киргизилген)

Сценарий	Кириш	Күтүлгөн чыгыш
Кадимки каттоо	email: `a@b.com`, pwd: `Pass1234`	`201`, `user_id` кайтарылат
Сыр сөздүн өтө кыска болушу	pwd: `Ab1`	`400`, ката коду `WEAK_PASSWORD`
Электрондук почтанын бар болушу	ошол эле email	`409`, ката коду `EMAIL_EXISTS`

Жакшы Spec адегенде тест учурларын жазууну талап кылат, анткени AI алардын негизинде түздөн-түз бирдик тесттерин түзүп, бүткөндөн кийин автоматтык түрдө текшере алат.

II. Spec жазуунун негизги принциптери (SMART вариант)

Принцип	Түшүндүрмө	Каршы мисал
Так (Precise)	Конкреттүү сандарды, түрлөрдү, логикалык шарттарды колдонуу, "мүмкүн", "адатта" сыяктуу сөздөрдөн качуу	❌ "Сыр сөз жетиштүү коопсуз болсун" → ✅ "Сыр сөз жок дегенде 8 белгиден, бир чоң тамга, бир кичине тамга жана бир сандан турсун"
Текшерилүүчү (Verifiable)	Ар бир талап автоматтык тест же кол менен текшерүү аркылуу өтүү/өтпөө деп аныкталсын	❌ "Код элеганттуу болсун" → ✅ "Функциянын цикломатикалык татаалдыгы ≤ 10, кайталанган код блоктору жок"
Эки маанисиз (Unambiguous)	Бир эле термин бүт текстте бирдей мааниде колдонулсун, зарыл болсо glossary берилсин	❌ "Эгер колдонуучу жок болсо, ката кайтар" → ✅ "Колдонуучу жок болсо → `404` жана `{code: 'USER_NOT_FOUND'}` кайтар"
Толук (Complete)	Бактылуу жолду, бардык өзгөчө жолдорду, функциялык эмес талаптарды камтысын	❌ Ийгиликтүү сценарий гана жазылган → ✅ Маалымат базасынын убактысы өтүү, укуктун жетишсиздиги ж.б. камтылган
Атомдук (Atomic)	Бир spec бир гана өз алдынча жеткирүүгө боло турган функцияны сүрөттөсүн (AI бир жолу бүтүрүү үчүн)	❌ "Бүт төлөм системасын" бир spec менен жазуу → ✅ "Төлөм буйрук түзүү", "Кайра чакыруу кол тамгасын текшерүү", "Кайтаруу" болуп бөлүнүү

III. AI менен кызматташуудагы Spec Coding процесси

Адам spec жазат (жогорудагы структура, өзгөчө тест учурларын жана функция сигнатураларын жакшы жазуу).
Spec бир жолу AIге берилет (диалог аркылуу кошумча талаптарды кошпоңуз, vibe булгануудан сактаныңыз).
AI код + бирдик тесттерин чыгарат (AI specтеги тест учурларына ылайык аткарылуучу тесттерди түзүшү керек).
Тесттерди иштетүү: Эгер бардыгы өтсө, кийинки кадамга өтүү; өтпөсө, specти өзгөртүү же кодду түздөн-түз оңдоо (бул учурда кичине циклге кирсе болот, бирок өзгөртүүлөрдү жазып коюу керек).
Адамдык текшерүү: Specтен тышкаркы функциялардын кошулбаганын (scope creep), коопсуздук/өндүрүмдүүлүктү текшерүү.
Бекемдөө: Spec документин жана акыркы кодду репозиторийге бирге жүктөө, түбөлүк документ катары сактоо.

Негизги практика: Spec коддондуруу — spec.md + test_spec.py колдонуу, мында тест файлы specтеги мисалдардан түз алынат, кийинчерээк кодду өзгөртүүдө тесттерди иштетип, specтин бузулбаганын текшерүү жетиштүү.

IV. Жакшы Specтин натыйжалары (кабыл алуу критерийлери катары)

Аныктык: Бир эле specти ар кандай AI (же ар кандай адамдар) окшош ишке ашырат.
Текшерилүүчүлүк: Код жазылгандан кийин дароо 90% тууралыгын автоматтык түрдө текшерүүгө болот.
Техникалык тейлөө жөндөмдүүлүгү: Алты айдан кийин кимдир бирөө specти карап, дизайндын баштапкы максатын түшүнө алат.
Байланыш чыгымдарынын аздыгы: Команда талкуусунда конкреттүү код саптары эмес, spec талкууланат.
Коопсуздук/сапат орнотулган: Коопсуздук талаптары (параметр суроолору сыяктуу) жана чек ара шарттары specте жазылат, AI аларды аткарууга милдеттүү.

V. Жакшы 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 |
| (мурда катталган email) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Функциялык эмес талаптар
- SQL параметрдик суроолорду колдонушу керек (инъекциядан коргоо)
- Журналга катталуу булагынын IPси жазылат, password жазылбайт
- Жооп убактысы 95% суроолор < 100ms (bcryptти эсептебегенде)

## Көз карандылыктар
- Python 3.10+, FastAPI, bcrypt, asyncpg

Жакшы Spec Coding = адамдын "дизайн чечимдерин" машинанын "тест учурлары + түр сигнатуралары + жүрүм-турум чектөөлөрү" катары жазуу, AI жөн гана ишке ашыруу менен толтуруу үчүн, ал эми адам сапатты жана багытты ар дайым көзөмөлдөйт.