AI-ready кодовая база: почему не каждый проект готов к агентам

Подключить AI-агента к репозиторию технически несложно.

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

Не каждый проект готов к агентам.

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

Что для этого нужно:

— актуальная документация с командами запуска и описанием ключевых сценариев;

— тесты, которые проверяют поведение и быстро показывают, что именно сломалось;

— понятная структура проекта без десятка равноправных точек входа;

— небольшие модули с явными границами и ответственностью;

— наблюдаемость: логи, метрики, трассировка и диагностируемые ошибки;

— зафиксированные архитектурные решения;

— ADR с контекстом: какую проблему решали, какие варианты рассматривали и почему выбрали именно этот;

— Decision Log для менее масштабных, но важных договорённостей.

Всё это было полезно и до появления AI-агентов. Просто люди умеют компенсировать недостатки системы: спросить коллегу, вспомнить обсуждение в чате или осторожно не трогать подозрительный участок кода.

Агент такого скрытого контекста не видит.

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

AI не делает плохой проект хорошим.

Он делает последствия плохого проекта заметнее.