Как поставить задачу ИИ-агенту в коде: спецификация вместо промпта

Почему «сделай форму регистрации» не работает

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

Есть и обратная сторона: агент склонен выполнять задачу буквально. Попросите «исправить падающий тест» — и он может исправить сам тест, а не ошибку в коде, которую тест поймал. Попросите «ускорить страницу» — и он может добавить кэш там, где данные должны быть всегда свежими. Чем яснее цель, тем меньше места для такого буквального, но бесполезного исполнения.

Поэтому полезно перестать думать о «промпте» как о волшебной фразе. Вы пишете техническое задание: его можно перечитать, отдать коллеге и по нему же потом проверить работу. Если задачу невозможно проверить по тексту, агент тоже не поймёт, когда остановиться.

Промпт и спецификация: в чём разница

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

Не каждая задача требует полной спецификации. Полезно соотносить объём описания с ценой ошибки и с тем, насколько задача однозначна.

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

Отдельно стоит сказать о задачах, где нужно продуктовое решение: какой текст показать пользователю, как поступить с неоднозначным случаем, что важнее при конфликте требований. Агент примет такое решение молча и правдоподобно. Если ответа на продуктовый вопрос нет в задаче, лучше попросить агента остановиться и задать вопрос, чем получить код с чужим решением внутри.

Анатомия хорошей задачи

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

• Цель. Одно-два предложения о том, какую проблему решаем и для кого. Без цели агент не может принять разумное решение в ситуации, которую вы не предусмотрели.
• Текущее и ожидаемое поведение. Для бага — шаги воспроизведения, что происходит и что должно происходить. Без этого агент чинит то, что сам считает ошибкой.
• Контекст в коде. Какие модули затронуты, где взять образец похожего решения. Без этого агент тратит время на поиск или изобретает своё.
• Границы. Что менять можно, а что нельзя. Без этого дифф расползается по проекту.
• Ограничения. Принятые библиотеки, соглашения, требования к производительности, совместимости, безопасности. Без этого агент берёт то, что популярно, а не то, что принято у вас.
• Критерии готовности. Проверяемые условия завершения. Без них агент останавливается, когда ему кажется, что хватит.
• Способ проверки. Какие команды запустить и что показать в отчёте. Без этого «готово» остаётся словом.

Контекст репозитория: дать нужное, а не всё

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

Что выносить в постоянные правила проекта

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

Версии и внешние API

Если задача касается внешнего API или библиотеки, которую агент может помнить в старой версии, укажите версию из файла зависимостей и приложите фрагмент актуальной документации. Это снимает целый класс ошибок, когда агент пишет вызовы, которых в вашей версии уже или ещё нет.

Неписаные правила

Соглашения, которые не записаны в коде, агенту неизвестны. Если в команде есть устное правило — например, «даты всегда храним в UTC» или «в этом модуле не используем исключения для управления потоком», — его нужно произнести в задаче, а лучше записать в правила проекта.

Обратная ошибка — вставить в задачу половину кодовой базы. Лишний контекст отвлекает, размывает главное и занимает место, которое агенту нужно для работы. Давайте указатели, а не содержимое: агент сам откроет нужные файлы.

Контекст для отладки

Для бага самый ценный контекст — точные факты, а не пересказ. Вставьте текст ошибки целиком, фрагмент лога вокруг неё, шаги воспроизведения и окружение, где она возникает. Пересказ «падает при сохранении» теряет детали, по которым агент нашёл бы причину; точный текст исключения часто сразу указывает на файл и строку. Если ошибка воспроизводится только в определённых данных, опишите их или приложите обезличенный пример.

Границы и ограничения: что нельзя трогать

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

• Публичные контракты: формат ответов API, события, схемы сообщений, которые читают другие сервисы или мобильные приложения.
• Схема базы данных: изменения только через отдельную задачу и миграцию.
• Общие компоненты и библиотеки: правки в них затрагивают весь проект.
• Зависимости: новые пакеты — только после согласования.
• Конфигурация и инфраструктура: файлы сборки, CI, переменные окружения.
• Сгенерированный код: его правят через генератор, а не вручную.

Полезно формулировать границы и позитивно: «изменения только в папке модуля отчётов и его тестах». Такую границу легко проверить по списку изменённых файлов.

Критерии готовности, которые можно проверить

«Должно работать корректно» — не критерий. Критерий — это условие, которое можно проверить без спора: тест проходит, команда завершается без ошибок, при определённых входных данных получается определённый результат. Лучше всего, когда критерий выражен автоматическим тестом.

• Плохо: «форма должна нормально валидировать данные». Хорошо: «при пустом email форма не отправляется и показывает сообщение из файла переводов; тест на это есть и проходит».
• Плохо: «оптимизировать запрос». Хорошо: «список заказов загружается одним запросом к базе вместо отдельного запроса на каждый заказ; существующие тесты проходят».
• Плохо: «почистить код модуля». Хорошо: «вынести повторяющийся расчёт скидки в одну функцию; поведение не меняется, все тесты модуля проходят без изменений».

Сначала тест

Для багов хорошо работает порядок «сначала тест»: попросите агента написать тест, который воспроизводит ошибку и падает, затем исправить код так, чтобы тест прошёл, не меняя самого теста. Это защищает от частого трюка, когда агент подгоняет проверку под код, и оставляет в проекте защиту от повторения ошибки.

Задачи без единственного ответа

