Плановое обслуживание

Назначение

Регулярно запускать агента на проходы, которые ищут дрейф кода, документации и агентского окружения, и возвращать результат небольшими PR или тикетами. Каждый проход имеет свою частоту, свою область и свой способ запуска: в облаке, локально или вместе с вами.

Также известен как

Garbage collection, doc gardening, maintenance routines, регулярные задачи, санитарные проходы.

Проблема

Агенты пишут десятки тысяч строк в неделю. Ревью каждого PR проверяет только его diff. Если три PR по отдельности нарушают стандарт чуть-чуть и в разных местах, ни одно ревью этого не заметит, а через месяц отклонение станет новой нормой, которую агент копирует дальше.

Вместе с кодом устаревает всё, что помогает агенту работать. Глоссарий не знает о новых моделях, в AGENTS.md копятся правила, которые уже ничего не меняют, скил запуска приложения ссылается на удалённый скрипт, allowlist разрешений разрастается, а в личной памяти агента оседают факты о проекте, которых нет в репозитории. Каждая такая мелочь стоит агенту лишних вызовов и ошибок в каждой следующей сессии.

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

Решение

Когда кода от агентов много, дрейфует всё сразу: архитектура, границы слоёв, глоссарий, соблюдение стандартов, инструкции для самих агентов. Поэтому проверки не ждут повода, а выполняются регулярно. Всё, что идёт следом за кодом, смотрится раз в неделю: ревью стандартов, упрощение, безопасность, глоссарий, архитектура. Инструкции, скилы, ADR и настройки агента меняются медленнее, их достаточно проверять раз в месяц.

Каждый проход смотрит на конкретный участок: изменения за неделю, каталог, слой или доменное понятие. Проход по всему репозиторию сразу даёт поверхностный отчёт.

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

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

Структура

Схема показывает три способа запуска и то, куда приходит результат каждого.

Фоновые проходы работают без вас и приходят готовыми PR. Находки недельного ревью подсказывают, какую область взять на сессию архитектуры. Ретроспектива запускается не по расписанию, а по неудачной сессии. Локальные проходы обслуживают сам инструмент и в проект попадают редко.

Участники / Компоненты

• Расписание запускает проходы с заданной частотой и хранит их промпты.
• Точка отсчёта задаёт диапазон: тег прошлого прогона или дата.
• Проход проверяет одну область на один вид дрейфа.
• Эталон описывает норму: стандарты кодирования, глоссарий, ADR, AGENTS.md.
• Результат оформляет находки как PR или тикеты.
• Вы принимаете изменения, выбираете область для архитектуры и отвечаете на вопросы ретроспективы.

Когда применять

• Агенты пишут больше кода, чем команда успевает внимательно прочитать.
• В проекте есть эталон, с которым можно сверяться: стандарты, глоссарий, ADR.
• Над репозиторием работают несколько людей или несколько параллельных сессий.
• В проекте уже накопилось агентское окружение: инструкции, скилы, хуки, разрешения.

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

Последствия и компромиссы

• ➕ Дрейф исправляется мелкими шагами, пока он ещё локален.
• ➕ Инструкции и скилы остаются короткими и соответствуют реальной работе.
• ➕ Фоновые проходы не требуют вашего времени до момента ревью.
• ➖ Недельные PR тоже нужно читать; если они копятся, проходы теряют смысл.
• ➖ Фоновый агент ошибается так же, как любой другой, поэтому его PR проходят обычное ревью.
• ➖ Проходы стоят токенов и лимитов, особенно на больших диапазонах.
• ➖ Расписание устаревает вместе с проектом и само требует пересмотра.

Реализация

Недельные проходы по коду удобно поставить облачными задачами: они сами приходят готовыми PR. Архитектура, ретроспектива и обслуживание агента запускаются вручную. Фоновая задача не помнит прошлый запуск, поэтому период указывайте прямо в промпте, например «за последнюю неделю». Если изменений слишком много для одного прохода, запускайте его по каталогам. Раз в месяц посмотрите, какие проходы давно ничего не находят, а какие дают PR, которые никто не читает.

Проходы, которые не зависят от агента

Большая часть этих проходов — скиллы Мэтта Покока, и пак нужно установить заранее: npx skills@latest add mattpocock/skills, затем один раз /setup-matt-pocock-skills. Установщик кладёт скилы в .agents/skills, откуда их читает Codex; Claude Code читает только .claude/skills, поэтому там должны быть ссылки на них. В примерах скилы вызываются как в Claude Code, через /имя; в Codex тот же вызов пишется как $имя. Встроенные команды агентов описаны в следующих блоках.

