← Блог

ИИ-агенты

Энтропия кода: как проверки в CI не дают ИИ плодить легаси

Сложность кода всегда росла сама собой, ИИ только ускорил этот рост. Ниже семь уровней проверок в CI, которые не дают копиться легаси, в том порядке, в каком я их добавляю.

Энтропия растёт сама собой. В физике это второе начало термодинамики. В разработке то же самое: беспорядок копится сам, а на порядок нужны усилия.

Так было всегда. Проект растёт, и вместе с ним растёт сложность: прибавляется легаси, поддерживать всё труднее, каждое изменение даётся тяжелее, а риск что-то сломать всё выше. В 1974 году Мэнни Леман сформулировал закон эволюции программ: сложность системы растёт, если её специально не снижать. ИИ здесь ничего не изменил, легаси просто стало копиться быстрее.

Поэтому код хочется держать как можно проще. С этим помогают проверки в CI.

  1. 1Мёртвый кодвалит сборку
  2. 2Линтеры и форматтерывалит сборку
  3. 3Статический анализвалит сборку
  4. 4Юнит-тесты и покрытиевалит сборку
  5. 5Сложность и дублированиевалит сборку
  6. 6Архитектура и зависимостивалит сборку
  7. 7Письменные правила (AGENTS.md)CI не проверяет
Внизу самые дешёвые проверки. Уровни 1–6 валят сборку при каждом нарушении. Письменные правила наверху подсказывают агенту, что делать, но остановить его не могут.

1. Мёртвый код

Проще всего удалить то, что больше не используется. Это тоже автоматизируется: добавьте в CI поиск мёртвого кода (vulture для Python, knip для JS/TS), и неиспользуемый код будет валить сборку.

2. Линтеры и форматтеры

Дальше линтер: phpcs для PHP, ruff для Python, ESLint и Prettier для JS/TS и так далее. У каждого языка свои стили кода, и какой вы выберете, неважно. Главное, чтобы никто не тратил время и деньги на вычитку кода и замечания в ревью вроде «поменяй двойные кавычки на одинарные». Договоритесь о стиле один раз, дальше его будет проверять CI.

3. Статический анализ

Следующий уровень — статические анализаторы: PHPStan для PHP, mypy для Python, tsc для JS/TS. Строгая статическая проверка типов ловит простые ошибки: строку передали туда, где ожидали число, или забыли, что значение может быть пустым. Логику она не проверит, но целый класс ошибок уберёт. С пустыми значениями история известная. Тони Хоар, который придумал нулевую ссылку, назвал её своей «ошибкой на миллиард долларов». А по данным Harness за 2020 год, NullPointerException всё ещё входил в десятку самых частых исключений в 70% продакшен-сред на Java, которые они изучили.

4. Юнит-тесты и 80% покрытия

Плохой код очень трудно покрыть юнит-тестами. Чтобы покрыть код тестами, его приходится делить на отдельные классы и функции, продумывать связи и интерфейсы. Надо решить, что будет публичным, а что приватным, внедрять зависимости и обходиться без глобального состояния. Гарантии это не даёт, тем более что ИИ легко раздувает покрытие тестами, которые почти ничего не проверяют. Но порог так или иначе задаёт рамки для дизайна, и хороший код получается чаще.

5. Сложность и дублирование

Рабочая память человека удерживает одновременно лишь несколько независимых элементов. Джордж Миллер в 1956 году насчитал 7 ± 2, Нельсон Коуэн в 2001-м уточнил: около четырёх. Остальное даётся с трудом и уходит в своп. Таких исследований для ИИ я не видел. Но чем понятнее код человеку, тем меньше шансов, что ИИ начнёт галлюцинировать. А если код настолько запутан, что человек в нём не разберётся, ИИ, скорее всего, нагромоздит сверху новые слои легаси.

Поэтому я ставлю жёсткие лимиты на сложность и дублирование. Лимит превышен → CI падает → приходится рефакторить и выносить код в отдельные методы и классы. Для Python, например, есть complexipy.

Пример с реального проекта. На платформе, над которой я работал, бэкенд в основном писали ИИ-агенты. Первый замер сделали через шесть недель, когда ни одной из этих проверок ещё не было. Он показал 143 функции со сложностью выше 10 и 202 скопированных фрагмента, около 5% кода. Позже, когда ввели жёсткий потолок, самой сложной оказалась функция, которая обрабатывала чеки, то есть работала с деньгами: 490 строк, сложность 73. Когда потолок начал валить сборку, её разобрали за четыре дня рефакторинга, по одной функции на коммит, и сложность упала с 73 до 30. За два месяца после первого замера дублирование снизилось примерно до 3%.

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

