Почему ваши AI-ассистенты творят чушь

Давайте признаемся себе: мы относимся к AI-ассистентам как к продвинутым Siri. Спрашиваем что-то в чате, получаем ответ, двигаемся дальше. Всё отлично работает, пока речь идёт о генерации идей или объяснении концепций.

Но потом мы просим этого же бота переписать функцию авторизации в рабочем проекте. И через час получаем код, который решает какую-то свою задачу, ломает соседние модули и проходит все тесты, потому что тесты мы тоже не обновили.

Знакомо? Это не баг в AI. Это наш подход к работе с ними.

Почему чатовый режим больше не работает

Раньше AI-ассистенты были отвечальными машинами. Поговорил — получил информацию — закрыл сессию. При таком сценарии небрежность в формулировках — это просто неудобство.

Теперь те же инструменты умеют редактировать файлы, запускать команды в терминале, создавать ветки. Они стали участниками разработки. А мы всё ещё общаемся с ними как с собеседниками в чате.

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

Решение не в более длинных инструкциях. Решение в смене формата коммуникации.

От промптов к спецификациям

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

Спецификация — это бриф для исполнителя. Это документ, который остаётся рядом с кодом на протяжении всей работы. Он говорит не «попробуй сделать X», а «вот проблема, вот что должно измениться, вот как мы поймём, что всё получилось».

Разница принципиальная:

• Промпт исчезает, когда сессия заканчивается
• Спецификация едет вместе с PR и становится частью истории проекта
• Промпт можете понять только автор
• Спецификацию могут проверить ревьюеры и мейнтейнеры через год

Когда ассистент работает с кодом, ему нужен не собеседник. Ему нужен чёткий бриф.

Из чего состоит толковая спецификация

Не нужно писать диссертацию. Достаточно пяти блоков:

Контекст. Зачем мы это делаем? Какая проблема пользователя или технический долг стоит за задачей? Что в архитектуре должен учитывать ассистент?

Что должно измениться. Конкретное описание поведения. Не «улучшить поиск», а «пользователь должен находить товары по частичному совпадению названия с учётом опечаток».

Что должно остаться прежним. Какие контракты, API, тайминги нельзя трогать? Это страховка от неожиданных последствий.

Примеры ожидаемого поведения. Конкретные сценарии: «Если пользователь вводит "iphon", система предлагает "iPhone 15 Pro"». Формат Given/When/Then или просто набор тест-кейсов.

Критерии приёмки. Что должен проверить ревьюер? На какие вопросы должен найти ответы? Как понять, что работа завершена?

Выглядит знакомо? Это потому что это тот же BDD-подход, те же acceptance criteria в issue-трекерах, просто адаптированные для AI-ассистента.

Где хранить спецификации

Главное — спецификация должна быть доступна не только вам. Она должна жить там, где живёт код:

• GitHub issue с чёткими критериями приёмки
• Описание PR, где расписано ожидаемое поведение
• BDD-сценарии в feature-файлах
• Design doc перед стартом реализации
• Специализированные инструменты вроде OpenSpec

Неважно, где именно. Важно, чтобы спецификация пережила вашу текущую сессию и стала частью того, что видит команда.

Три вопроса вместо одного

Хорошая спецификация отвечает на три разных вопроса:

1. Что должно измениться? — суть задачи
2. Как мы поймём, что получилось? — критерии успеха
3. Как сейчас видится решение? — технический подход

Эти вопросы связаны, но не идентичны. Смешивая их в одну кучу инструкций, вы рискуете. Ассистент может залипнуть на предложенном вами способе реализации и пропустить суть. Или написать элегантный код, который решает не ту проблему.

Разделение помогает. Требование остаётся стабильным, а реализация может эволюционировать. Ассистент изучает кодовую базу, находит нюансы, а спецификация говорит ему: «Стоп. Ты всё ещё решаешь изначальную задачу?»

Это особенно важно для работы с существующим кодом. Большинство задач — это не создание с нуля, а модификация того, что уже работает. Спецификация говорит: «было так, стало эдак». Ревьюеру не нужно догадываться, что вы имели в виду.

Начните с пяти минут

Если вы привыкли писать «сделай фичу X» и отправлять в репозиторий, это покажется избыточным. Но подумайте о альтернативе: PR, который непонятно как проверять; код, который решает свою задачу; время на разборки и переделки.

Переход на спецификации — это не бюрократия. Это инвестиция в понятность.

Не обязательно сразу перестраивать процессы. Просто в следующий раз, перед тем как отправить ассистента в репозиторий, потратьте пять минут на запись:

• Какой проблемы это решение
• Что конкретно должно измениться
• Как вы поймёте, что всё работает

Запишите это в описании PR или в комментарии к issue. Пусть это будет видно.

Ваш следующий ревьюер (а им может быть вы через месяц) скажет спасибо.

Коротко: AI-ассистенты стали мощными участниками разработки. Обращайтесь с ними соответственно. Дайте им чёткий бриф — и получите работу, которую не стыдно показать команде.