Ретроспектива

Это скил retro из раздела in-progress пака (исходник). Модель не вызывает его сама, запускаете только вы.

Скил подгружает writing-for-agents как руководство по стилю и читает транскрипт сессии, по умолчанию текущей. Улучшения он ищет в семи категориях: навигация по проекту, автоматические проверки, стандарты для ревью, AGENTS.md, экономия вызовов, правила, которые ничего не меняют, и доступ к информации. Механическое нарушение он предлагает ловить линтером, хуком или CI, а в стандарты записывать только то, что требует суждения. Кандидатов показывает по убыванию важности и сам ничего не меняет.

Запускайте сразу после сессии, где агент буксовал: много исправлений, откат, долгий поиск, повторная ошибка. Принятые предложения реализуйте в этой же сессии.

Пример

/retro

Ревью стандартов

Это скил code-review из пака (исходник).

Скил берёт diff от точки отсчёта (git diff <точка>...HEAD) и находит документы со стандартами, например CODING_STANDARDS.md и CONTRIBUTING.md. Затем запускает два сабагента параллельно: один сверяет diff со стандартами проекта и с базовым списком запахов кода из «Рефакторинга» Фаулера, другой сверяет diff с исходной задачей. Для планового прохода нужна только первая часть. Нарушения делятся на жёсткие и спорные, у каждого есть ссылка на правило.

Запускайте раз в неделю облачной задачей, по отдельной задаче на каждую крупную область.

Пример

/code-review за последнюю неделю

Упрощение

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

Запускайте раз в неделю по 3–5 каталогам с наибольшим числом изменений. Каталоги облачная задача находит сама по git log --since="7 days ago" --stat.

Пример

Упрости код, который поменялся за последнюю неделю

Ревью безопасности

Обычный промпт. Агент читает изменения за период и проверяет места, где ошибка стоит дороже всего: авторизацию, платежи, загрузку файлов и вызовы внешних API.

Запускайте раз в неделю облачной задачей по основной ветке.

Пример

Проверь на уязвимости изменения за последнюю неделю

Проверка глоссария

Это скил domain-modeling из пака (исходник).

Скил сверяет термины в коде и разговоре с CONTEXT.md и указывает на противоречия: глоссарий называет понятие одним словом, а код другим, или код ведёт себя не так, как описано. Разрешённый термин он записывает в глоссарий сразу. CONTEXT.md остаётся только словарём, без деталей реализации. Скил рассчитан на разговор с вами; в облачной задаче спросить некого, поэтому спорные термины уходят в описание PR.

Запускайте раз в неделю облачной задачей.

Пример

/domain-modeling за последнюю неделю

Архитектура

Это скил improve-codebase-architecture из пака (исходник). Он сам подгружает codebase-design и grilling. План превращается в тикеты скилом to-tickets (исходник).

Скил берёт из codebase-design словарь: модуль, интерфейс, глубина, шов, адаптер. Затем читает CONTEXT.md и ADR выбранной области, и сабагент обходит код в поисках трения: чтобы понять одно понятие, приходится прыгать по многим мелким модулям; интерфейс почти так же сложен, как реализация; модули протекают друг в друга через швы. Подозрительные модули проверяются тестом удаления: если удалить модуль, сложность соберётся в одном месте или просто переедет? Кандидатов скил показывает HTML-отчётом во временной папке. По выбранному проводит grilling и при желании сравнивает варианты интерфейса через design-it-twice. to-tickets режет план на вертикальные срезы с блокирующими связями и публикует их в трекер.

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

Пример

/improve-codebase-architecture app/services

После разбора выбранного места запустите /to-tickets.

Инструкции для агентов

Это скил 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.283 и справочником команд на 2026-09-26. Названия команд меняются быстрее, чем сам подход. Всё, кроме /schedule, запускается локально: этим командам нужны ваши транскрипты, настройки или поднятое окружение.

Расписание: /schedule

/schedule — встроенная команда, она же /routines (документация).

Команда в разговоре создаёт облачную задачу: спрашивает расписание, репозиторий и промпт. Каждый запуск клонирует репозиторий с веткой по умолчанию и может пользоваться подключёнными коннекторами. Результат задача отдаёт как PR из ветки с префиксом claude/, ход запуска виден в транскрипте на claude.ai.

Пример

/schedule каждый понедельник /code-review за последнюю неделю

