AI серия интервью 16: Каким должно быть хорошее Spec Coding?

Хорошее Spec Coding (спецификация-ориентированное программирование) заключается в превращении "туманных идей" в "точные, проверяемые, исполнимые контракты". Это не просто документ, а создание однозначного языка общения между человеком и AI (или между людьми). Ниже я рассмотрю четыре аспекта: структура содержания спецификации, принципы написания, процесс совместной работы с AI, проверка качества, чтобы показать, как выглядит хорошая спецификация.

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`

В хорошей спецификации сначала пишутся тестовые случаи, потому что AI может сгенерировать по ним модульные тесты, а после выполнения — автоматически проверить.

2. Основные принципы написания спецификации (вариант SMART)

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

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

Человек пишет спецификацию (указанная структура, особенно тестовые случаи и сигнатуры функций).
Спецификация передается AI единым блоком (не добавлять требования в диалоговом режиме, чтобы избежать расплывчатости).
AI выдает код + модульные тесты (AI должен генерировать исполняемые тесты на основе тестовых случаев из спецификации).
Запуск тестов: если все проходят, переходим к следующему шагу; если нет, изменить спецификацию или напрямую исправить код (допускается малый цикл, но изменения фиксируются).
Ручная проверка: проверка на наличие функциональности вне спецификации (scope creep), контроль безопасности/производительности.
Фиксация: спецификация и итоговый код вместе сохраняются в репозитории как постоянная документация.

Ключевая практика: Кодификация спецификации — использование spec.md + test_spec.py, где тестовый файл напрямую основан на примерах из спецификации, так что при последующем изменении кода достаточно запустить тесты, чтобы проверить, не нарушена ли спецификация.

4. Результаты хорошей спецификации (могут служить критериями приемки)

Определенность: Одна и та же спецификация, переданная разным AI (или разным людям), даёт близкую реализацию.
Тестируемость: После написания кода можно сразу автоматически проверить 90% правильности.
Поддерживаемость: Через полгода любой, кто посмотрит спецификацию, поймет первоначальные проектные намерения.
Низкие затраты на общение: Команда обсуждает только спецификацию, а не конкретные строки кода.
Встроенная безопасность/качество: Требования безопасности (например, параметризованные запросы) и граничные условия прописаны в спецификации, AI обязан их соблюдать.

5. Пример хорошей спецификации (минимальная версия)

# 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 источника регистрации, не логировать пароль
- Время ответа 95% запросов < 100ms (без учёта bcrypt)

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

Хорошее Spec Coding = превратить "проектные решения" человека в "тестовые случаи + сигнатуры типов + ограничения поведения" для машины, позволяя AI только заполнять реализацию, а человеку всегда контролировать качество и направление.