AI серия интервю 16: Какво представлява доброто spec кодиране?

Едно добро Spec Coding (спецификационно кодиране) се състои в превръщането на „неясна идея“ в „точен, проверим и изпълним договор“. Не е просто документ, а изграждане на недвусмислен език за комуникация между човек и AI (или между хора). По-долу ще разгледаме четири измерения: структура на съдържанието, принципи на писане, процес на сътрудничество с AI и проверка на качеството.

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

Секция	Задължително съдържание	Пример
1. Цел и обхват	Едно изречение какво се прави, ясно какво не се прави	„Реализация на API за регистрация на потребител, без проверка на имейл“
2. Входно/изходен договор	Структура на данните, типове, задължителни/опционални полета, примерни стойности	`POST /register` заявка `{email: string, password: string}`, отговор `201` или `400` с код за грешка
3. Поведение и логика	Бизнес правила, гранични условия, преходи на състояния	„Дължина на паролата 8-20 знака, поне една цифра; ако имейлът вече съществува, върни `409`“
4. Обработка на грешки	Всички възможни изключения и съответни кодове/съобщения за грешка	„Неуспешна връзка с база данни → върни `503`, без да показваш стека“
5. Нефункционални изисквания	Производителност (време за отговор < 200 ms), сигурност (параметризирани заявки), логове, наблюдаемост	„Всички 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 може директно да генерира unit тестове по тях и след това да ги провери автоматично.

II. Основни принципи за писане на Spec (вариант на SMART)

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

III. Spec Coding процес при сътрудничество с AI

Човекът пише spec (в горепосочената структура, особено тестовите сценарии и подписите на функциите).
Подава spec-а на AI наведнъж (без диалогово добавяне на изисквания, за да се избегне замърсяване от контекста).
AI генерира код + unit тестове (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 |
| (вече съществуващ имейл) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Нефункционални изисквания
- SQL трябва да използва параметризирани заявки (защита от инжекции)
- Логовете записват IP адреса на източника на регистрация, не записват парола
- 95% от заявките с време за отговор < 100 ms (без bcrypt)

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

Доброто Spec Coding = превръщане на „дизайнерските решения“ на човека в „тестови сценарии + типови подписи + поведенчески ограничения“ за машината, като AI отговаря само за попълването на реализацията, а човекът винаги контролира качеството и посоката.