Ревью: /code-review и /review

В Claude Code есть встроенный скил /code-review, который ищет ошибки корректности. Скил проекта с тем же именем, например code-review из пака Мэтта Покока, его заменяет, а встроенный остаётся доступен как /review (документация).

Пример

/review

Упрощение: /simplify

/simplify — встроенный скил (документация).

Четыре сабагента параллельно смотрят изменённый код: переиспользование существующих хелперов, упрощение, эффективность и уровень абстракции. Найденное сразу исправляется. Ошибки корректности /simplify не ищет. Аргументом можно передать путь или PR, поэтому в недельной задаче его запускают по каждому каталогу.

Пример

/simplify app/services

Безопасность: /security-review

/security-review — встроенная команда (документация, исходник).

Команда берёт diff текущей ветки с веткой по умолчанию в origin и ищет инъекции, ошибки авторизации и утечки данных. Диапазон коммитов она не принимает, поэтому её запускают на ветке перед слиянием, а недельный проход по основной ветке остаётся обычным промптом из общего блока.

Пример

/security-review

Память

Автопамять лежит в ~/.claude/projects/<проект>/memory, а /memory показывает записи и включает или выключает её (документация). Фоновая консолидация (настройка autoDreamEnabled) удаляет устаревшие записи и помечает противоречия с CLAUDE.md, но факты о проекте в репозиторий не переносит, поэтому ежемесячный проход из общего блока всё равно нужен.

Разрешения: /fewer-permission-prompts

/fewer-permission-prompts — встроенный скил.

Скил читает транскрипты сессий, собирает частые вызовы Bash и MCP только для чтения и предлагает список по приоритету. После вашего согласия дописывает правила в permissions.allow общего .claude/settings.json.

Запускайте раз в месяц.

Пример

/fewer-permission-prompts

Здоровье установки: /doctor

/doctor — встроенный скил.

Скил проверяет установку (дубли, PATH, повреждённые файлы настроек) и версию. Он находит неиспользуемые скилы, MCP-серверы и плагины с их стоимостью в контексте и отмечает медленные хуки. Файлы CLAUDE.md он чистит от дублей и от того, что можно узнать из кода. Часто отклоняемые команды только для чтения добавляет в личный .claude/settings.local.json. AGENTS.md в его проверках нет, поэтому инструкции сокращает проход writing-for-agents.

Запускайте раз в месяц, после /fewer-permission-prompts.

Пример

/doctor

Скилы: /skill-doctor

/skill-doctor — встроенная команда, работает с версии 2.1.252.

Команда показывает для каждого скила, сколько он стоит в контексте и как часто используется, чтобы было видно, что отключить. Скилы, которых нет в .claude/skills, Claude Code не видит вовсе, поэтому заодно проверьте, что ссылки на .agents/skills на месте.

Запускайте раз в месяц.

Пример

/skill-doctor

Запуск приложения: /run-skill-generator

/run-skill-generator — встроенный скил.

Скил пишет проектный скил, который учит /run и /verify собирать, запускать и проверять ваше приложение с чистого окружения. Если записанный скил перестал работать, /run сам предлагает его обновить. Claude правит файл, только когда запуск пошёл не так.

Запускайте раз в месяц и каждый раз, когда /run сообщает, что скил устарел.

Пример

/run-skill-generator

Codex

Сверено с Codex CLI 0.156.1 и документацией на learn.chatgpt.com на 2026-09-26.

Расписание: Scheduled tasks и codex-action

Scheduled tasks — функция приложения Codex (документация). openai/codex-action — GitHub Action, который запускает Codex в CI (документация, исходник).

Задача в приложении запускается в локальном проекте или в отдельном worktree по расписанию и работает без подтверждений (approval_policy = "never") в вашей песочнице по умолчанию. Результат приходит в раздел Scheduled, который работает как входящие. Компьютер и приложение при этом должны быть включены. Action запускает codex exec на любом триггере GitHub, включая cron, и не зависит от вашей машины. PR он сам не открывает, для этого нужен отдельный шаг. Перед тем как ставить проход на расписание, убедитесь, что песочница не даёт ему выйти за пределы репозитория.

Пример в приложении

В разделе Scheduled создайте задачу с расписанием и промптом:

$code-review за последнюю неделю

Пример в GitHub Actions

on:
  schedule:
    - cron: "0 6 * * 1"
jobs:
  standards:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/prompts/weekly-standards.md
      - uses: peter-evans/create-pull-request@v7
        with:
          branch: maintenance/weekly-standards
          title: "refactor: weekly standards pass"

