Когда использовать
Перед тем как поручить агенту-кодеру (Claude Code, Cursor, Spec Kit, Kiro) собрать фичу или сервис. Главный провал «vibe coding» — расплывчатый запрос «сделай логин», по которому модель додумывает поведение и уезжает от замысла. Spec-driven лечит это: сначала спека, потом код. Роль ИИ — системный аналитик, который пишет спеку, а не код. Результат: документ, по которому агент собирает то, что задумано, и который остаётся источником правды при изменениях.
Промт (бери и вставляй)
Ты — системный аналитик. Не пиши код. Составь ИСПОЛНЯЕМУЮ СПЕКУ для ИИ-агента-кодера —
единый источник правды, по которому он сгенерирует реализацию.
ФИЧА/СЕРВИС: «<ВСТАВЬ, что нужно сделать>»
КОНТЕКСТ: <стек/окружение, если есть; иначе предложи и зафиксируй [допущение]>
Спека по разделам:
1. Цель и не-цели: что система делает и чего НЕ делает (границы), одним списком.
2. Требования в формате EARS: «КОГДА <событие>, система ДОЛЖНА <реакция>» / «ЕСЛИ <условие>, ТО …» —
нумеруй, каждое проверяемо и однозначно.
3. Контракты: входы/выходы, формы данных (поля и типы), API/сигнатуры, коды ошибок.
4. Краевые случаи и обработка ошибок: пустые/некорректные данные, гонки, лимиты, оффлайн.
5. Критерии приёмки: чек-лист «готово, если …», по которому КОД можно проверить (в идеале — будущие тесты).
6. Открытые вопросы: что нужно решить до кода; по каждому дай рекомендуемый дефолт.
Пиши так, чтобы по спеке два разных разработчика собрали одно и то же. Никаких «и т.п.» — конкретика.
Где данных нет — прими разумное допущение, пометь [допущение], не выдумывай факты молча.
Приём: spec-driven development — практика, оформившаяся в 2025 как ответ на «дрейф намерения» у ИИ-агентов: исполняемая спека становится источником правды, код из неё выводится. Формулировки требований по EARS убирают двусмысленность.
Пример заполнения
Фича: «магический вход по ссылке на email (passwordless), без пароля». Контекст: TS / Node / PostgreSQL.
Ожидаемый ответ ИИ: не-цели («не делаем OAuth, не делаем 2FA в v1»); требования EARS («КОГДА пользователь ввёл email, система ДОЛЖНА отправить одноразовую ссылку со сроком 15 мин»; «ЕСЛИ ссылка просрочена, ТО система ДОЛЖНА показать ошибку и предложить выслать новую»); контракт POST /auth/magic-link {email} → коды 200/400/429; краевые — повторные запросы (rate-limit), несуществующий email (не палить, что его нет); критерии приёмки чек-листом. По этой спеке агент-кодер уже не «додумывает» срок жизни ссылки или поведение при повторе.
Вариации
- Spec Kit / Kiro стиль. Попроси разбить на три файла:
requirements.md(EARS) →design.md→tasks.md(атомарные задачи) — под инструменты, которые этого ждут. - Поверх легаси. «Учитывай существующий модуль
: что переиспользуем, что не ломаем» — добавляет раздел совместимости. - Спека как тесты. «Из критериев приёмки сгенерируй список тест-кейсов (вход → ожидание)» — мост к TDD.
Про-советы
- Спека стоит живой: меняется требование — правьте спеку и регенерируйте код, а не патчите код напрямую. Иначе код и намерение снова разъезжаются.
- Требуйте EARS-формулировки: «система должна реагировать на <событие>» проверяемо, «удобный быстрый логин» — нет.
- Раздел «не-цели» экономит больше всего: именно туда уходит половина лишней работы агента, если границы не заданы.