Документация, миграции и рутина

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

Что подходит, а что нет

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

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

Документация из кода

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

Мы изменили сборку посадочных страниц (см. git diff main...HEAD).
Обнови docs/LANDINGS.md под новое поведение.

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

Таблица источников превращает ревью документации из чтения прозы в проверку ссылок. Документацию держите в том же MR, что и код: так ревьюер видит обе части изменения сразу.

Миграции базы

Миграции — рутина с высокой ценой ошибки. Правила для агента лучше записать в AGENTS.md один раз:

## Миграции
- Плагины OctoberCMS: миграции в `plugins/<author>/<plugin>/updates/`, регистрация в `version.yaml`.
- Уже применённые миграции не редактировать — только новая миграция.
- У каждой миграции рабочий `down()`; если откат невозможен, напиши об этом в описании MR.
- Миграции контента обязательно обновляют `updated_at` у изменённых записей.
- Запускать миграции только в локальном Docker-окружении: `php artisan october:migrate`.
- Никогда не подключаться к продовой или общей тестовой базе.

Пункт про updated_at — пример проектного правила, которое агент сам не угадает. У нас от этой даты зависят sitemap и пометка «обновлено» на странице, и миграция без неё выглядит корректной, но ломает SEO. Таких неочевидных последствий в каждом проекте несколько, и их место — в AGENTS.md.

Сама задача:

Добавь в модель Case поле is_featured (boolean, по умолчанию false)
и миграцию для него. Проставь is_featured = true трём кейсам
с наибольшим sort_order. Проверь на копии базы: october:migrate проходит,
откат только этой версии плагина проходит, затем снова migrate.
Покажи итоговый SQL-эффект на тестовых данных.

Команду отката агент пусть найдёт сам в php artisan list и покажет вам до запуска: в OctoberCMS есть команды, которые откатывают не одну версию плагина, а всю базу. Проверка «вперёд-назад-вперёд» ловит большинство ошибок в down(), которые иначе всплывают в самый неудобный момент.

Обновление зависимостей

Обновлять пакеты с агентом удобно по одному: одна зависимость — один коммит. Так при регрессии понятно, что откатывать. Агенту для этого почти всегда нужна сеть: читать changelog и ставить пакеты. В режиме по умолчанию сеть в песочнице выключена, и Codex попросит одобрение. Для чтения актуальных changelog можно включить живой веб-поиск флагом --search.

Обнови guzzlehttp/guzzle до последней минорной версии в текущей мажорной.
Прочитай changelog между версиями и выпиши изменения, которые могут
нас задеть. Найди в коде все места использования затронутого API.
Запусти composer test. Если что-то сломалось — не чини обходом,
остановись и опиши проблему.

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

Массовые однотипные правки

Схема та же, что «образец → рецепт → тираж» в уроке «Рефакторинг и легаси»: сначала эталон, потом тираж, потом механическая проверка.

1. Попросите агента сделать правку в одном файле и внимательно прочитайте результат.
2. Скажите: «Сделай так же во всех компонентах из git ls-files 'plugins/*/components/*.php'. Ничего сверх этого не меняй».
3. Проверьте git diff --stat — нет ли файлов, которых вы не ждали, — и прогоните линтер и тесты.

Если файлов сотни, удобнее отдавать их порциями через codex exec в цикле: каждый вызов получает маленький изолированный контекст.

for f in $(git ls-files 'plugins/*/components/*.php'); do
  codex exec --sandbox workspace-write \
    "Проставь типы параметров и возвращаемых значений в методах $f по фактическому использованию. Поведение не меняй, другие файлы не трогай."
done
composer test

Подробнее о codex exec — в курсе Codex в автоматизации. Когда правка чисто механическая — добавить declare(strict_types=1), переименовать импорт, — не тратьте на неё модель: попросите агента написать скрипт или codemod, проверьте его на двух файлах и запустите на всех.

Из повторяющегося промпта — в навык

Если вы третий раз пишете один и тот же промпт для release notes или для обновления зависимостей, это сигнал. В документации Codex правило сформулировано так: повторяющийся промпт или процесс, который вы постоянно поправляете, стоит превратить в навык (skill). Навык — это каталог с файлом SKILL.md, где описаны шаги и проверки, плюс при необходимости скрипты. Командные навыки кладут в репозиторий в .agents/skills, и они работают у всех, кто открыл проект. Как их писать — в уроках Навыки и Пишем свой навык.

Следующий шаг — расписание: сводка по коммитам за неделю или проверка устаревших пакетов раз в месяц. Но только когда задача уже стабильно получается вручную. Об этом — урок Задачи по расписанию.