Amiga
Оглавление курса · урок 18 из 24

Модуль 4 · Масштаб · урок 18 из 24

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

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

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

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

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

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

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

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

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

Вид дрейфа Как выглядит Чем обнаружить
Дубли третий хелпер форматирования телефона jscpd, phpcpd, поиск по сигнатурам
Расхождение шаблонов два способа работать с формами в компонентах структурные тесты, ревью агентом по принципам
Мёртвый код компоненты, которые не подключены ни на одной странице knip для JS, поиск неиспользуемых компонентов по pages/
Устаревшая документация в docs/ описана удалённая команда doc-gardening: агент сверяет документ с кодом
Устаревшие правила в AGENTS.md правило про библиотеку, которой больше нет тот же агент плюс проверка ссылок
Дрейф зависимостей composer outdated, уязвимые пакеты штатные команды менеджеров пакетов
Деградация тестов всё длиннее список пропущенных и нестабильных тестов отчёт CI по skipped и retried

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

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

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

markdown · docs/golden-principles.md
# Золотые принципы

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 и в веб-версии. Для desktop компьютер и приложение должны быть включены, а из CLI и IDE этими задачами управлять нельзя (см. урок о задачах по расписанию). Если у команды всё живёт в GitLab, удобнее запланированный пайплайн с codex exec:

yaml · .gitlab-ci.yml
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 отклоняют чаще, чем принимают, значит детектор слишком чувствительный или принцип плохо сформулирован. Метрика здесь простая: доля MR, принятых без правок.

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

Попробуйте сами

10–15 мин на рабочем месте
  1. Запишите пять золотых принципов своего проекта: те, которые агент нарушает в коде чаще всего. Добавьте ссылку на них в AGENTS.md.
  2. Запустите один детектор (jscpd, knip, composer outdated) и попросите Codex: «Возьми одну находку, исправь её одним минимальным изменением, прогони тесты, опиши изменение в трёх строках». Повторите пять раз и посчитайте, сколько результатов вы бы приняли.
  3. Попросите агента сверить с кодом один документ из docs/ и перечислить утверждения, которые больше не соответствуют действительности.

Коротко

  • Агент размножает шаблоны, которые уже есть в проекте, поэтому агентный код дрейфует быстрее.
  • Авральные уборки вручную не масштабируются, нужна постоянная фоновая сборка мусора.
  • Золотые принципы хранятся в репозитории и со временем переезжают в проверки.
  • Одна находка даёт один маленький MR, и только тогда ревью занимает минуту.
  • Автомерж годится только для изменений, которые не могут задеть поведение. Сначала задача должна надёжно работать вручную, потом её ставят на расписание.
Отметка хранится только в вашем браузере
Хотите связаться с владельцем
компании напрямую?
Дмитрий Тарасов
Дмитрий Тарасов
СЕО

НАПИСАТЬ

Написать в MAX