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

Жақсы Spec Coding (спецификацияға негізделген бағдарламалау) — бұл «түсініксіз идеяны» «нақты, тексерілетін, орындалатын келісімшартқа» айналдыру. Бұл тек құжат жазу емес, адам мен AI (немесе адам мен адам) арасында екіұштылықсыз байланыс тілін құру. Төменде мен мазмұн құрылымы, жазу принциптері, AI-мен ынтымақтастық процесі, сапаны тексеру төрт өлшемі бойынша жақсы spec үлгісін беремін.

1. Спецификация құжатының стандартты құрылымы (функционалдық модуль мысалында)

Бөлім	Міндетті мазмұн	Мысал
1. Мақсат пен ауқым	Бір сөйлеммен не істелетінін, не істелмейтінін анықтау	«Пайдаланушыны тіркеу API іске асыру, email тексерусіз»
2. Кіріс/шығыс келісімшарты	Деректер құрылымы, түрі, міндетті/міндетті емес өрістер, мысал мәндер	`POST /register` сұрау денесі `{email: string, password: string}`, жауап `201` немесе `400` қате кодымен
3. Мінез-құлық пен логика	Бизнес ережелері, шекаралық шарттар, күй ауысулары	«Құпиясөз ұзындығы 8-20 символ, кемінде бір сан болуы керек; email бұрыннан бар болса `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 бұрыннан бар	жоғарыдағыдай email	`409`, `EMAIL_EXISTS` қате коды

Жақсы Spec алдымен тест жағдайларын жазуы керек, өйткені AI олар бойынша бірлік тесттерін тікелей жасап, аяқталғаннан кейін автоматты түрде тексере алады.

2. Spec жазуының негізгі принциптері (SMART нұсқасы)

Принцип	Түсіндірме	Қарсы мысал
Нақты (Precise)	Нақты сандар, типтер, буль шарттар қолдану, «мүмкіндігінше», «әдетте» сияқты сөздерден аулақ болу	❌ «Құпиясөз жеткілікті қауіпсіз болуы керек» → ✅ «Құпиясөз кемінде 8 символ, кемінде бір бас әріп, бір кіші әріп, бір сан болуы керек»
Тексерілетін (Verifiable)	Әрбір талап автоматты тест немесе қолмен тексеру арқылы өту/өтпеу ретінде анықталуы мүмкін	❌ «Код әдемі болуы керек» → ✅ «Функция цикломатикалық күрделілігі ≤ 10, қайталанатын код блоктары жоқ»
Екіұштылықсыз (Unambiguous)	Бір термин бүкіл мәтінде бір мағынада қолданылуы керек, қажет болса glossary беру	❌ «Пайдаланушы жоқ болса, қате қайтару» → ✅ «Пайдаланушы жоқ → `404` және `{code: 'USER_NOT_FOUND'}` қайтару»
Толық (Complete)	Бақытты жолды, барлық ерекше жолдарды, функционалдық емес талаптарды қамту	❌ Тек сәтті сценарий жазылған → ✅ Дерекқордың кідірісі, рұқсаттың жеткіліксіздігі т.б.
Атомдық (Atomic)	Бір spec тек бір тәуелсіз жеткізілетін функцияны сипаттайды (AI бір ретте орындауы үшін)	❌ Бір spec «төлем жүйесін» жазу → ✅ «Төлем тапсырысын жасау», «Шақыруды тексеру», «Қайтару» болып бөлінген

3. AI-мен бірлесіп жұмыс істеу кезіндегі Spec Coding процесі

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

Маңызды тәжірибе: Spec-ті кодтандыру — spec.md + test_spec.py пайдалану, мұндағы тест файлы spec-тегі мысалдардан тікелей алынады, кейінірек кодты өзгерту кезінде тесттерді орындау арқылы spec-тің бұзылмағанын тексеруге болады.

4. Жақсы Spec-тің әсері (қабылдау критерийлері ретінде)

Анықтық: Бір spec-ті әртүрлі AI (немесе әртүрлі адамдар) ұқсас етіп іске асырады.
Тестілеу мүмкіндігі: Код жазылғаннан кейін бірден 90% дұрыстығын автоматты түрде тексере аласыз.
Қызмет көрсету мүмкіндігі: Жарты жылдан кейін кез келген адам spec-ті қарап, бастапқы дизайн мақсатын түсіне алады.
Төмен байланыс шығындары: Команда талқылау кезінде тек spec-ті талқылайды, нақты код жолдарын талқыламайды.
Қауіпсіздік/сапаның кіріктірілуі: Қауіпсіздік талаптары (мысалы, параметрлендірілген сұраулар) және шекаралық шарттар spec-те жазылған, AI оны орындауы керек.

5. Жақсы Spec мысалы (өте қысқа нұсқа)

# Spec: Пайдаланушыны тіркеу API

## Ауқым
- email, password қабылдау
- Растау хатын жібермеу, email шынайылығын тексермеу

## Келісімшарт
POST /register
Content-Type: application/json
Request: { "email": string, "password": string }
Response 201: { "user_id": string }
Response 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Response 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 тек орындауды толтырады, ал адам әрқашан сапа мен бағытты бақылайды.