От промптов к спекам с AI-агентами

Приёмка результата против спеки

В четвёртом подмодуле мы ввели правило: после каждой задачи — две минуты на сверку с «Критериями готовности». Этот подмодуль разворачивает эти две минуты в полноценный процесс — как именно убедиться, что агент сделал то, что в спеке, а не «что-то похожее».

Ловушка «примерно работает»

Агент сообщает «готово» — и код действительно что-то делает. Логин проходит, токен возвращается, тесты зелёные. Но «работает» и «соответствует спеке» — разные утверждения.

Типичный пример: спека говорила «блокировка после 5 ошибок *подряд*». Агент реализовал блокировку после 5 ошибок суммарно за всё время аккаунта. Технически — «что-то похожее». На практике — другое поведение. Если не проверять явно, такой дрейф живёт в продакшене до первого инцидента.

Три шага приёмочного чека

Шаг 1. Пройдите по «Критериям готовности» буквально. Возьмите спеку, откройте раздел «Критерии готовности» — тот, который заполняли в подмодуле 2. Каждый пункт — это утверждение. Проверьте его явно: запросом к API, тестом, ручным прогоном.

# Каждый критерий — конкретная проверка, не «по ощущениям»
POST /auth/login {"email":"test@example.com","password":"wrong"} → ожидаем 401
POST /auth/login {"email":"test@example.com","password":"correct"} → ожидаем 200 + token

Шаг 2. Прогоните граничные случаи. Раздел «Граничные случаи» в спеке был написан именно для этого момента. Каждый пункт — отдельная проверка. Именно их агент чаще всего реализует «с точностью до своей интерпретации».

Шаг 3. Посмотрите, что агент добавил помимо задачи. Иногда агент «помогает» — добавляет что-то, чего в задаче не было. Это не всегда плохо, но нужно знать, что именно лежит в коде.

Хороший способ ускорить все три шага — попросить агента сверить результат самостоятельно:

Прочитай specs/auth-login.md, разделы «Требования» и «Критерии готовности».
Сверь с тем, что реализовано в auth.controller.ts.
Перечисли расхождения: где код отличается от спеки или делает что-то, чего в спеке нет.
Не предлагай правок — только список расхождений.

Агент нередко замечает то, что вы пропустили при ручной проверке.

Три исхода: принять, доработать, обновить спеку

После проверки у вас три варианта — не «принять или нет».

Принять. Все критерии выполнены, граничные случаи покрыты, агент не добавил ничего неожиданного. Ставите чекбокс в tasks.md и двигаетесь дальше.

Доработать — вернуть агенту. Критерий не выполнен, при этом спека была однозначной. Значит, агент ошибся в реализации. Возвращаете задачу с конкретным указанием на расхождение:

В specs/auth-login.md критерий: «Блокировка после 5 ошибок подряд».
Сейчас счётчик считает суммарно, а не подряд.
Исправь: счётчик сбрасывается после каждого успешного логина.

Обновить спеку → новая задача. Проверка выявила что-то, чего в спеке не было. Агент сделал разумный выбор, но этот выбор нужно зафиксировать явно — или пересмотреть. В любом случае: сначала обновляете спеку, потом принимаете или ставите новую задачу в tasks.md.

Дрейф спека–код: три сигнала

Молчаливые допущения — агент сделал выбор, которого в спеке не было. Например, нормализовал email (trim + lowercase) молча, хотя в «Требованиях» это не прописано. Выглядит правильно, но теперь есть поведение без документации.

Расширение скоупа — агент реализовал что-то из «Не-целей». Добавил refresh-токен «потому что так обычно делают». Соблазнительно оставить — не делайте этого без обновления спеки: такой код становится «тёмным» поведением, про которое никто не знает.

Смещение семантики — требование выполнено формально, но не по смыслу. «Возвращать сообщение об ошибке» — агент вернул {error: true}, а не {error: "Invalid credentials"}.

Когда обновлять спеку, а когда — код

Правило простое: если агент сделал что-то разумное, чего нет в спеке — спека неполная. Если агент нарушил то, что в спеке написано — код неправильный.

Агент нормализовал email, спека молчала об этом → добавьте в «Требования»: «Email при сохранении приводится к lowercase и trim».

Спека говорила «блокировка на 15 минут», агент сделал на 30 → ошибка реализации, исправляйте код, не спеку.

Обновлённая спека — не признак плохого планирования. Требования уточняются в ходе работы, это нормально. Главное — фиксировать изменения в тексте, а не только в голове.

Упражнение

Возьмите задачу, которую реализовали в прошлом подмодуле. Запустите три шага:

1. Откройте спеку, раздел «Критерии готовности» — проверьте каждый пункт явно.

2. Прогоните каждый граничный случай из раздела «Граничные случаи».

3. Запустите авто-аудит: попросите агента сверить код со спекой, только расхождения.

Примите одно из трёх решений и запишите его в tasks.md рядом с задачей — одной строкой: «Принято», «Возвращено: [причина]» или «Спека обновлена: [что добавлено]».

В следующем и последнем подмодуле разберём, как встроить весь цикл SDD в работу с продактом или аналитиком — чтобы спека стала общим артефактом команды, а не личным файлом разработчика.