ИИ-агенты
Энтропия кода: как проверки в CI не дают ИИ плодить легаси
Сложность кода всегда росла сама собой, ИИ только ускорил этот рост. Ниже семь уровней проверок в CI, которые не дают копиться легаси, в том порядке, в каком я их добавляю.
Энтропия растёт сама собой. В физике это второе начало термодинамики. В разработке то же самое: беспорядок копится сам, а на порядок нужны усилия.
Так было всегда. Проект растёт, и вместе с ним растёт сложность: прибавляется легаси, поддерживать всё труднее, каждое изменение даётся тяжелее, а риск что-то сломать всё выше. В 1974 году Мэнни Леман сформулировал закон эволюции программ: сложность системы растёт, если её специально не снижать. ИИ здесь ничего не изменил, легаси просто стало копиться быстрее.
Поэтому код хочется держать как можно проще. С этим помогают проверки в CI.
- 1Мёртвый кодвалит сборку
- 2Линтеры и форматтерывалит сборку
- 3Статический анализвалит сборку
- 4Юнит-тесты и покрытиевалит сборку
- 5Сложность и дублированиевалит сборку
- 6Архитектура и зависимостивалит сборку
- 7Письменные правила (AGENTS.md)CI не проверяет
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 и документация для ИИ. Здесь, в отличие от проверок, результат не гарантирован: ИИ может прочитать правило и всё равно его нарушить. Поэтому в письменные правила попадает только то, что не удалось покрыть проверками. При прочих равных лучше написать жёсткую проверку в коде, чем абзац текста.
ИИ то и дело пытается отключить проверку вместо того, чтобы исправить код: поднять лимит, добавить исключение, заглушить правило комментарием. Поэтому в моём файле с правилами есть отдельная строка: ослабить проверку, чтобы она прошла, — это обход, исправлять надо код.
Инструменты по языкам
| Уровень | Python | PHP | JS/TS |
|---|---|---|---|
| Мёртвый код | vulture | shipmonk/dead-code-detector (PHPStan) | knip |
| Линтеры и форматтеры | ruff | PHP_CodeSniffer (phpcs) | ESLint + Prettier |
| Статический анализ | mypy (strict) | PHPStan | tsc (strict) |
| Юнит-тесты и покрытие | pytest + coverage | PHPUnit | Jest / Vitest |
| Сложность | complexipy | PHPMD, cognitive-complexity (PHPStan) | ESLint complexity |
| Дублирование | pylint duplicate-code | jscpd | jscpd |
| Архитектура и зависимости | import-linter | Deptrac | dependency-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 работу команды?
С проверками ошибка всплывает на упавшей сборке, где она обходится дешевле, чем на ревью или в продакшене. В проекте с легаси лимиты ставят на текущем уровне, так что в первый день ничего не блокируется.
Можно ли добавить эти проверки в существующий легаси-проект?
Да. Зафиксируйте текущий уровень как лимит, чтобы хуже не становилось, и снижайте его шаг за шагом по мере рефакторинга.
Разве для этого не хватит код-ревью?
Ревью держится на внимательности и не успевает за тем, как быстро агенты пишут код. Проверка запускается на каждом изменении и падает всегда одинаково.
Нужно ли вводить все семь уровней сразу?
Нет. Добавляйте по порядку: сначала дешёвые — мёртвый код, форматирование и типы. Лимиты на сложность и архитектуру окупаются, когда кода становится много.