Повторяемая задача для Codex начинается не с длинной команды, а с чёткой границы результата. Если написать «разберись с проектом и всё исправь», агенту придётся угадывать область изменений, критерии готовности и допустимые действия. Такой запрос может дать полезный черновик, но его сложно повторить и проверить. Автоматизация становится надёжнее, когда задача описана как короткий контракт: что нужно получить, какие файлы входят в область, какие действия запрещены и какой проверкой подтверждается результат.
Сначала определите результат, а не набор команд
Практическая формулировка должна отвечать на четыре вопроса: какой артефакт изменится, какое поведение должно появиться или сохраниться, какие ограничения нельзя нарушать и чем измеряется готовность. Например, учебная задача может звучать так: «Обновить обработчик формы в каталоге src/forms, сохранить публичный API, добавить тест на пустое значение и запустить целевой набор тестов». Здесь есть объект работы, ограничение, ожидаемая проверка и понятный финал.
Отдельно полезно записать, что не входит в задачу. Запрет на изменение схемы базы, внешних интеграций или конфигурации деплоя сокращает риск случайного расширения. Если область нельзя выразить несколькими путями, опишите её через конкретный пользовательский сценарий и список затрагиваемых модулей.
Разделите задачу на подготовку, изменение и проверку
Надёжный процесс повторяемой автоматизации состоит из трёх фаз. Сначала агент читает инструкции репозитория, проверяет состояние рабочей копии и находит связанные файлы. Затем вносит минимальное изменение. В конце запускает проверки, просматривает diff и сообщает, какие ограничения подтверждены. Такой порядок снижает вероятность начать редактирование до того, как обнаружены локальные правила проекта.
- Подготовка. Найти правила, тесты, точки входа и существующие ограничения.
- Изменение. Исправить только необходимый участок, сохраняя стиль и интерфейсы.
- Проверка. Запустить релевантные тесты, проверить diff и отдельно проверить негативные сценарии.
Если задача запускается регулярно, сохраните этот порядок в инструкции или навыке. Codex поддерживает многошаговую работу с инструментами и средой, но конкретные разрешения, состояние и доступ к файлам задаются используемым приложением. Поэтому процесс должен быть понятен и без предположения о конкретной оболочке.
Подготовьте инструкции для агента
Локальные правила проекта должны быть короткими и применимыми. Хорошая инструкция сообщает, как запускать тесты, где лежат исходники, какие каталоги нельзя менять без отдельного согласования, какой формат нужен для новых файлов и какие команды считаются безопасными. Не стоит складывать туда историю всех решений: для текущей задачи важнее проверяемые правила.
Для учебного примера можно завести файл с такими разделами: «Структура», «Проверки», «Запрещённые изменения», «Критерии готовности». Если в репозитории используются вложенные инструкции, размещайте более узкие требования ближе к коду. Codex учитывает инструкции от корня к текущему каталогу, поэтому конфликтующие правила нужно устранять, а не маскировать большим количеством текста.
Выберите инструменты и границы доступа
Автоматизация не означает, что агенту нужен доступ ко всему проекту. Для статического исправления достаточно чтения исходников, редактирования целевого каталога и запуска тестов. Доступ к сети, секретам, публикации и удалённым системам должен быть отдельной необходимостью, а не настройкой по умолчанию. Если задача работает с внешним API, зафиксируйте разрешённые хосты, типы запросов и правило: сначала прочитать состояние, потом выполнять изменение.
Полезно различать обратимые и необратимые действия. Форматирование файла или создание теста легко пересмотреть. Удаление данных, отправка сообщения, публикация релиза и изменение настроек доступа требуют отдельной проверки фактического состояния и более узкого сценария. Агенту следует поручать не «сделать всё», а выполнить конкретный шаг с наблюдаемым результатом.
Сделайте проверки частью самой задачи
Фраза «проверь, что всё работает» слишком расплывчата. Укажите команды, ожидаемый тип результата и минимальный набор случаев. Для функции расчёта это могут быть обычное значение, пустой ввод и предельное значение. Для веб-изменения — тест рендера, запрос к целевому маршруту и проверка пользовательского сценария. Для миграции — сравнение до и после на учебной выборке.
| Участок | Проверка | Сигнал готовности |
|---|---|---|
| Исходный код | Линтер и типы | Нет новых ошибок |
| Поведение | Целевые тесты | Сценарии проходят |
| Граница | Негативный случай | Ошибка обрабатывается явно |
Если проверка не может быть автоматизирована, сформулируйте ручной критерий: какой экран открыть, какое поле заполнить и какой результат увидеть. Это превращает субъективное «похоже, готово» в воспроизводимую процедуру.
Сохраняйте отчёт и повторяйте только нужный шаг
После выполнения полезно сохранить краткий отчёт: изменённые файлы, команды, результаты, оставшиеся ограничения и вопросы для человека. Такой отчёт помогает отличить успешное завершение от частичного результата. Если тест упал, следующая итерация должна начинаться с причины падения и минимального исправления, а не с повторного выполнения всей задачи вслепую.
Для регулярного запуска добавьте защиту от дубликатов и повторов. Перед публикацией, отправкой или изменением внешней системы сначала читайте сохранённое состояние. При сбое фиксируйте прогресс атомарно, чтобы повтор продолжал с последнего подтверждённого шага. Это особенно важно для пакетных задач, где один плохой элемент не должен стирать результат предыдущих.
Учебный шаблон задачи
Ниже — учебный шаблон, который можно адаптировать под проект:
- Цель: какое измеримое изменение должно появиться.
- Область: каталоги, файлы и сценарий, который разрешено затронуть.
- Ограничения: интерфейсы, данные и внешние системы, которые нельзя менять.
- Порядок: прочитать инструкции, исследовать, изменить, проверить.
- Приёмка: конкретные команды и ожидаемые результаты.
- Отчёт: diff, проверки, ограничения и нерешённые вопросы.
Такой формат не гарантирует идеальный результат автоматически. Он делает работу прозрачной: человек понимает, что поручил агенту, а агент получает критерии, по которым можно остановиться. Чем чаще задача повторяется, тем важнее превращать найденные ошибки в тест или правило, а не в устное замечание.
Обработайте сбои и неполный прогресс
Повторяемая автоматизация должна предполагать, что выполнение прервётся в середине. Причиной может быть упавший тест, временно недоступная сеть, конфликт в рабочей копии или недостаток прав. Запрос «повтори всё» опасен: часть действий уже могла завершиться, а повтор может создать дубль. Надёжная задача хранит состояние по шагам или хотя бы умеет определить, какие результаты уже существуют.
Учебный пример — пакетная обработка десяти файлов. После каждого успешного файла можно записывать его имя и контрольную сумму. При повторе агент сначала читает журнал, пропускает подтверждённые элементы и продолжает с первого незавершённого. Если результат файла существует, это ещё не доказывает успех: проверьте размер, формат и содержимое. Для внешнего действия нужен более сильный идентификатор операции.
Добавьте наблюдаемость без лишнего шума
Отчёт автоматизации должен помогать расследованию, а не превращаться в стенограмму всех команд. Достаточно фиксировать начало и конец шага, его идентификатор, результат проверки и ссылку на изменённый артефакт. Секреты, токены и полные пользовательские данные в журнал не попадают. Если команда вывела чувствительные значения, отчёт должен их маскировать.
Для длительной задачи полезны три статуса: «не начато», «в работе», «подтверждено». Отдельно храните ошибку и время последней проверки. Это позволяет отличить отсутствие результата от устаревшего результата. При изменении входных файлов старый статус следует считать недействительным и запускать проверку заново.
Проверьте автоматизацию на учебных данных
До работы с реальными данными прогоните сценарий на небольшом безопасном наборе. В него стоит включить нормальный объект, пустой объект, поврежденный объект, дубликат и файл неожиданного формата. Такой набор выявляет не только ошибки алгоритма, но и неправильное поведение при повторном запуске. Учебные примеры нужно явно отделять от фактических данных проекта.
Сравните ожидаемый и фактический результат по каждому объекту. Не ограничивайтесь количеством обработанных файлов: проверьте поля, связи, порядок и побочные эффекты. Если задача меняет HTML, сравните обязательные элементы и внутренние ссылки. Если создаёт изображение, проверьте тип, разрешение и уникальность файла.
Когда задачу нельзя считать автоматизированной
Иногда процесс формально запускается одной командой, но всё равно требует ручного решения на каждом шаге. Это не провал: просто границу автоматизации нужно назвать. Например, агент может собрать кандидатов и подготовить отчёт, а публикация остаётся ручной. Или он может предложить изменение доступа, но не применять его без проверки владельца.
Разделите такие этапы в контракте. Укажите, какой артефакт готовит агент, кто принимает решение и какая информация нужна для выбора. Это предотвращает скрытое расширение полномочий и делает процесс устойчивым при смене исполнителя.
Соберите критерии остановки и продолжения
У каждой автоматической задачи должны быть условия остановки. Агент останавливается, если достигнут критерий готовности, если входные данные противоречат ожиданиям или если действие выходит за разрешённую область. Отдельно укажите, когда допустим повтор: например, после временной ошибки сети, но не после ошибки схемы или отказа в доступе. Без этой границы повтор может замаскировать проблему и увеличить ущерб.
Критерии продолжения должны быть такими же конкретными. Если тест падает из-за изменённого ожидания, агент может исследовать причину и предложить исправление. Если не найден обязательный первичный источник, нельзя заменять его догадкой. Если нужный файл уже изменён пользователем, задача должна сохранить эти изменения и включить их в анализ, а не перезаписать рабочую копию.
Для регулярного запуска полезно хранить контрольный снимок входа: дату, идентификатор версии, список объектов и хеши. При следующем запуске сравнение показывает, что действительно изменилось. Это сокращает ненужные действия и помогает доказать, что результат относится к актуальной версии данных.
Перед передачей задачи в расписание проведите пробный запуск в режиме без побочных эффектов. Он должен собрать входы, показать план изменений и перечислить проверки, но не публиковать и не удалять. После просмотра отчёта можно разрешить ограниченное выполнение. Такой двухфазный режим полезен там, где ошибка стоит дорого: в рассылках, каталогах, платежных статусах и конфигурациях доступа.
Наконец, договоритесь о владельце результата. Автоматизация может подготовить файл или отчёт, но кто-то должен отвечать за актуальность правил, обработку исключений и пересмотр процесса при изменении продукта. Без владельца даже хорошо написанная задача постепенно расходится с реальностью.
Хороший владелец также определяет срок действия результата. Отчёт о проверке, список кандидатов или подготовленный пакет не обязательно остаются верными навсегда. В метаданных укажите время проверки и событие, после которого нужна новая валидация: изменение версии, входных данных, схемы или внешней политики. Это особенно важно для задач, которые запускаются по расписанию и работают на изменяющемся контексте.
Перед запуском в расписании полезно провести сухой прогон. Он показывает входные данные, план изменения и будущие проверки, но не выполняет побочные эффекты. После просмотра отчёта можно включить ограниченный режим. Такая двухфазная схема снижает риск ошибок в рассылках, каталогах, платёжных статусах и конфигурациях доступа.
Если сухой прогон и реальное выполнение используют разные пути кода, сравните их отдельно. Иначе демонстрационный результат может не отражать фактическое поведение. В описании задачи укажите, какая часть проверена симуляцией, а какая — реальным тестовым действием.