Интервју од AI серија 16: Како треба да изгледа доброто spec coding?

Доброто Spec Coding (спецификациско кодирање) суштински го претвора „нејасната идеја“ во „точен, проверлив и извршен договор“. Тоа не е само пишување документ, туку воспоставување јазик за комуникација без двосмисленост помеѓу човек и AI (или помеѓу луѓе). Подолу ќе го опишам изгледот на добра spec од четири димензии: структура на содржината, принципи на пишување, процес на соработка со AI и проверка на квалитет.

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

Поглавје	Задолжителна содржина	Пример
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 може директно да генерира единични тестови врз основа на нив, а потоа автоматски да верификува.

2. Клучни принципи за пишување Spec (варијанта SMART)

Принцип	Објаснување	Контрапример
Прецизно (Precise)	Користи конкретни броеви, типови, булови услови; избегнувај „што е можно“, „обично“	❌ „Лозинката да биде доволно безбедна“ → ✅ „Лозинката најмалку 8 знаци, содржи голема буква, мала буква, цифра“
Проверливо (Verifiable)	Секое барање да може да се провери со автоматски тест или рачна проверка	❌ „Кодот да биде елегантен“ → ✅ „Цикломатска сложеност ≤ 10, без повторувачки блокови“
Без двосмисленост (Unambiguous)	Истиот термин да има иста значење низ целиот текст; по потреба даде речник	❌ „Ако корисникот не постои, врати грешка“ → ✅ „Корисникот не постои → врати `404` со `{code: 'USER_NOT_FOUND'}`“
Целосно (Complete)	Покриј го среќниот пат, сите исклучоци, нефункционални барања	❌ Само успешни сценарија → ✅ Вклучи timeout на база, немање дозвола итн.
Атомарно (Atomic)	Една spec опишува само една независно испорачлива функција (за AI да заврши во еден потег)	❌ Една spec за „целиот систем за плаќање“ → ✅ Подели на „генерирај налог за плаќање“, „потврди потпис“, „врати средства“

3. Процес на Spec Coding при соработка со AI

Човек пишува 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
- Не испраќа потврдна е-пошта, не проверува автентичност на е-пошта

## Договор
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 извор на регистрација, не се логира лозинка
- Време на одговор 95% од барањата < 100ms (без bcrypt)

## Зависности
- Python 3.10+, FastAPI, bcrypt, asyncpg

Доброто Spec Coding = претворање на „дизајнерските одлуки на човекот“ во „тест случаи + типски потписи + ограничувања на однесување“ за машината, оставајќи AI само да ја пополнува имплементацијата, додека човекот секогаш го контролира квалитетот и насоката.