Примечание автора: статья адресована разработчикам, которые уже используют Agent в работе. Разберём, какой контекст, справочные материалы и проверяемые критерии приёмки стоит подготовить до передачи задачи и какие вопросы по-прежнему требуют участия человека.
С появлением Agent результатов действительно стало больше, но люди стали уставать ещё сильнее. 3 ноября 2026 года разработчик на V2EX описал это состояние: человек остаётся внутри рабочего цикла — проверяет результаты, постоянно исправляет отклонения от задачи и проблемы в проектировании. По-настоящему отпустить процесс не получается. В посте упоминался известный приём: подробный контекст и справочные материалы помогают Agent понять задачу и повысить качество результата. Но что именно значит «подробный», автор не пояснил.
Это не очередная статья с общими советами о том, как написать хороший промпт. Мы сосредоточимся на подготовке к передаче задачи: разложим размытые требования на цели, ограничения, справочные материалы и проверяемые критерии выполнения. Благодаря этому Agent сможет проверять себя сам, а вам останется вмешиваться лишь на нескольких ключевых этапах. При этом открытых сравнительных данных, которые позволили бы количественно оценить эффективность разных способов подготовки, сейчас нет. Примеры в статье обобщают распространённые ситуации — проверяйте их эффективность на своих задачах.
Главное: вы получите многоразовую структуру описания задачи для Agent и способы формулировать критерии приёмки, а также сможете определить, что Agent способен проверить самостоятельно, а где решение должен принять человек.
Контекст и критерии приёмки для Agent: главное
Прежде чем писать описание задачи, стоит понять общую картину: чаще всего Agent отклоняется от курса, потому что его представление о том, «что делать», «какого результата достичь» и «что нельзя трогать», не совпадает с вашим. В таблице ниже — пять элементов, которые стоит включить в описание задачи.
| Элемент | Что указать | Какую проблему решает |
|---|---|---|
| Цель | В одном предложении объясните, что нужно сделать и для кого | Не даёт Agent самостоятельно расширять требования или уходить в сторону |
| Контекст | Текущее состояние проекта, связанные модули, уже опробованные решения | Помогает не изобретать велосипед и не ломать существующую архитектуру |
| Ограничения | Какие файлы нельзя менять, какой стек обязателен, какие есть требования к производительности и совместимости | Защищает от решений, которые «работают, но пользоваться ими нельзя» |
| Справочные материалы | Примеры существующего кода, документация API, образцы стиля | Помогают приблизить стиль и структуру результата к принятому в проекте |
| Критерии приёмки | Условия завершения, которые можно проверить по пунктам, в идеале автоматически | Позволяют Agent проверить себя и избавляют вас от необходимости изучать каждую строку |
Как понять, что Agent отклонился от задачи
В исходном посте конкретных примеров не было, поэтому ниже собраны несколько типичных ситуаций для программирующих и других Agent, выполняющих задачи. Они выглядят по-разному, но причина часто одна: в описании задачи не хватило какого-то элемента.
| Как проявляется | Частая причина | Как предотвратить |
|---|---|---|
| Исправляя баг, Agent заодно отрефакторил полмодуля | Границы цели размыты, допустимый объём изменений не указан | В ограничениях перечислите файлы или функции, которые разрешено менять |
| Добавил новую зависимость, которой нет в проекте | Не знает существующий стек | В контексте перечислите имеющиеся зависимости и укажите, можно ли добавлять новые |
| Стиль кода отличается от остальной части проекта | Не хватает примеров | Приложите в качестве справочных материалов одну-две похожие реализации |
| Сообщил «готово», но не учёл важные сценарии | Критерии завершения размыты | Запишите критерии приёмки в виде проверок, которые можно выполнить |
| Решение технически работает, но не соответствует замыслу продукта | Проектные решения заранее не объяснили | Сначала примите проектное решение сами, а затем поручите реализацию Agent |
Последний случай заслуживает особого внимания. Дело здесь не в «недостатке контекста»: решение о компромиссах в дизайне должен принять человек. Об этом поговорим отдельно ниже.
Как подготовить описание задачи для Agent: структура из пяти частей
Собрав пять перечисленных выше элементов в одном документе, вы получите описание задачи, которое Agent сможет понять и использовать для самопроверки. Удобнее всего вести его в Markdown и хранить в репозитории проекта — например, в файле TASK.md. Другой вариант: общие ограничения разместить в файле с инструкциями для проекта, например AGENTS.md, а конкретную цель — в документе отдельной задачи.
Часть первая: как сформулировать цель задачи для Agent
Цель должна одним предложением объяснять, что нужно получить в результате, для кого и в каком сценарии. Формулировку «оптимизировать модуль входа» Agent может понять по-разному: как повышение производительности, рефакторинг кода или обновление интерфейса. Лучше написать так: «Сделать так, чтобы API входа возвращал единый код ошибки при неверном пароле, а фронтенд показывал соответствующее сообщение. Процесс успешного входа менять не нужно».
Если задача крупная, стоит добавить под целью фразу о том, что в неё не входит. Чёткие исключения зачастую лучше предотвращают расширение требований со стороны Agent, чем описание того, что нужно сделать.
Часть вторая: как дать Agent контекст
Главное в контексте — не объём, а полезность. Передать Agent весь репозиторий ещё не значит дать ему достаточно контекста: ему всё равно нужно знать, какие части связаны с текущей задачей. Удобно собрать эту информацию в таком порядке:
- Связанные модули: перечислите файлы или директории, которые напрямую относятся к задаче, например логику входа в
src/auth/и соответствующие тесты. - Принятые решения: объясните, почему всё устроено именно так. Например: «Коды ошибок централизованно определяются в модуле
errors, а не прописываются в бизнес-логике». - Уже опробованные варианты: если какой-то подход уже пробовали и от него отказались, укажите причину, чтобы Agent не повторял ту же работу.
- Объяснение терминов: расскажите о внутренних бизнес-терминах проекта, которые Agent не сможет надёжно вывести из кода.
Часть третья: список ограничений для Agent
Ограничения помогают избежать результата, который «работает, но использовать его нельзя». Их удобно оформить списком, чтобы Agent сверился с ним перед началом работы и после её завершения:
- Разрешённая область изменений и файлы, которые явно запрещено менять, например скрипты миграции базы данных или определения публичных интерфейсов.
- Ограничения по стеку, например «не добавлять сторонние зависимости» или «использовать только библиотеку логирования, уже принятую в проекте».
- Требования к совместимости и производительности, например «не менять сигнатуры существующих интерфейсов».
- Порядок действий в неоднозначных ситуациях, например «если потребуется изменить публичный интерфейс, остановиться и объяснить причину, а не менять его самостоятельно».
Последний пункт особенно важен. Чётко обозначить Agent, когда нужно остановиться и спросить человека, гораздо проще, чем потом разбираться с последствиями его самостоятельных решений.
Часть четвёртая: как выбрать справочные материалы для Agent
Справочные материалы помогают Agent опираться на существующие решения, а не придумывать всё с нуля. Обычно полезнее всего аналогичные реализации в том же проекте. Например: «При добавлении интерфейса ориентируйся на код в src/user/, включая проверку параметров и обработку ошибок». Из внешней документации давайте только разделы, относящиеся к задаче, и указывайте версию, чтобы Agent не написал код для устаревшего интерфейса.
Как написать проверяемые критерии приёмки для Agent
Критерии приёмки — та часть описания задачи, где проще всего отделаться общими словами, но именно ей стоит уделить время. Правило простое: если Agent не может самостоятельно проверить, выполнен ли критерий, то это не критерий, а пожелание.
| Расплывчатая формулировка | Проверяемая формулировка | Способ проверки |
|---|---|---|
| Код должен быть качественным | Код проходит существующую в проекте lint-проверку без новых предупреждений | Agent запускает проверку и сообщает результат |
| Функциональность работает | Новые модульные тесты покрывают три случая: неверный пароль, отсутствие аккаунта и успешный вход. Все тесты проходят | Запустить тесты и привести краткую сводку результатов |
| Не затрагивать другие функции | Весь существующий набор тестов проходит, файлы, запрещённые к изменению в ограничениях, не затронуты | Запустить все тесты и перечислить изменённые файлы |
| Документация должна быть полной | Добавить в документацию API описание кодов ошибок в том же формате, что и существующие записи | Сверить каждый пункт с примером |
| Производительность не должна ухудшиться | На критическом пути не добавлено новых запросов к базе данных | В итоговом отчёте указать, как изменилось количество запросов |
Когда критерии готовы, попросите Agent в конце описания задачи отчитаться по каждому из них: указать, выполнен ли он, на каком основании и, если нет, почему. Тогда при проверке результата достаточно будет посмотреть эту таблицу, а не изучать все изменения с самого начала.
Контекст и критерии приёмки для агента: быстрый старт
Соберём всё вышесказанное в пошаговый план, которому можно сразу следовать. Дополнительные инструменты не нужны: для начала достаточно одного документа Markdown.
Подготовка задания для агента за 5 шагов
- Сначала напишите критерии приёмки, потом — цель: такой порядок заставит вас разобраться, как именно выглядит выполненная задача, и не даст сформулировать цель слишком широко.
- Добавьте контекст: кратко перечислите только относящиеся к задаче модули, уже принятые решения и неудачные попытки.
- Укажите ограничения и условия остановки: напишите, что нельзя менять и в каких ситуациях агент должен остановиться и задать вопрос.
- Подберите один-два примера: в первую очередь используйте похожие реализации внутри проекта, а из внешней документации приводите только нужные разделы.
- Попросите структурированный отчёт: после завершения агент должен отчитаться по каждому критерию приёмки, приложить список изменённых файлов и указать нерешённые вопросы.
Пример описания задачи для агента: исправление сообщений об ошибках входа
Ниже — пример структуры описания задачи для гипотетической ситуации. Замените пункты своими данными:
- Цель: интерфейс входа возвращает единый код ошибки, если пароль неверен или аккаунт не существует; фронтенд показывает сообщение на основе этого кода. Успешный вход и стили страницы не меняем.
- Контекст: коды ошибок определены в модуле
errors. Ранее пробовали проверять текст ошибки на фронтенде, но отказались от этого из-за мультиязычности. - Ограничения: можно менять только
src/auth/и соответствующие тесты; новые зависимости добавлять нельзя. Если потребуется изменить определение публичного интерфейса, остановиться и сообщить об этом. - Справочные материалы: обработка ошибок в интерфейсе регистрации в
src/user/. - Критерии приёмки: добавить модульные тесты для трёх сценариев и убедиться, что они проходят; все существующие тесты проходят; линтер не выдаёт новых предупреждений; в документацию интерфейса добавлены описания двух кодов ошибок.
- Формат отчёта: пройтись по каждому критерию приёмки, перечислить изменённые файлы и указать нерешённые проблемы.
🚀 Совет для начала: одну и ту же задачу можно поручить разным моделям и сравнить, какая из них лучше соблюдает ограничения и условия остановки. Через агрегаторы вроде APIYI (apiyi.com) можно переключаться между моделями разных разработчиков с помощью единого интерфейса и одного ключа. Это избавит от необходимости регистрировать и настраивать несколько аккаунтов и позволит сравнить модели на реальных задачах.
Перекрёстная проверка работы агентов моделями разных поставщиков
Автор исходного поста упомянул ещё одно опасение: у моделей одного поставщика могут быть похожие слепые зоны. Поэтому он хотел бы, чтобы агенты разных поставщиков проверяли работу друг друга. Но пока передавать информацию между ними приходится через Markdown-документы или копированием и вставкой, что сильно усложняет координацию. Эту идею можно совместить с подходом из статьи: само описание задачи и критерии приёмки — лучшая общая основа для перекрёстной проверки. Проверяющему не обязательно понимать весь ваш замысел: достаточно последовательно оценить результат по одним и тем же критериям.
Один из простых вариантов — распределить роли между моделями и дать каждой одно и то же описание задачи:
| Роль | Входные данные | Обязанности | Способ подключения |
|---|---|---|---|
| Исполнитель | Описание задачи | Реализовать решение и самостоятельно проверить его по критериям приёмки | Ваш привычный агент для программирования |
| Проверяющий A | Описание задачи + сводка изменений | Проверить каждый критерий приёмки и указать неохваченные сценарии | Модель другого поставщика, которую можно вызвать через единый интерфейс APIYI |
| Проверяющий B | Описание задачи + сводка изменений | Проверить соблюдение ограничений и условий остановки | Модель третьего поставщика: достаточно сменить имя модели в том же интерфейсе |
| Человек | Сводка замечаний | Разобрать только разногласия между проверяющими и вопросы проектирования | Не требуется |
Если написать небольшой скрипт, который свяжет этапы «результат выполнения → отправка моделям для проверки → сбор замечаний», большую часть ручного копирования можно будет исключить. APIYI предоставляет единый интерфейс, совместимый с популярными SDK: чтобы вызвать модель другого поставщика, достаточно сменить её имя в скрипте. Это упрощает самую хлопотную часть подключения агентов от разных поставщиков. Но важно помнить: автоматизируется передача информации, а окончательное решение по-прежнему должно оставаться за человеком.
Какие проблемы решает контекст Agent, а где нужен контроль человека
Хорошо подготовленный контекст избавляет от многих исправлений по ходу работы, но полностью исключить участие человека не может. В исходном посте рядом упоминаются «отклонение от задачи» и «проблемы проектирования», хотя это проблемы разной природы: первая чаще всего связана с нехваткой информации, а вторая — с выбором между вариантами.
| Тип проблемы | Можно ли решить с помощью контекста | Причина | Роль человека |
|---|---|---|---|
| Выход за границы изменений | В основном да | Если чётко прописать ограничения, Agent сможет себя проверить | Выборочно проверить список изменений |
| Несоответствие стиля и формата | В основном да | Достаточно привести образцы для подражания | Изредка проверять |
| Неполное покрытие тестами | По большей части да | Достаточно указать сценарии в критериях приёмки | Проверить полноту списка сценариев |
| Архитектурные и проектные решения | Сложно | Нужно выбирать между несколькими разумными вариантами | Принять решение заранее и записать его в описании задачи |
| Продуктовые цели и пользовательский опыт | Сложно | Зависят от бизнес-целей и понимания пользователей | Определить заранее и проверить при приёмке |
| Правильность самих критериев приёмки | Нет | Agent может свериться с критериями, но не способен поставить под сомнение их предпосылки | Ответственность обязательно несёт человек |
Проблемы проектирования сложно полностью доверить Agent, потому что у них обычно нет единственного правильного ответа. Например, коды ошибок можно разместить как в общем модуле, так и в бизнес-модуле — оба варианта будут работать. Выбор зависит от планов команды по развитию системы и привычных подходов к сопровождению, а эти соображения нередко существуют лишь в головах людей и их сложно полностью изложить на бумаге.
Поэтому практичнее вовлекать человека раньше: принять проектные решения до начала работы и записать их в ограничениях. Тогда во время выполнения задачи за Agent не придётся постоянно следить. По завершении останется только проверить таблицу приёмки и разногласия между проверяющими. Так роль человека в процессе меняется: вместо того чтобы сопровождать работу от начала до конца, он «задаёт направление на старте и принимает результат в конце».
Частые вопросы FAQ
Q1: Что такое критерии приёмки для агента?
Критерии приёмки — это условия, которые должны быть выполнены по завершении задачи и которые можно проверить по отдельности. Например: «все указанные тесты пройдены» или «файлы, которые запрещено менять, не изменены». Они помогают агенту проверить себя, а человеку — быстро оценить результат, не читая весь вывод построчно.
Q2: Чем больше контекста, тем лучше?
Нет. Лишняя информация отвлекает от главного и может даже подтолкнуть агента к изменениям там, где они не нужны. Контекст стоит подбирать под конкретную задачу: включать связанные модули, уже принятые решения, неудачные попытки и необходимые термины. Если вы не уверены, полезна ли какая-то информация, можно через APIYI apiyi.com вызвать разные модели и протестировать краткую и полную версии описания задачи. Так вы увидите, с какой из них агент реже отклоняется от цели.
Q3: Нужно ли так подробно описывать каждую небольшую задачу?
Нет. Общие ограничения и контекст проекта можно один раз записать в файл инструкций проекта и использовать повторно. Для отдельной задачи достаточно добавить цель, справочные материалы и критерии приёмки. Для небольшого изменения на несколько минут обычно хватает одного предложения с целью и двух-трёх критериев приёмки.
Q4: Для каких агентов и задач подходит этот подход?
В первую очередь — для агентов-программистов и агентов, выполняющих задачи с конкретным результатом: исправление ошибок, реализация интерфейсов, создание документации или обработка данных. Если задача исследовательская и её цель ещё не определена, заранее сформулировать критерии приёмки сложно. В таком случае лучше сначала обсудить направление с агентом и только потом приступать к работе.
Q5: Как организовать перекрёстную проверку моделями разных поставщиков без постоянного копирования и вставки?
Можно написать небольшой скрипт, который отправит результат работы вместе с описанием задачи проверяющим моделям, а затем соберёт их замечания. Благодаря единому интерфейсу APIYI apiyi.com для вызова моделей разных поставщиков достаточно сменить имя модели в скрипте — отдельно подключать SDK и создавать аккаунт у каждого поставщика не придётся. Это удобно для быстрого создания прототипа процесса «выполнение + проверка несколькими моделями».
Q6: Какие ограничения есть у этого подхода?
Во-первых, он не заменяет проектных решений: архитектурные компромиссы и цели продукта по-прежнему определяет человек. Во-вторых, если критерии приёмки составлены неверно, агент добросовестно выполнит именно их. Кроме того, пока не хватает открытых данных, которые позволили бы количественно сравнить эффективность разных способов подготовки. Поэтому стоит провести небольшое сравнение на собственных задачах и для ориентира записывать, сколько раз пришлось корректировать работу агента.
Контекст и критерии приёмки для агента: главное
- Отклонения от задачи чаще всего возникают из-за нехватки информации: отсутствие цели, ограничений или справочных материалов может привести к переделкам.
- Пять элементов описания задачи: цель, контекст, ограничения, справочные материалы и критерии приёмки — нужны все пять.
- Критерии приёмки должны быть проверяемыми: если агент не может проверить их самостоятельно, это лишь пожелания.
- Задавайте условия остановки: заранее укажите, когда агент должен остановиться и задать вопрос, — это проще, чем потом исправлять результат.
- Принимайте проектные решения заранее: архитектурные и продуктовые компромиссы сначала определяет человек, а затем они входят в ограничения.
- Используйте единые критерии для перекрёстной проверки: через единый интерфейс APIYI можно вызывать модели разных поставщиков и сравнивать результаты проверки.
Итоги
Работа человека в цикле с агентом утомляет во многом потому, что задачу передают с неполной информацией. В результате приходится постоянно следить за процессом и поправлять агента. Подготовка заранее сводится к трём основным шагам:
- Описывайте задачу в пяти разделах: цель, контекст, ограничения, справочные материалы и критерии приёмки. Так агент будет знать, что нужно сделать, какого результата достичь и чего нельзя затрагивать.
- Формулируйте критерии приёмки как проверяемые пункты: попросите агента отчитаться по каждому из них. Вам останется просмотреть таблицу и нерешённые вопросы.
- Разделяйте вопросы, которые можно поручить агенту через контекст, и те, которые требуют контроля человека: проектные компромиссы решайте заранее, а за сами критерии приёмки отвечайте лично.
Начните со следующей реальной задачи: сначала запишите критерии приёмки, затем добавьте остальные разделы. Зафиксируйте, сколько раз вам пришлось вмешаться в процессе, — это поможет понять, что улучшить. Если вы также пробуете перекрёстную проверку моделями разных поставщиков, через единый интерфейс APIYI на apiyi.com можно подключить разные модели и проверить на реальных задачах, какая комбинация лучше всего сокращает необходимость вашего вмешательства.
📚 Источники
- Обсуждение на V2EX — как сократить вмешательство человека, чтобы агент работал самостоятельно и качественнее выполнял задачи: источник темы этой статьи
- Ссылка:
v2ex.com/t/1254207 - Описание: обсуждение усталости человека при постоянном участии в работе агента, роли контекста и идеи перекрёстной проверки агентами разных разработчиков
Автор: техническая команда APIYI
Обсуждение технологий: свяжитесь с нами через главную страницу сайта APIYI — apiyi.com, чтобы обменяться опытом описания задач для агентов и совместной работы нескольких моделей
