Плановое обслуживание
Назначение
Регулярно запускать агента на проходы, которые ищут дрейф кода, документации и агентского окружения, восстанавливают скрытые модели поведения и возвращают результат небольшими PR, описаниями моделей или тикетами. Каждый проход имеет свою частоту, свою область и свой способ запуска: в облаке, локально или вместе с вами.
Также известен как
Garbage collection, doc gardening, maintenance routines, регулярные задачи, санитарные проходы.
Проблема
Агенты пишут десятки тысяч строк в неделю. Ревью каждого PR проверяет только его diff. Если три PR по отдельности нарушают стандарт чуть-чуть и в разных местах, ни одно ревью этого не заметит, а через месяц отклонение станет новой нормой, которую агент копирует дальше.
Вместе с кодом устаревает всё, что помогает агенту работать. Глоссарий не знает о новых моделях, в AGENTS.md копятся правила, которые уже ничего не меняют, скил запуска приложения ссылается на удалённый скрипт, allowlist разрешений разрастается, а в личной памяти агента оседают факты о проекте, которых нет в репозитории. Каждая такая мелочь стоит агенту лишних вызовов и ошибок в каждой следующей сессии.
Разовая чистка «когда станет совсем плохо» не работает: к этому моменту дрейф уже разошёлся по кодовой базе, и исправление превращается в большой рискованный рефакторинг. Ручная еженедельная уборка тоже не масштабируется: команда тратит на неё день и всё равно не успевает за объёмом.
Решение
Когда кода от агентов много, дрейфует всё сразу: архитектура, границы слоёв, глоссарий, соблюдение стандартов, инструкции для самих агентов. Начните с недельного ритма для ревью стандартов, упрощения, безопасности и глоссария. Проходы по скрытым моделям и архитектуре чередуйте по областям, где изменения даются труднее всего. Инструкции, скилы, ADR и настройки агента меняются медленнее, их удобно проверять раз в месяц. Частоту меняйте по полезности находок и способности команды разбирать результат.
Каждый проход смотрит на конкретный участок: изменения за неделю, каталог, слой или доменное понятие. Проход по всему репозиторию сразу даёт поверхностный отчёт.
Поиск модели и изменение кода — разные проходы. Сначала вы получаете описание существующего поведения со ссылками на код и спорными местами, затем выбираете изменение. Результатом может быть небольшое исправление, принятая модель или тикет с вопросом к предметной области. Если менять нечего, проход заканчивается этим выводом. Обязательный PR после каждого запуска провоцирует ненужные правки.
Выбранное изменение выполняйте по правилам рефакторинга: с проверкой текущего поведения до и после правок. Плановые проходы дополняют небольшие улучшения в ходе обычных задач.
Отдельно от плановых проходов держите разбор по событию. Ретроспектива сессии полезна сразу после неудачной работы, пока вы помните, что пошло не так. Через неделю разбирать уже нечего.
Структура
Схема показывает три способа запуска и то, куда приходит результат каждого.
Фоновые проходы работают без вас. При настройке задайте ожидаемый результат: PR с правками, описание модели или тикеты с подтверждёнными находками. После запуска проверьте результат; отсутствие находок тоже допустимо. Находки недельного ревью подсказывают область для сессии архитектуры. Ретроспектива запускается после неудачной сессии; локальные проходы обслуживают сам инструмент.
Участники / Компоненты
- Расписание запускает проходы с заданной частотой и хранит их промпты.
- Точка отсчёта задаёт диапазон: тег прошлого прогона или дата.
- Проход проверяет одну область на один вид дрейфа.
- Эталон описывает норму: стандарты кодирования, глоссарий, ADR, AGENTS.md.
- Результат оформляет находки как PR, описание модели или тикеты и отделяет подтверждённое поведение от предположений.
- Вы принимаете изменения, выбираете область для архитектуры и отвечаете на вопросы ретроспективы.
Когда применять
- Агенты пишут больше кода, чем команда успевает внимательно прочитать.
- В проекте есть эталон, с которым можно сверяться: стандарты, глоссарий, ADR.
- Над репозиторием работают несколько людей или несколько параллельных сессий.
- В проекте уже накопилось агентское окружение: инструкции, скилы, хуки, разрешения.
В маленьком проекте с одним разработчиком и редкими изменениями достаточно ретроспективы после неудачных сессий и ежемесячного прохода по инструкциям.
Последствия и компромиссы
- ➕ Дрейф исправляется мелкими шагами, пока он ещё локален.
- ➕ Инструкции и скилы остаются короткими и соответствуют реальной работе.
- ➕ Фоновые проходы не требуют вашего времени до момента ревью.
- ➖ Недельные PR тоже нужно читать; если они копятся, проходы теряют смысл.
- ➖ Фоновый агент ошибается так же, как любой другой, поэтому его PR проходят обычное ревью.
- ➖ Проходы стоят токенов и лимитов, особенно на больших диапазонах.
- ➖ Расписание устаревает вместе с проектом и само требует пересмотра.
Реализация
Недельные проходы по коду удобно поставить облачными задачами. Для исправлений задайте небольшой PR, для поиска скрытой модели — описание со ссылками на код и открытыми вопросами. Архитектуру, разбор спорных правил, ретроспективу и обслуживание агента проводите в интерактивной сессии. Указывайте период явно, например «за последнюю неделю»; для последовательного охвата можно сохранять проверенный коммит прошлого прогона. Выбирайте следующий диапазон после ревью результата и учитывайте уже открытые тикеты, чтобы не получать одни и те же предложения. Раз в месяц пересматривайте полезность проходов.
Проходы, которые не зависят от агента
Часть проходов использует скиллы Мэтта Покока, остальные задаются обычными промптами. Для скиллов установите пак одним из описанных в обзоре способов, затем один раз запустите /setup-matt-pocock-skills. В примерах ниже указаны имена процедур; способ их вызова зависит от выбранного агента. Встроенные команды разобраны в отдельных блоках после общего подхода.
Ретроспектива
Это скил retro из инженерной части пака (исходник). Модель не вызывает его сама, запускаете только вы.
Скил подгружает writing-for-agents как руководство по стилю и читает транскрипт сессии, по умолчанию текущей. Улучшения он ищет в семи категориях: навигация по проекту, автоматические проверки, стандарты для ревью, AGENTS.md, экономия вызовов, правила, которые ничего не меняют, и доступ к информации. Механическое нарушение он предлагает ловить линтером, хуком или CI, а в стандарты записывать только то, что требует суждения. Кандидатов показывает по убыванию важности и сам ничего не меняет.
Запускайте сразу после сессии, где агент буксовал: много исправлений, откат, долгий поиск, повторная ошибка. Принятые предложения реализуйте в этой же сессии.
Пример
/retro
Ревью стандартов
Это скил code-review из пака (исходник).
Скил берёт diff от точки отсчёта (git diff <точка>...HEAD) и находит документы со стандартами, например CODING_STANDARDS.md и CONTRIBUTING.md. Затем запускает два сабагента параллельно: один сверяет diff со стандартами проекта и с базовым списком запахов кода из «Рефакторинга» Фаулера, другой сверяет diff с исходной задачей. Для планового прохода нужна только первая часть. Нарушения делятся на жёсткие и спорные, у каждого есть ссылка на правило.
Запускайте раз в неделю облачной задачей, по отдельной задаче на каждую крупную область.
Пример
/code-review за последнюю неделю
Рефакторинг
Раз в неделю выбирайте активную область и один вид трудности: повторяющееся правило, неясные состояния, лишние абстракции или устаревшие ветки. Чередуйте области и учитывайте уже открытые тикеты. Подробные запросы, исследование модели и проверки до и после изменения разобраны в главе «Рефакторинг».
Ревью безопасности
Обычный промпт. Агент читает изменения за период и проверяет места, где ошибка стоит дороже всего: авторизацию, платежи, загрузку файлов и вызовы внешних API.
Запускайте раз в неделю облачной задачей по основной ветке.
Пример
Проверь на уязвимости изменения за последнюю неделю
Проверка глоссария
Это скил domain-modeling из пака (исходник).
Скил сверяет термины в коде и разговоре с GLOSSARY.md и указывает на противоречия: глоссарий называет понятие одним словом, а код другим, или код ведёт себя не так, как описано. Разрешённый термин он записывает в глоссарий сразу. GLOSSARY.md остаётся только словарём, без деталей реализации. Скил рассчитан на разговор с вами; в облачной задаче спросить некого, поэтому спорные термины уходят в описание PR.
Запускайте раз в неделю облачной задачей.
Пример
/domain-modeling за последнюю неделю
Архитектура
Раз в неделю проводите совместную сессию по одной области, выбранной по находкам недельных проходов. Если решение требует уточнить предметную область или сравнить интерфейсы, разбирайте его вместе с агентом. Применение improve-codebase-architecture и переход к тикетам описаны в «Рефакторинге».
Инструкции для агентов
Это скил writing-for-agents из пака (исходник).
Это справочник о том, как писать документы для агента. Он разбирает указатели на контекст, две нагрузки (на контекст агента и на внимание человека), порядок шагов и справки, критерии завершения и единый источник правды. С ним видны дубли между файлами, разросшиеся документы и запреты, которые тянут внимание к запрещённому сильнее, чем отводят от него.
Запускайте раз в месяц.
Пример
/writing-for-agents проверь доки
Свои скилы
Свои скилы проверяет тот же writing-for-agents, для скилов он дополнительно разбирает frontmatter и способ вызова. Описание скила должно называть случаи, в которых он нужен, а шаги должны заканчиваться проверяемым критерием.
Запускайте раз в месяц.
Пример
/writing-for-agents проверь скилы
ADR
ADR проверяет тот же domain-modeling. Скил читает docs/adr, сверяет решения с кодом и более поздними ADR и проставляет статусы и ссылки.
Запускайте раз в месяц.
Пример
/domain-modeling проверь ADR
Память агента
Отдельной команды нет, нужен обычный промпт. Агент читает свою память о проекте, переносит в репозиторий факты о коде и командах и оставляет в памяти только то, как работать с вами. Где лежит память и как она чистится сама, зависит от агента и описано в его блоке. Если вы выключили память в проекте, как советует глава «Приватная память», проход нужен один раз, перед выключением.
Запускайте раз в месяц, локально.
Пример
Почисти свою память по этому проекту
Claude Code
Блок сверен с Claude Code 2.1.316 и справочником команд на 2026-10-31. Обслуживание установки и памяти выполняется локально. /schedule запускает облачные задачи; у ревью также есть облачный режим /code-review ultra.
Расписание: /schedule
/schedule — встроенная команда, она же /routines (документация).
Команда создаёт облачную задачу в разговоре: уточняет расписание, репозиторий и запрос. Обычно запуск начинает работу от ветки по умолчанию; события PR и явные настройки могут менять исходную ветку. Результатом может быть отчёт, комментарий или PR. Если нужен PR, задайте это при настройке задачи и проверьте результат запуска. Для новых веток обычно используется префикс claude/; ход работы доступен в транскрипте на claude.ai.
Пример
/schedule каждый понедельник /code-review за последнюю неделю
Ревью: /code-review и /review
В Claude Code есть встроенный скил /code-review, который ищет ошибки корректности. Скил проекта с тем же именем, например code-review из пака Мэтта Покока, его заменяет, а встроенный остаётся доступен как /review (документация).
Пример
/review
Упрощение
Для регулярной задачи выбирайте отдельную активную область. Применение встроенного скила /simplify и проверка результата разобраны в «Рефакторинге»; здесь настройте расписание и проверьте, что результаты прохода успевают разобрать до следующего запуска.
Пример
/schedule каждый понедельник /simplify app/services
Безопасность: /security-review
/security-review — встроенная команда (справочник команд, исходник). Проверки устанавливаемого плагина Security Guidance — отдельный механизм.
Команда берёт diff текущей ветки с веткой по умолчанию в origin и ищет инъекции, ошибки авторизации и утечки данных. Диапазон коммитов она не принимает, поэтому её запускают на ветке перед слиянием, а недельный проход по основной ветке остаётся обычным промптом из общего блока.
Пример
/security-review
Память
Автопамять лежит в ~/.claude/projects/<проект>/memory, а /memory показывает записи и управляет её включением (документация). Это личные заметки инструмента. При ежемесячном проходе переносите подтверждённые командные правила в AGENTS.md через обычное ревью; не рассчитывайте, что фоновая обработка памяти сама обновит репозиторий.
Разрешения: /fewer-permission-prompts
/fewer-permission-prompts — встроенный скил.
Скил читает транскрипты сессий, собирает частые вызовы Bash и MCP только для чтения и предлагает список по приоритету. После вашего согласия дописывает их в общий список разрешений проекта, который коммитится вместе с кодом.
Запускайте раз в месяц.
Пример
/fewer-permission-prompts
Здоровье установки: /doctor
/doctor — встроенный скил.
Скил проверяет установку, версию, настройки, плагины, MCP-серверы и хуки. Предлагаемые изменения разрешений оценивайте отдельно от диагностики. Для проверки AGENTS.md используйте проход writing-for-agents: сверьте команды с текущим проектом, удалите дубли и подтвердите результат на реальных задачах.
Запускайте раз в месяц, после /fewer-permission-prompts.
Пример
/doctor
Скилы: /skill-doctor
/skill-doctor — встроенная команда, доступная с версии 2.1.252 (документация). Для отчёта требуется доступ к загрузке feature flags; через Remote Control команда недоступна.
Отчёт показывает стоимость в контексте и использование поддерживаемых скиллов; встроенные и корпоративные скиллы в него не входят. Claude Code загружает скиллы проекта, пользователя, плагинов и других поддерживаемых источников. При установке редактируемых файлов проверьте каталог .claude/skills/ или ссылки на общие файлы; при установке плагина проверяйте сам плагин.
Запускайте раз в месяц.
Пример
/skill-doctor
Запуск приложения: /run-skill-generator
/run-skill-generator — встроенный скил.
Скил пишет проектный скил, который учит /run и /verify собирать, запускать и проверять ваше приложение с чистого окружения. Если записанный скил перестал работать, /run сам предлагает его обновить. Claude правит файл, только когда запуск пошёл не так.
Запускайте раз в месяц и каждый раз, когда /run сообщает, что скил устарел.
Пример
/run-skill-generator
Codex
Блок сверен с Codex CLI 0.166.0 и документацией на learn.chatgpt.com на 2026-10-31.
Расписание: Scheduled tasks и codex-action
Scheduled tasks создают повторяемые задания в приложении и в веб-среде ChatGPT/Work, когда функция доступна (документация). openai/codex-action запускает Codex в GitHub Actions (документация, исходник).
Локальная задача работает в проекте или отдельном worktree; для неё компьютер и приложение должны быть включены. Веб-задача использует доступные ей файлы, скиллы, плагины и подключённые инструменты, но не получает прямого доступа к локальной папке. Задачи выполняются без вашего участия, поэтому заранее проверьте разрешения и песочницу. Action запускает codex exec по событиям GitHub, включая cron, и не зависит от вашей машины. Для создания PR нужен отдельный шаг.
Пример в приложении
В разделе Scheduled создайте задачу с расписанием и промптом:
$code-review за последнюю неделю
Пример в GitHub Actions
Попросите Codex завести workflow; файл попадёт в репозиторий через обычное ревью.
Заведи еженедельный GitHub Actions: codex-action прогоняет $code-review и открывает PR
Ревью: codex review и @codex review
codex review — встроенная команда CLI, /review делает то же в TUI (документация). Правила для ревью Codex берёт из раздела ## Code Review Rules в AGENTS.md, поэтому ссылку на стандарты проекта стоит держать там. Автоматическое ревью PR на GitHub (@codex review) смотрит один PR и сообщает только о серьёзных проблемах, поэтому недельный проход оно не заменяет.
Пример
codex review --base main
Проход по коду
Проверенный проход можно повторять по расписанию, чередуя области и сохраняя точку отсчёта после ревью. Обычный запрос на рефакторинг и оформление процедуры своим скилом описаны в «Рефакторинге».
В приложении создайте недельную задачу с таким запросом и проверьте первый результат перед регулярным запуском.
Пример
Каждый понедельник упрощай код оплаты, изменённый за последнюю неделю
Безопасность: @codex security review
Security Review требует доступа к функции, настроенного рабочего пространства и подключённого облачного репозитория (настройка). На дату проверки поддерживаются Enterprise, Business, Edu и Pro; на Plus функция недоступна. В настроенном репозитории комментарий @codex security review запускает проверку PR, полный отчёт появляется во вкладке Security Report задачи. Для более широких проверок есть Codex Security.
Пример
@codex security review
Память: Memories
Memories по умолчанию выключены (документация). Если вы их включили, записи лежат в ~/.codex/memories/ и генерируются из прошлых сессий. Документация не рекомендует править их руками, поэтому при ежемесячном проходе факты о проекте переносятся в AGENTS.md, а в командном проекте Memories лучше выключить, попросив об этом Codex (см. «Приватная память»).
Разрешения: правила .rules
Песочница ограничивает файловую систему и сеть, политика подтверждений определяет, когда нужно ваше согласие, а экспериментальные правила .rules решают, какие команды Codex выполняет за пределами песочницы сразу, с вопросом или никогда (правила, песочница). Из подходящих правил побеждает самое строгое.
Когда вы соглашаетесь навсегда разрешить префикс команды, Codex сохраняет правило в ваших личных правилах; разовое разрешение правила не создаёт. Раз в месяц просите Codex пересмотреть эти правила: общие перенести в правила репозитория, а лишние удалить.
Пример
Почисти мои правила для команд, общие перенеси в репозиторий
Здоровье установки: codex doctor
codex doctor — встроенная команда CLI (документация).
Команда проверяет установку, конфигурацию, авторизацию, окружение, Git и терминал. В TUI /debug-config показывает слои конфигурации, а /hooks показывает хуки и позволяет доверить или отключить их (документация).
Запускайте раз в месяц.
Пример
codex doctor
Размер AGENTS.md
Codex загружает инструкции до лимита, по умолчанию 32 KiB (документация).
Проверьте, сколько весят инструкции, применимые к рабочему каталогу, и не упираются ли они в лимит. При большом наборе файлов явно убедитесь, что нужные правила попали в контекст; не считайте наличие файла на диске доказательством загрузки. Совмещайте эту проверку с проходом writing-for-agents.
Пример
Посчитай, сколько весят все AGENTS.md вместе
Скилы
Codex читает .agents/skills/ напрямую и умеет отключать выбранные скиллы (документация).
Спросите Codex, какими скиллами вы не пользовались, и попросите отключить лишние. Оценка опирается на сохранённые сессии, но отсутствие записи не доказывает, что скилл не запускался: учитывайте срок хранения и источник истории.
Запускайте раз в месяц.
Пример
Какими скилами я не пользовался за последний месяц?
Запуск приложения
Скрипты подготовки и действия для запуска приложения настраивают в Local environments (документация). Раз в месяц запускайте подготовку в чистом worktree и проверяйте, что приложение поднимается с нуля.
Пример
В проекте за неделю приходит около двадцати тысяч строк, стандарты лежат в CODING_STANDARDS.md, код разложен по слоям в app/. Каждый понедельник облачная задача запускается с промптом:
/code-review за последнюю неделю
В этом учебном примере ревью находит два сервиса, которые ходят в базу мимо репозиториев. Вы принимаете небольшой PR после проверки. В оплате обнаруживается неясное правило, поэтому следующую сессию посвящаете его исследованию и рефакторингу.
Открытый вопрос о статусах остаётся в тикете. Следующий недельный проход учитывает его и ищет новые расхождения от сохранённого коммита. Через месяц вы видите, что отчёты по одному каталогу перестали давать полезные находки, и меняете область. Частоту проходов уменьшаете, если команда не успевает разбирать результаты.
Антипаттерны и частые ошибки
- Проход по всему репозиторию. Агент понемногу смотрит всё и находит только очевидное. Задавайте область.
- Один большой PR. Правки по всем областям в одном PR невозможно ревьюить, его откладывают, и следующий проход находит то же самое.
- Находки без разбора. Отчёты копятся, и следующие запуски повторяют их. Принятое описание модели — полезный результат; непрочитанный отчёт не помогает.
- Рефакторинг по обязанности. Агент создаёт правки ради еженедельного PR. Допускайте вывод, что менять нечего.
- Ретроспектива по памяти. Разбор сессий недельной давности опирается на то, что никто уже не помнит.
- Надежда на ревью каждого PR. Автоматическое ревью PR ловит ошибки в diff, но не отклонение, которое складывается из многих PR.
- Обслуживание инструмента вперемешку с проектом. Правки личных разрешений и памяти попадают в командный PR или, наоборот, командные правила остаются в личных настройках.
- Расписание без пересмотра. Проходы, которые давно ничего не находят, продолжают тратить лимиты, а PR от них перестают читать.
Известные применения
- OpenAI описывает в статье Harness engineering фоновые задачи Codex, которые с регулярной частотой ищут отклонения от «золотых принципов», обновляют оценки качества по доменам и слоям и открывают целевые PR с рефакторингом. Отдельный агент doc-gardening ищет устаревшую документацию. Раньше команда тратила на уборку каждую пятницу, и это не масштабировалось.
- Скиллы Мэтта Покока дают готовые проходы для регулярного запуска:
retro,code-review,domain-modeling,writing-for-agents,improve-codebase-architecture. - Claude Code содержит встроенные проверки окружения
/doctor,/skill-doctorи/fewer-permission-prompts, а/scheduleзапускает облачные задачи по расписанию. - Codex в документации к Scheduled tasks приводит пример задачи, которая просматривает прошлые сессии и улучшает скилы.
Связанные паттерны
- Рефакторинг объясняет исследование модели, выбор изменения и проверку сохранения поведения.
- Память проекта описывает файл инструкций, который ежемесячный проход держит коротким.
- Раздутая память показывает, во что превращаются инструкции без регулярной чистки.
- Словарь домена задаёт эталон для недельной проверки глоссария.
- Скиллы упаковывают проходы так, чтобы их можно было запускать по расписанию.
- Писатель и рецензент разделяет написание и ревью; плановое ревью стандартов работает на уровне недели, а не одного PR.
- Исполняемые ограничения получают новые проверки из ретроспектив и ограничивают фоновые задачи песочницей.
- Спроектируй дважды помогает сравнить представления выбранной модели.
- Петля обратной связи даёт проверку сохранения поведения при рефакторинге.
- Трассирующие тикеты превращают выбранное улучшение в проверяемые шаги; широкая смена интерфейса требует expand–contract.