Промпт для Codex: цель, контекст, ограничения и готовность

Краткий ответ

Сильный промпт для coding agent похож на короткий инженерный контракт. Он описывает требуемый результат, релевантный контекст, реальные границы и доказательство завершения. Жёсткий шаблон не обязателен, но эти элементы предотвращают большинство дорогих недоразумений.

Начинайте с результата

Формулируйте изменение в терминах поведения системы:

«гость не видит персональную плашку рейтинга»;
«повторная отправка запроса не создаёт вторую запись»;
«страница имеет один осмысленный H1»;
«администратор может загрузить изображение и увидеть его после перезагрузки».

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

Четыре части рабочего промпта

Удобная структура:

1. Цель — что должно измениться для пользователя или системы. 2. Контекст — где проявляется задача и какие материалы важны. 3. Ограничения — что сохранить, чего не делать, где запросить решение. 4. Готово, когда — какие автоматические и ручные проверки подтверждают результат.

Пример:

Цель: устранить повторное начисление баллов при повторной отметке задачи.

Контекст: backend/src/users, текущая история активности в MongoDB и тесты
users.service.spec.ts. В базе могут существовать старые дубли.

Ограничения: не меняй публичный формат API и не пересчитывай данные
пользователей отдельным административным скриптом.

Готово, когда: новая отметка идемпотентна, старые дубли нормализуются при
чтении, добавлены регрессионные тесты и проходит backend test.

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

Ограничения должны защищать реальный риск

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

не менять внешний контракт;
не отправлять сообщения и не публиковать результат;
не выполнять миграцию на production;
не устанавливать новую зависимость без необходимости;
сохранить обратную совместимость с существующими документами;
остановиться при обнаружении конфликтующих пользовательских изменений.

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

Определение готовности — это не «сделай хорошо»

Критерий должен быть наблюдаемым. Комбинируйте уровни:

Уровень Пример доказательства

Код diff ограничен нужной областью

Автоматика проходят unit-тест, typecheck и lint

Интеграция API возвращает ожидаемый статус и тело

Интерфейс сценарий проверен в реальном браузере

Данные повторная операция не создаёт дубль

Тест «сборка проходит» не доказывает пользовательское поведение. Скриншот не доказывает отсутствие регрессии в API. Выбирайте проверки по риску задачи.

Как уточнять задачу во время работы

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

Хорошее уточнение:

Уточнение: найденная таблица legacy_users остаётся только для чтения.
Не добавляй в неё новые поля. Продолжай с основной схемой users.

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

Практика: перепишите расплывчатый запрос

Исходный запрос: «Сделай авторизацию безопаснее».

Составьте новый вариант, в котором:

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

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

Частые вопросы

Нужно ли всегда использовать один и тот же шаблон?

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

Следует ли писать техническое решение в промпте?

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

Можно ли попросить Codex самому определить критерии готовности?

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

Что важно запомнить

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

https://yadro-code.ru/lessons/without-university/codex-agent-workflows/codex-agent-03