Энтропия и сборка мусора в коде

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

Что говорит источник

В статье OpenAI Harness engineering этой теме посвящён отдельный раздел. Codex воспроизводит существующие в репозитории шаблоны, включая неудачные, и отсюда дрейф. Сначала команда убирала последствия вручную: каждую пятницу, то есть 20% рабочей недели, уходило на чистку того, что авторы называют «AI slop». Это не масштабировалось.

Решение из двух частей:

• Золотые принципы, закодированные в репозитории. Примеры из статьи: общие утилитные пакеты лучше самописных хелперов, чтобы инварианты жили в одном месте; никаких «прощупываний» данных наугад — проверять границы или опираться на типизированные SDK.
• Регулярная сборка мусора. Фоновые задачи Codex ищут отклонения от принципов, обновляют оценки качества и открывают точечные рефакторинговые PR. По словам авторов, большинство из них ревьюится меньше чем за минуту и мержится автоматически.

Технический долг авторы сравнивают с кредитом под высокий процент: гасить лучше постоянно и понемногу. Отдельно в статье упомянут агент doc-gardening — он периодически ищет документы, расходящиеся с реальным поведением кода, и открывает PR с исправлениями.

Что такое энтропия в агентном проекте

Полезно назвать конкретные виды дрейфа — для каждого нужен свой детектор.

Биргитта Бёкелер в статье о harness engineering относит такие проверки к непрерывным датчикам — они живут вне жизненного цикла отдельного изменения и ловят постепенный дрейф: мёртвый код, качество покрытия, зависимости.

Золотые принципы

Принципы — это то, что отличает ваш проект от просто работающего кода. Они короче и стабильнее, чем codestyle, и каждый из них должен быть проверяем — человеком, агентом или скриптом.

# Золотые принципы

1. Одна утилита на задачу. Перед новым хелпером ищем существующий
   в classes/Helpers и src/themes/amiga/resources/js/utils.
2. Данные из внешних систем (CRM, формы, API) валидируются на входе
   в сервис. Компоненты получают уже проверенные структуры.
3. Страница не содержит больших inline-стилей и скриптов: только бандлы
   resources/scss/pages и resources/js/pages.
4. Миграция контента ставит updated_at — от этого зависит sitemap.
5. Каждый Playwright-тест опирается на data-testid, а не на тексты и классы.

Нарушение принципа — повод для отдельного маленького MR, а не для
правки «заодно» в чужой задаче.

Ссылка на этот файл — в AGENTS.md, рядом с картой документации; как устроить такую карту, разобрано в уроке AGENTS.md как оглавление. Те принципы, что проверяются механически, со временем переезжают в линтеры и структурные тесты — см. урок об инвариантах.

Сборщик мусора: устройство

У фоновой уборки три звена.

Детектор находит кандидатов. Лучше детерминированный: дешевле, воспроизводимее и не шумит. Агент нужен там, где правило смысловое — «два способа работать с формами».

Исполнитель — агент, который берёт одну находку и делает один маленький MR. Именно размер делает возможным ревью за минуту. Уборка, которая приходит одним MR на сорок файлов, никогда не будет принята быстро.

Политика мержа определяет, что можно принять автоматически, а что требует человека.

Запускать можно двумя путями. Scheduled tasks в Codex работают в ChatGPT desktop app и на web — в desktop компьютер и приложение должны быть включены, а CLI и IDE ими не управляют (урок о задачах по расписанию). Для команды, где всё живёт в GitLab, естественнее запланированный пайплайн с codex exec:

gc_detect:
  stage: test
  image: node:22-bookworm
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule" && $GC_TASK'
  script:
    - npx jscpd src/themes/amiga/resources/js --min-lines 8 --reporters json --output reports/ || true
  artifacts:
    paths: [reports/]
    expire_in: 7 days

garbage_collection:
  stage: test
  image: node:22-bookworm
  needs: [gc_detect]
  environment: agent-gc
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule" && $GC_TASK'
  script:
    - npm install -g "@openai/codex@${CODEX_VERSION}"
    - >
      codex exec --sandbox workspace-write --ephemeral
      -c shell_environment_policy.ignore_default_excludes=false
      -o reports/gc-summary.md
      "Прочитай docs/golden-principles.md и reports/jscpd-report.json.
      Выбери ОДНО самое заметное дублирование, устрани его, прогони
      npm run build и тесты. Не трогай файлы вне найденного дубля.
      В reports/gc-summary.md опиши изменение в трёх строках."
    - git diff --stat
  artifacts:
    paths: [reports/]
    expire_in: 7 days

codex exec в CI авторизуется переменной CODEX_API_KEY. Заведите её как masked и protected с областью видимости окружения agent-gc: тогда её видит только задание с Codex, а не детектор, который исполняет сторонний пакет из npm. Ключ -c shell_environment_policy.ignore_default_excludes=false убирает переменные с KEY, SECRET и TOKEN в имени из окружения команд, которые запускает агент, — по умолчанию Codex их сохраняет. Версию CLI закрепите переменной CODEX_VERSION вместо последней. Шаг создания MR из получившегося диффа зависит от вашей настройки GitLab — через API с отдельным токеном с минимальными правами. Как хранить ключи и почему задание, исполняющее код репозитория, не должно видеть лишних секретов, разобрано в уроке о безопасности автоматизации.

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

Уход за документацией

Документация — первое, что гниёт, и самое опасное для агента: устаревший документ он воспримет как истину. Doc-gardening по образцу OpenAI можно устроить так же, как уборку кода: агент берёт один документ из docs/, сверяет утверждения с кодом (существует ли команда, файл, ключ конфига) и предлагает MR с исправлениями или пометкой «устарело». Детерминированная часть — проверка, что все ссылки на файлы и якоря в docs/ живы, — запускается в обычном CI. Подробнее о документации как системе записи — в уроке о системе записи.

Оценка качества во времени

В эксперименте OpenAI есть документ качества, который ставит оценку каждому домену и архитектурному слою и отслеживает пробелы во времени, а фоновые задачи его обновляют. Это превращает уборку из реакции в управление: видно, какой модуль деградирует, и туда направляется следующая уборка. Для сайта агентства это может быть простая таблица по плагинам и разделам темы: покрытие тестами, число нарушений принципов, размер baseline, дата последней уборки.

Где проходят границы

Автомерж. У OpenAI большинство уборочных PR мержится автоматически — но это внутренний продукт команды, которая строила среду под агентов с первого коммита. Для клиентского проекта с продакшеном и договорной ответственностью наш вывод осторожнее: автоматически можно принимать только классы изменений с нулевым риском для поведения — документация, форматирование, удаление явно мёртвого кода при зелёных тестах. Всё остальное идёт обычным MR в main с ревью, просто очень маленьким и быстрым.

Шум. Если уборочные MR отклоняются чаще, чем принимаются, детектор слишком чувствителен или принцип сформулирован плохо. Метрика простая — доля принятых без правок.

Вкус против корректности. Уборка не должна превращаться в бесконечную переделку под меняющиеся предпочтения. Принцип попадает в список, только если команда готова защищать его годами.