Открыл PR от агента и не узнал свою задачу? Лишний код, не те решения, пропущенные обработки ошибок — и каждый раз заново все объяснять. Дело не в агенте, а в том, что ты не дал ему четкого контракта. Показываем, как это исправить раз и навсегда.
Spec-Driven Development: для чего AI-агенту нужна спецификация
Ты даешь агенту задачу «Добавь анализ YouTube видео». Агент пишет 800 строк кода. Ты открываешь PR и видишь: он добавил три библиотеки для парсинга субтитров, реализовал загрузку видео на диск (которую ты не просил), не обработал видео без субтитров.
Винить агента не за что — ты дал ему пять слов задачи, а остальное он добрал из обучающих данных. Когда ты пишешь «добавь анализ видео», агент сталкивается с десятком развилок: как получить субтитры, какую модель использовать, что делать, если субтитров нет. На все эти вопросы он отвечает сам, как умеет — иногда угадывает правильно, но чаще нет.
Чтобы агент не угадывал, ему нужно заранее ответить на все эти вопросы — до того, как он сядет за код. Для этого существует спецификация.
Что такое спецификация
Спецификация (спека) — это документ, где ты с агентом заранее договариваешься, что должно получиться на выходе, чтобы не выяснять это постфактум по PR на 800 строк. Это контракт между тобой и агентом: что делаем, чего не делаем, как реагируем на ошибки, какие инструменты используем.
Что такое Spec-Driven Development
Spec-Driven Development (SDD) — методология разработки, где спецификация выступает источником истины для агента: не идея в голове разработчика, а зафиксированный документ, на который можно сослаться и который не меняется на лету.
Что фиксирует спецификация
Спецификация отвечает на вопрос «ЧТО делает проект?», чего не делает, как реагирует на граничные случаи, и какие технические решения уже приняты (модель, библиотека, сервис). Она не отвечает на вопрос, как именно эти решения реализовать в коде: какой будет внутренняя структура функций, алгоритм парсинга, имена переменных.
Дальше весь разбор строится на одном примере: сервисе анализа субтитров YouTube-видео.
Какие контракты описывают в спецификации
Что на входе, что на выходе: Например POST /api/videos/analyze возвращает {analysis: {...}}, формат запроса, формат ответа, коды ошибок. В реализацию (какие технологии и как вызываются внутри кода) спека не лезет.
Что такое инварианты в спецификации
Инварианты — правила без исключений: «Максимальная длина видео — 60 минут», «Субтитры кешируются на 7 дней», «Анализ только через Claude Opus». Когда через месяц агент решит, что было бы неплохо проанализировать двухчасовые видео, именно инвариант не даст ему сделать это.
Какие граничные случаи нужно описывать
Что происходит, когда что-то идет не так: видео без субтитров, упавший сервис субтитров, удаленное видео. Идеальный сценарий агенты пишут отлично, а вот про обработку ошибок забывают, если не напомнить явно.
Зачем нужны архитектурные правила в спецификации
Кто с кем общается. «Фронтенд не вызывает YouTube API напрямую, только через /api/videos/*». «Для субтитров используем только UltraData API, не youtube-transcript-api». Без этого агент выберет первую знакомую библиотеку из обучающих данных.
Что писать в разделе «Вне scope»
Какие фичи не реализуем. Без этого раздела агент будет ползти по scope: «раз уж мы тут, давайте еще и анализ комментариев». Явно перечисли, что НЕ делаем в этой итерации.
Как писать критерии приемки для AI-агента
Критерии приемки должны быть такими, чтобы агент мог сам их проверить, не спрашивая тебя.
Плохой критерий: «ошибки обрабатываются корректно». Хороший: «видео без субтитров возвращает 422 с error: no_subtitles». Если критерий нельзя проверить командой или кликом — он еще не готов.
Когда нужен Spec-Driven Development
Фича затрагивает больше одного компонента
Анализ видео: сервис субтитров, сервис анализа, API, UI, кеширование — пять компонентов, которым агент додумает поведение, если не написать явно.
Задача содержит бизнес-требования
Какая максимальная длина видео? Кешировать или нет? Что делать без субтитров? Всего этого агент не знает, значит ты должен ответить на вопросы до генерирования кода.
Ожидаемый diff больше 400 строк
При таком объеме ты перестаешь удерживать последствия в голове — твой агент тоже. Спецификация разбивает большую задачу на атомарные части.
Агент уже переделывал задачу дважды
Если агент уже дважды переделывал задачу, стоит остановиться и зафиксировать требования в спецификации.
Когда Spec-Driven Development не нужен
- Правка в одном файле, поведение очевидно
- Рефакторинг по шаблону
- Быстрый эксперимент
Как выглядит спецификация в Spec-Driven Development
На бумаге это выглядит логично, а на практике первые спеки обычно получаются либо слишком общими, либо слишком подробными: забыл прописать граничный случай — агент его не учтет, не назвал библиотеку явно — агент возьмет первую знакомую, а иногда спека незаметно разрастается до десяти страниц.
Сам такие огрехи замечаешь обычно постфактум, когда агент уже пошел не туда. Научиться распознавать их заранее получится, если помогает человек, который уже освоил этот навык: «Смотри, тут спеки написаны так, что устареют после первой итерации», «Здесь агент ушел не туда, потому что контекст неполный» — именно так и устроена обратная связь на курсе «Управляемая разработка с AI и Spec-Driven Development», где ты собираешь проект по неделям. К концу курса ты защищаешь проект и выходишь с рабочей системой.
Как работать с AI-агентом по методологии Spec-Driven Development
1. Как сгенерировать спецификацию
Промпт:
Агент сгенерирует первую версию. Дальше ты ее ревьюишь.
2. Как проверить спецификацию перед реализацией
[✓] Неоднозначности устранены?
[✓] Библиотеки явно названы?
[✓] Out of scope записан?
[✓] Каждый таск атомарный?
[✓] Есть способ проверить результат?
[✓] Граничные случаи покрыты?
3. Как протестировать спецификацию
Промпт:
Если что-то не так (библиотека не подходит, API не работает) → правь спеки, а не код.
4. Как давать задачи AI-агенту по спецификации
Не давай агенту всю спецификацию сразу. Работай по одной задаче.
Сессия 1:
Агент пишет код → ты ревьюишь → коммитишь.
Сессия 2:
Ты не застреваешь в одной длинной сессии и каждый коммит атомарный.
5. Как проверять код после каждой задачи
Промпт:
Агент сам протестирует свой код. Если что-то сломано — исправит до Task 2.
6. Как обновлять спецификацию в процессе разработки
Обнаружил проблему в процессе → останови работу, обнови спеки. Например, в процессе разработки выяснилось, что без ограничения числа попыток агент зависал в бесконечном retry при недоступности UltraData API. Обновляем спеки:
7. Как фиксировать технические решения
Зафиксируй выбранные библиотеки, сервисы и инструменты и то, что использовать нельзя. Это и есть та часть «ЧТО», которая казалась бы похожей на «КАК»: выбор технологии — это принятое решение, а не алгоритм. Агент не имеет права пересматривать его без обсуждения, но вправе сам решать, как именно внутри кода эту технологию использовать. «Используй UltraData API, не youtube-transcript-api» — из этой категории.
Антипаттерны Spec-Driven Development: какие ошибки делают при написании спецификаций
❌ Ошибка: нет конкретики в спецификации
Ты: «Добавь анализ видео»Агент угадывает: какой API? какую модель? что делать без субтитров?Результат: 800 строк, половина не то.
Правильно: пиши спеки с явными решениями.
❌ Ошибка: спецификация на 10 страниц
Ты описываешь, как реализовать. Агент теряется в деталях.
Правильно: спеки отвечают на «ЧТО» и фиксируют принятые решения, но не диктуют, как писать сам код.
❌ Ошибка: все задачи за раз
Агент пытается сделать все сразу → 800 строк → ревью невозможно.
Правильно: разбей на 3-5 атомарных задач.
❌ Ошибка: спецификация без верификации
Агент говорит «готово», ты запускаешь → не работает.
Правильно: каждая задача содержит конкретные команды для проверки.
Как автоматизировать создание спецификаций
Промпт для генерации спецификации
Итого: зачем AI-агентам нужен Spec-Driven Development
Если коротко, спецификация — это просто способ договориться с агентом заранее, а не разгребать последствия в PR. На практике важнее всего четыре вещи:
- Писать спеку до того, как агент сядет за код
- Фиксировать требования, контракты и принятые технические решения, но не диктовать внутреннюю реализацию и структуру кода
- Двигаться маленькими задачами по одной за сессию
- Проверять каждую задачу, а не верить агенту на слово
Где еще пригодится спецификация
За пределами этой статьи остаются темы, которые тоже стоят отдельного разговора: как писать спеки для легаси-кода, для рефакторинга, который не должен ничего поломать вокруг, и для багфиксов, где сначала нужно воспроизвести проблему. Отдельно — чек-лист ревью AI-кода: какие типовые ошибки агенты допускают чаще всего и как их ловить автоматически. И тест-стратегия: как писать тесты до реализации, чтобы агент не написал код, который проходит только идеальный сценарий.
На курсе «Управляемая разработка с AI и Spec-Driven Development» каждой из этих тем отведена отдельная неделя — 8 в общей сложности. Ты ведешь свой проект и получаешь обратную связь от эксперта на воркшопах, а в конце остаешься с работающим кодом для портфолио и принципами SDD: шаблонами спецификаций, чек-листами ревью, тест-стратегиями.