Как ставить задачу агенту

Качество работы агента сильнее всего зависит от двух вещей: насколько хорошо подготовлен проект и насколько понятно поставлена задача. Проектом займёмся в уроке про AGENTS.md, а здесь — постановка. Хорошая новость: это тот же навык, что нужен для задачи коллеге, только с поправкой на то, что агент не может сходить к вам переспросить в коридоре.

Четыре части постановки

Документация Codex в разделе Best practices предлагает по умолчанию включать в промпт четыре вещи:

• Цель (Goal) — что нужно изменить или построить.
• Контекст (Context) — какие файлы, папки, документы, примеры или ошибки относятся к задаче.
• Ограничения (Constraints) — каких стандартов, архитектуры, требований безопасности и соглашений придерживаться.
• Готово, когда (Done when) — что должно быть правдой в конце: тесты проходят, поведение изменилось, баг больше не воспроизводится.

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

Плохо и хорошо

Задача из трекера: «Интеграция с CRM: передавать UTM-метки из формы заявки».

Слабая постановка:

Добавь передачу UTM-меток в CRM.

Агенту придётся угадать: откуда брать метки, какие именно, в какое поле CRM, что делать, если меток нет, как проверить. Каждое угадывание — шанс промахнуться.

Сильная постановка:

Цель: при отправке формы заявки передавать в CRM метки utm_source,
utm_medium, utm_campaign, utm_content, utm_term.

Контекст: метки сохраняются в cookie при первом заходе — см.
@themes/site/assets/js/utm.js. Отправка в CRM —
@plugins/acme/crm/classes/LeadSender.php. Формат запроса к CRM описан
в @docs/crm-api.md, поле для меток — "source_details".

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

Готово, когда: есть тесты на случаи «все метки», «часть меток», «нет меток»;
`php artisan test --filter=LeadSender` проходит; в ответе перечисли
изменённые файлы.

Вторая постановка длиннее на минуту работы, но экономит несколько итераций переделок.

Контекст: показывайте, а не пересказывайте

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

Критерий готовности — самая важная часть

Без критерия агент остановится, когда код покажется ему правильным. С критерием — когда проверка прошла. Хороший критерий:

• называет конкретную команду: npm run test:e2e -- contact-form.spec.ts, ./gradlew testDebugUnitTest;
• описывает наблюдаемое поведение: «при пустом email показывается ошибка, запрос не уходит»;
• может включать требование к отчёту: «перечисли изменённые файлы и что не удалось проверить».

Последний пункт полезен: он заставляет агента явно сказать, где у него остались сомнения, а не прятать их в общем «готово».

Размер задачи

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

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

Сначала план

Если задача сложная, неоднозначная или её трудно описать, попросите агента сначала составить план, а не писать код. Документация называет три способа:

• Режим планирования (plan mode). Включается командой /plan или сочетанием Shift+Tab. Агент собирает контекст, задаёт уточняющие вопросы и предлагает план до того, как начать менять код.
• Интервью. Если идея пока размыта, попросите агента расспросить вас: «Прежде чем писать код, задай мне вопросы, которые нужны, чтобы превратить это в чёткую задачу. Оспаривай мои допущения».
• Шаблон плана. Для длинных многошаговых задач — файл с планом исполнения, по которому агент работает и отмечает прогресс. Это тема урока «Сначала план».

Типичные ошибки

• Постоянные правила в каждом промпте. «Пиши с declare(strict_types=1), классы по BEM, не трогай vendor» — это не постановка задачи, а правила проекта. Им место в AGENTS.md (урок «AGENTS.md»). Документация называет перегрузку промпта такими правилами одной из частых ошибок.
• Нет способа проверить. Агенту не сказали, как запустить сборку и тесты, — он не видит результат своей работы.
• Пропущенное планирование в сложной многошаговой задаче.
• Микроменеджмент. Расписывать каждый шаг не нужно: опишите результат и ограничения, путь агент найдёт сам.

Шаблон

Сохраните себе и подставляйте:

Цель: <что должно измениться>
Контекст: <файлы через @, ошибки, образцы, ссылки на документацию>
Ограничения: <что не трогать, каким соглашениям следовать>
Готово, когда: <команда проверки и наблюдаемое поведение>
В ответе: <список изменённых файлов, что не удалось проверить>