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

Чек спеки перед кодом и итерации с агентом

Спека написана — но это ещё не значит, что она готова. У вас первый черновик. Пробелы и неоднозначности в нём почти всегда есть, и сейчас — пока ни строки кода не написано — их исправить дешевле всего. Правка требования в Markdown занимает минуту. Правка готового модуля, который агент реализовал на основе неверной интерпретации, может занять час.

Clarify-промпт: отдаём спеку агенту на разбор

Самый прямой способ найти дыры — попросить агента сыграть роль въедливого инженера, который читает спеку с единственной целью: задать вопросы, без которых реализация будет неоднозначной.

В Claude Code откройте новую сессию, добавьте CLAUDE.md и нужную спеку в контекст, затем отправьте:

Прочитай specs/[feature].md. Не пиши код и не предлагай реализацию.
Задай мне все вопросы, которые делают реализацию неоднозначной или неполной.
Сгруппируй по разделам: Требования, Граничные случаи, Критерии готовности.
Начни с самых критичных.

В Cursor — то же самое, но в режиме чата (Chat), а не Agent/Composer: так агент не начнёт редактировать файлы самостоятельно.

Пример того, что агент может вернуть на спеку авторизации из прошлого подмодуля:

> Требования:

> — Неясно, чувствителен ли email к регистру. User@example.com и user@example.com — один пользователь или разные?

> — Что происходит, если верный пароль вводится во время периода блокировки?

>

> Критерии готовности:

> — «Блокировка после 5 ошибок» — подряд или суммарно за сессию?

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

Важный нюанс: первый раунд редко вытаскивает всё. После того как вы ответили и обновили спеку — запустите промпт снова. Второй раунд часто открывает новые вопросы, которые стали видны только после ответов на первые. Два раунда — норма, три — бывает.

Три типа проблем, которые агент находит

Вопросы агента почти всегда попадают в одну из трёх категорий.

Размытые требования — формулировки, допускающие несколько интерпретаций. «Система должна быть быстрой» — не требование. «P95 ответа < 300 мс при нагрузке 100 RPS» — требование. Агент спросит: «Что значит быстрой?» Это хороший знак.

Непокрытые граничные случаи — ситуации, которые вы не предусмотрели. Спека описывает счастливый путь, но молчит о таймауте, пустом вводе или невалидных данных. Агент либо спросит — либо, что хуже, придумает что-то сам и не скажет.

Конфликты между требованиями — редкость в небольших спеках, но встречается: «все запросы требуют авторизации» плюс «API-документация доступна без токена» — противоречие. Агент его заметит, если вы попросите.

Как работать с ответами агента

Не каждый вопрос требует нового пункта в спеке. Разбирайте по схеме:

• Вопрос про поведение фичи → дополнить «Требования» или «Граничные случаи»
• Вопрос про технический выбор → дополнить «Дизайн» или CLAUDE.md
• Вопрос про что-то вне скоупа → добавить явно в «Не-цели»
• Вопрос, на который агент сам может принять разумное решение → написать «Оставляю на усмотрение агента, предпочтительно X»

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

Чек-лист готовности: потренируйте инстинкт

Прежде чем двигаться к декомпозиции, пройдите по пяти критериям.

Однозначность. Каждое требование допускает ровно одну интерпретацию. Если два разработчика прочитают одно требование и придут к разным выводам — его нужно переписать.

Покрытие edge-кейсов. Для каждого основного сценария описан хотя бы один сценарий ошибки или граничный случай.

Измеримые критерии приёмки. Каждый пункт в «Критериях готовности» можно проверить — тестом, запросом к API, вручную. «Работает корректно» — не критерий. «Возвращает 401 при неверном пароле» — критерий.

Отсутствие конфликтов. Требования не противоречат друг другу и не противоречат CLAUDE.md.

Явные не-цели. Всё, что могло войти в эту фичу, но не войдёт — написано явно. Это защищает от разрастания скоупа прямо во время реализации.

Когда останавливаться

Спека готова, когда агент перестаёт задавать вопросы по существу. Если после второго раунда остались только технические вопросы — «какой HTTP-клиент использовать?», «как назвать файл?» — продуктовая часть закрыта. Технические детали уходят в «Дизайн» или решаются по умолчанию.

Если после третьего раунда вопросы не кончаются — скорее всего, фича слишком большая или смешивает несколько независимых сценариев. Стоит разбить спеку на две.

Задание

Возьмите спеку из прошлого подмодуля. Загрузите CLAUDE.md и спеку в контекст Cursor или Claude Code, запустите clarify-промпт. Обновите спеку по ответам — и запустите снова. Когда вопросов не останется или останутся только технические детали — спека готова. В следующем подмодуле она пойдёт в декомпозицию на задачи.