Модуль 2 · Качество · урок 12 из 17
Документация, миграции и рутина
Ради рутины многие и пробуют агента: обновить README, написать миграцию, поднять версию пакета, переименовать поле в сорока файлах. Задачи скучные, но рискованные. Ошибка в миграции стоит дороже, чем в вёрстке, а массовая правка легко задевает лишнее. Ниже о том, как ставить такие задачи, чтобы проверка занимала минуты, и как не писать один и тот же промпт каждую неделю.
Что подходит, а что нет
Агенту стоит отдавать рутину, результат которой проверяется механически или быстрым чтением диффа.
| Задача | Что дать агенту | Как проверить |
|---|---|---|
| Обновить документацию после изменения | Дифф или ветку, путь к документу | Каждое утверждение сверено с кодом |
| Миграция схемы | Текущую модель, соседние миграции, правила | Миграция и откат на копии базы |
| Обновление зависимости | Пакет, целевую версию, changelog | Тесты, сборка, список breaking changes |
| Массовая однотипная правка | Один эталонный пример | Линтер, тесты, git diff --stat |
| Changelog и release notes | Диапазон коммитов, формат | Чтение человеком |
| Переводы и словари | Файлы локализации, глоссарий | Ключи на месте, плейсхолдеры целы |
Плохо подходят задачи, где «правильно» знаете только вы и не можете это сформулировать. Например, «наведи порядок в конфигах». Сначала опишите, какой порядок вам нужен.
Документация из кода
Документация устаревает незаметно, и агент хорошо её догоняет. Слабость у него одна: он пишет гладкий текст, в котором часть утверждений взята из представлений о том, «как обычно бывает», а не из кода. Поэтому просите опираться на код:
Мы изменили сборку посадочных страниц (см. 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. Если что-то сломалось — не чини обходом,
остановись и опиши проблему.Без последней фразы агент склонен «чинить» несовместимость локальными заплатками, и вместо обновления пакета вы получите патч поверх него.
Массовые однотипные правки
Схема та же, что «образец → рецепт → тираж» в уроке «Рефакторинг и легаси»: сначала эталон, потом тираж, потом механическая проверка.
- Попросите агента сделать правку в одном файле и внимательно прочитайте результат.
- Скажите: «Сделай так же во всех компонентах из
git ls-files 'plugins/*/components/*.php'. Ничего сверх этого не меняй». - Посмотрите
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, и они работают у всех, кто открыл проект. Как их писать, рассказывают уроки Навыки и Пишем свой навык.
Следующий шаг — запуск по расписанию: сводка по коммитам за неделю или проверка устаревших пакетов раз в месяц. Переходите к нему, только когда задача уже стабильно получается вручную. Об этом урок Задачи по расписанию.
Попробуйте сами
10–15 мин на рабочем месте- Выберите документ в своём репозитории, который давно не обновляли. Попросите Codex сверить его с кодом и выдать таблицу «утверждение → файл:строка» с пометками «верно / устарело / не нашёл».
- Допишите в AGENTS.md раздел «Миграции» с правилами вашего проекта, включая хотя бы одно неочевидное последствие вроде нашего
updated_at. - Сделайте с агентом одну массовую правку по схеме «эталон → тираж →
git diff --stat» на 5–10 файлах.
Коротко
- Отдавайте агенту рутину, результат которой проверяется механически или быстрым чтением диффа.
- В документации требуйте опоры на код: таблица источников и список вопросов вместо догадок.
- Правила миграций и их неочевидные последствия держите в AGENTS.md, миграции проверяйте циклом «вперёд-назад-вперёд».
- Зависимости обновляйте по одной на коммит. При несовместимости агент останавливается и ничего не латает.
- Массовые правки делайте через эталон, тираж и проверку. Повторяющийся промпт стоит превратить в навык.