6. Архитектура и зависимости

Жёсткие границы тоже снижают сложность, только уровнем выше. Это как инкапсуляция в ООП: система собрана из крупных блоков, и держать в голове их устройство не нужно, хватает контракта. А реализацию блока при необходимости можно заменить, не переписывая остальную систему. Вместо десятков классов и связей вы думаете о нескольких крупных блоках. Того, что надо держать в голове одновременно, снова становится меньше, теперь на каждом уровне архитектуры.

На практике это Clean Architecture и гексагональная архитектура: код разделён на слои, а зависимости между ними строго ограничены. Домен ничего не знает о базе данных, HTTP и внешних API, а внешний код обращается к нему через заранее описанные интерфейсы. Это тоже проверяется автоматически, например import-linter для Python: появился запрещённый импорт, CI упал.

7. Письменные правила

Последний уровень — письменные правила. Раньше это были гайдлайны и документация для разработчиков, теперь — файл AGENTS.md и документация для ИИ. Здесь, в отличие от проверок, результат не гарантирован: ИИ может прочитать правило и всё равно его нарушить. Поэтому в письменные правила попадает только то, что не удалось покрыть проверками. При прочих равных лучше написать жёсткую проверку в коде, чем абзац текста.

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

Инструменты по языкам

Что я использую на каждом уровне. Сами инструменты не так важны, главное — чтобы каждый уровень валил сборку.
УровеньPythonPHPJS/TS
Мёртвый кодvultureshipmonk/dead-code-detector (PHPStan)knip
Линтеры и форматтерыruffPHP_CodeSniffer (phpcs)ESLint + Prettier
Статический анализmypy (strict)PHPStantsc (strict)
Юнит-тесты и покрытиеpytest + coveragePHPUnitJest / Vitest
СложностьcomplexipyPHPMD, cognitive-complexity (PHPStan)ESLint complexity
Дублированиеpylint duplicate-codejscpdjscpd
Архитектура и зависимостиimport-linterDeptracdependency-cruiser

У этой статьи есть пошаговая версия для ИИ-агентов: плейбук по автопроверкам в CI (на английском). Чтобы применить его к репозиторию, скажите агенту: Примени https://sg4.tech/blog/code-entropy-ci-checks-ai-legacy/playbook.md к этому репозиторию.

Итог

Энтропия будет расти в любом случае. Вопрос в том, кто её сдерживает. Чем больше правил переезжает из гайдлайнов в проверки CI, тем меньше всё зависит от того, насколько внимателен человек на ревью. ИИ сам запускает проверки, видит, что упало, и исправляет: строчку в AGENTS.md он пропустить может, а упавший CI — нет. И чем больше таких проверок, тем спокойнее можно отдавать ему код.

Если вы основатель и код не читаете, список всё равно пригодится: спросите команду, какие из этих уровней на деле валят сборку. Каждое «мы это ловим на ревью» — правило, которое держится на том, внимателен ли кто-то в этот день. Зачем коду от агентов такие автопроверки, я разбирал отдельно: управляйте ИИ как джуном.

Шаблон для Python

Подход не зависит от языка. Для Python я собрал всё это в готовый шаблон, пользуйтесь: python-guardrails-template.

Внутри:

  • все проверки из статьи запускаются одной командой make verify в Docker, та же команда работает в GitHub Actions;
  • архитектурные слои с проверкой импортов;
  • сканер секретов при коммите;
  • AGENTS.md, где почти каждое правило ссылается на проверку, которая за ним следит;
  • небольшой пример, чтобы проверки проходили сразу после создания проекта.

Новый проект создаётся одной командой:

copier copy gh:sg4tech/python-guardrails-template my-project

Когда шаблон обновляется, copier update добавляет новые проверки в уже созданные проекты и не трогает ваши изменения. Настраивать всё с нуля в каждом проекте больше не придётся.

Частые вопросы

Не замедлят ли строгие проверки в CI работу команды?

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

Можно ли добавить эти проверки в существующий легаси-проект?

Да. Зафиксируйте текущий уровень как лимит, чтобы хуже не становилось, и снижайте его шаг за шагом по мере рефакторинга.

Разве для этого не хватит код-ревью?

Ревью держится на внимательности и не успевает за тем, как быстро агенты пишут код. Проверка запускается на каждом изменении и падает всегда одинаково.

Нужно ли вводить все семь уровней сразу?

Нет. Добавляйте по порядку: сначала дешёвые — мёртвый код, форматирование и типы. Лимиты на сложность и архитектуру окупаются, когда кода становится много.