Только 33% разработчиков доверяют ответам ИИ: как научить агента работать по спецификации

«Внедрим ИИ, и через полгода половина команды не понадобится» — такую установку автор разбора на Habr слышит от руководителей слишком часто. Они представляют, что агент получает задачу одним промптом, пишет код, сам тестирует и выкатывает, а людям остаётся нажать Merge. Реальность другая.

Допустим, вы просите агента ускорить обработку возвратов в магазине. Он убирает «лишнее» повторное чтение из базы, тесты зелёные, но при параллельных запросах клиент получает денег больше, чем заплатил: это чтение защищало бизнес-правило, а агенту о нём никто не сказал. Поэтому в опросе Stack Overflow 2025 ответам ИИ доверяют только 33% разработчиков.

Автор предлагает решение — работать по спецификациям (SDD, spec-driven development): сначала описывается, что должен делать код, а затем код пишется и проверяется против этого описания. Для этого он использует фреймворк OpenSpec.

Почему демо врёт

На демо агент за пять минут собирает CRUD или ускоряет SQL-запрос. У такой задачи нет истории, и понятно, как выглядит правильный результат. В живой системе есть интеграции и правила, которые нигде не записаны: агент не знает, какой клиент читает это поле. Недостающее он достраивает сам, и код получается правдоподобным, но не обязательно верным.

Цифры Stack Overflow 2025 это подтверждают. ИИ используют или собираются использовать 84% разработчиков, но точности ответов доверяют 33%, а не доверяют 46%. Чаще всего, в 66% случаев, жалуются на решения, которые почти правильные, но не совсем, а 45% говорят, что отлаживать сгенерированный код дольше. Авторы отчёта DORA 2025 называют ИИ усилителем: у сильных команд он усиливает сильные стороны, у слабых — проблемы.

Простой тест для руководителя: прежде чем планировать сокращения, провести с ИИ одну свою реальную задачу целиком — спроектировать фичу, описать требования, получить код, проверить и довести до прода. Через пару дней станет видно, что ИИ ускоряет работу, но решать, правильно ли сделано, всё равно приходится человеку.

Спецификации вместо однострочных тикетов

Однострочный тикет агент додумает сам, а по полной спецификации с ограничениями и краевыми случаями он работает в заданных рамках. Похожий подход у GitHub Spec Kit, который вышел в открытый доступ в сентябре 2025 года. Его ведущий мейнтейнер Манфред Рим сравнил агента с очень способным и быстрым стажёром, которому нужны чёткое ТЗ и наставник.

OpenSpec — лёгкий фреймворк: спецификации лежат в репозитории рядом с кодом в обычном Markdown. Он поддерживает более 30 инструментов, включая Claude Code, Cursor и GitHub Copilot. В папке openspec/ три части: specs/ описывает, как система работает сейчас, changes/ хранит предлагаемые изменения (proposal, design, tasks и дельты требований), а config.yaml несёт контекст проекта, который подставляется агенту при создании артефактов.

Требования пишутся с ключевыми словами SHALL/MUST и сценариями GIVEN/WHEN/THEN. Например, для частичного возврата: сумма всех возвратов по заказу MUST NOT превышать оплаченную, а повторный запрос с тем же ключом идемпотентности не создаёт второй возврат. Цикл состоит из трёх команд: /opsx:propose создаёт план, и его ревьюят до написания кода; /opsx:apply реализует задачи; /opsx:archive вливает дельты в основные спецификации. Следующая задача стартует уже с актуальной картиной системы.

Контекст, инварианты и скиллы

Агент каждый раз приходит в проект как новичок в первый день, поэтому рядом с кодом стоит держать описание системы: границы продукта, бизнес-процессы, пайплайны CI/CD, глоссарий и инварианты, то есть правила, которые нельзя нарушать ни при каком рефакторинге. Последние недооценивают чаще всего — отсюда и история с возвратами. Глоссарий решает похожую проблему: аналитик пишет «отмена», а в коде есть Refund, Reversal и Cancellation, и без словаря агент выберет наугад. Обновление контекста автор предлагает включить в Definition of Done наравне с тестами.

Скиллы — переиспользуемые инструкции вроде «как у нас пишется миграция» или «как ревьюится PR». Скилл review-against-spec сверяет каждый сценарий из дельты с кодом и тестами, проверяет, что инварианты не ослаблены, и выдаёт список расхождений без самостоятельных правок. На просьбу «посмотри, всё ли нормально» агент обычно отвечает, что всё нормально, а чек-лист заставляет его искать. Последнее слово на ревью остаётся за человеком.

Люди и петля багов

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

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

Без процесса команда с каждым багом на проде переписывает куски системы и плодит новые баги. Выход — после каждой ошибки выяснять, чего не хватило агенту: контекста, правила или проверки в скилле. Недостающее дописывают и пропускают через ревью, как обычный PR. Если поправить только код, агент повторит ту же ошибку в следующей фиче.