Ревью: 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

Упоминание @codex security review в комментарии к PR запускает Security Review, полный отчёт появляется во вкладке Security Report задачи. Для более широких проверок есть отдельный плагин Codex Security (документация).

Пример

@codex security review

Память: Memories

Memories по умолчанию выключены (документация). Если вы их включили, записи лежат в ~/.codex/memories/ и генерируются из прошлых сессий. Документация не рекомендует править их руками, поэтому при ежемесячном проходе факты о проекте переносятся в AGENTS.md, а генерацию при необходимости отключают через memories.generate_memories.

Разрешения: правила .rules

Разрешения в Codex задаёт механизм правил выполнения команд, он помечен как экспериментальный (документация).

Правила пишутся как prefix_rule(pattern=[...], decision="allow" | "prompt" | "forbidden") в файлах .rules рядом с каждым слоем конфигурации: ~/.codex/rules/ и .codex/rules/ в доверенном проекте. Из подходящих правил побеждает самое строгое. Каждое «разрешить» в TUI дописывает правило в ~/.codex/rules/default.rules, а команды для просмотра и чистки нет.

Раз в месяц просматривайте файл руками, общие правила переносите в .codex/rules/ репозитория, лишние удаляйте.

Пример

Проверить, как правила решат конкретную команду:

codex execpolicy check --pretty --rules ~/.codex/rules/default.rules -- git push origin main

Здоровье установки: codex doctor

codex doctor — встроенная команда CLI (документация).

Команда проверяет установку, конфигурацию, авторизацию, окружение, Git и терминал. В TUI /debug-config показывает слои конфигурации, а /hooks показывает хуки и позволяет доверить или отключить их (документация).

Запускайте раз в месяц.

Пример

codex doctor

Размер AGENTS.md

Размер инструкций ограничивает настройка project_doc_max_bytes, по умолчанию 32 KiB (документация).

Codex собирает AGENTS.md от корня проекта до рабочего каталога и прекращает загрузку, когда суммарный размер доходит до лимита. Предупреждения нет: правила из последних файлов просто не попадают в контекст. Проверяйте это раз в месяц вместе с проходом writing-for-agents.

Пример

Посчитай, сколько весят все AGENTS.md вместе

Скилы

Скилами в Codex управляет настройка [[skills.config]] в config.toml (документация). Аналога /skill-doctor нет.

Codex читает .agents/skills напрямую, симлинки не нужны. Неиспользуемый скил отключают записью [[skills.config]] с enabled = false. Как часто скил срабатывает, можно оценить по сессиям в ~/.codex/sessions.

Запускайте раз в месяц.

Пример

Какими скилами я не пользовался за последний месяц?

Запуск приложения

Запуск приложения в Codex описывают в Local environments приложения (документация). Генератора скила запуска нет. Раз в месяц проверяйте, что скрипты по-прежнему поднимают приложение с нуля.

Пример

В проекте за неделю приходит около двадцати тысяч строк, стандарты лежат в CODING_STANDARDS.md, код разложен по слоям в app/. Каждый понедельник облачная задача запускается с промптом:

/code-review за последнюю неделю

В понедельник приходят три PR: в app/services два сервиса снова ходят в базу мимо репозиториев, в app/policies появилась проверка роли через строку вместо перечисления, в app/javascript/pages дублируется форматирование дат. Первые два PR вы принимаете после короткого ревью. Третий показывает, что правило про форматирование дат можно проверить линтером, и вы заводите тикет на правило вместо строчки в стандартах.

На сессию архитектуры в эту неделю вы берёте app/services: там больше всего находок второй месяц подряд. Отчёт показывает, что сервисы тонкие и почти целиком пересказывают репозитории; выбранное место прорабатывается до плана и уходит тикетами.

Антипаттерны и частые ошибки

• Проход по всему репозиторию. Агент понемногу смотрит всё и находит только очевидное. Задавайте область.
• Один большой PR. Правки по всем областям в одном PR невозможно ревьюить, его откладывают, и следующий проход находит то же самое.
• Отчёт вместо изменения. HTML-отчёты копятся во временной папке, и ничего не меняется.
• Ретроспектива по памяти. Разбор сессий недельной давности опирается на то, что никто уже не помнит.
• Надежда на ревью каждого 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.
• Исполняемые ограничения получают новые проверки из ретроспектив и ограничивают фоновые задачи песочницей.