Для рефакторинга критерием служит сохранение поведения: все существующие тесты проходят, публичные интерфейсы не меняются, дифф не выходит за пределы нужного модуля. Для интерфейсных задач, которые сложно покрыть тестом, опишите, что должно быть видно на экране в конкретных состояниях, и проверьте это сами.

Нефункциональные требования

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

План до кода и отчёт после

Когда просить план

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

1. 01Проверьте, что агент правильно понял цель: пересказ задачи своими словами показывает это лучше всего.
2. 02Посмотрите список файлов, которые он собирается менять: нет ли там лишнего и не пропущено ли нужное.
3. 03Оцените выбранный подход: использует ли он существующие механизмы проекта или изобретает новые.
4. 04Обратите внимание на вопросы и допущения: каждое допущение — место, где вы могли что-то не сказать.
5. 05Поправьте план и только потом разрешите выполнение.

Что требовать в отчёте

• Список изменённых файлов и краткое объяснение каждого изменения.
• Какие команды проверки были запущены и с каким результатом — с выводом, а не пересказом.
• Что осталось непроверенным или вызвало сомнения.
• Какие решения агент принял сам, потому что в задаче этого не было.

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

Шаблон задачи и три условных примера

1. 01Цель: что и зачем нужно сделать.
2. 02Сейчас / должно быть: текущее и ожидаемое поведение.
3. 03Где: модули и файлы, образец похожего решения.
4. 04Нельзя: что не трогать и чего не добавлять.
5. 05Готово, когда: перечень проверяемых условий.
6. 06Проверка: команды, которые нужно запустить.
7. 07Отчёт: что показать по итогам.

Пример: исправление бага

Цель: пользователь не может сохранить профиль с длинным именем. Сейчас сервер возвращает ошибку; должно — сохранять имя в пределах допустимой длины и показывать понятное сообщение при превышении. Где: обработчик профиля и его тесты. Нельзя: менять схему базы. Готово, когда новый тест на длинное имя проходит вместе со всеми существующими. Проверка: тесты модуля профиля и проверка типов.

Пример: новая функция по образцу

Цель: менеджерам нужна выгрузка списка клиентов в CSV, как уже сделано для заказов. Где: образец — экспорт заказов в модуле отчётов. Нельзя: добавлять новые библиотеки, менять существующий экспорт. Готово, когда эндпоинт отдаёт файл с указанными колонками, доступен только ролям, которым доступен список клиентов, и на это есть тесты, включая отказ для роли без доступа.

Пример: рефакторинг

Цель: расчёт скидки продублирован в трёх местах и копии уже расходятся. Где: модуль корзины. Нельзя: менять поведение и публичные функции модуля. Готово, когда расчёт вынесен в одну функцию, все места используют её, а существующие тесты проходят без изменений. Отчёт: перечислить найденные расхождения между копиями до объединения — их решение остаётся за человеком.

Пример: исследование без изменений

Цель: понять, почему отчёт по продажам иногда расходится с данными в базе. Где: модуль отчётов и задания, которые его пересчитывают. Нельзя: менять код и данные. Готово, когда агент описал, откуда отчёт берёт данные, в какие моменты они пересчитываются и какие есть гипотезы расхождения со ссылками на конкретные места в коде. Такая задача полезна перед сложным изменением: вы получаете карту кода, а решение о правке принимаете сами.

Типовые ошибки постановки и как их заметить

• Несколько несвязанных задач в одной. Признак — в задаче есть «а ещё». Агент делает их наполовину и смешивает изменения; разделите на отдельные задачи и ветки.
• Решение вместо проблемы. Признак — задача начинается с «добавь библиотеку» или «сделай через». Вы диктуете способ, хотя в коде может быть подходящий механизм; опишите проблему и попросите варианты.
• Нет критерия остановки. Признак — агент продолжает «улучшать» и расширяет дифф. Добавьте конкретные условия завершения.
• Расплывчатые слова. «Оптимизировать», «почистить», «сделать удобнее» без уточнения. Замените их измеримым или наблюдаемым результатом.
• Нет объяснения «зачем». Признак — агент принимает формально верные, но странные решения в пограничных случаях. Добавьте цель и пользователя.
• Скрытые ожидания. Признак — на ревью вы пишете замечания, которых не было в задаче. Перенесите их в задачу или в правила проекта.

Уточнить или начать заново

Когда результат не устраивает, есть два пути: продолжить в той же сессии с уточнениями или откатить изменения и поставить задачу заново. Выбор зависит от того, где именно ошибка.

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

Само уточнение тоже стоит писать как маленькую задачу. Одно конкретное замечание вместо общего «не то»: какой файл или поведение не устраивает, почему и что должно получиться. Повторите критерий готовности, который не выполнен, и попросите снова запустить проверки. Несколько расплывчатых замечаний подряд чаще запутывают агента, чем помогают ему.

Чек-лист перед отправкой задачи

1. 01Понятно ли из текста, зачем нужна задача и для кого?
2. 02Описано ли текущее и ожидаемое поведение?
3. 03Указаны ли точка входа в коде и образец похожего решения?
4. 04Перечислено ли, что трогать нельзя?
5. 05Указаны ли ограничения: библиотеки, совместимость, безопасность?
6. 06Можно ли проверить каждый критерий готовности без обсуждения?
7. 07Есть ли тест, который должен пройти, или задача написать его первым?
8. 08Указаны ли команды проверки?
9. 09Сказано ли, что включить в отчёт?
10. 10Нужен ли для этой задачи план до правок?
11. 11Укладывается ли ожидаемый результат в дифф, который вы готовы внимательно прочитать?

Вывод

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

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