AI-ready кодовая база: почему не каждый проект готов к агентам
Подключить AI-агента к репозиторию технически несложно.
Сложнее сделать так, чтобы он не тратил большую часть времени на археологию: искал точку входа, угадывал контракты и пытался понять, почему странное решение трёхлетней давности нельзя просто удалить.
Не каждый проект готов к агентам.
Чтобы агент мог приносить пользу, кодовая база должна быть понятна не только людям, которые годами держат её контекст в голове.
Что для этого нужно:
— актуальная документация с командами запуска и описанием ключевых сценариев;
— тесты, которые проверяют поведение и быстро показывают, что именно сломалось;
— понятная структура проекта без десятка равноправных точек входа;
— небольшие модули с явными границами и ответственностью;
— наблюдаемость: логи, метрики, трассировка и диагностируемые ошибки;
— зафиксированные архитектурные решения;
— ADR с контекстом: какую проблему решали, какие варианты рассматривали и почему выбрали именно этот;
— Decision Log для менее масштабных, но важных договорённостей.
Всё это было полезно и до появления AI-агентов. Просто люди умеют компенсировать недостатки системы: спросить коллегу, вспомнить обсуждение в чате или осторожно не трогать подозрительный участок кода.
Агент такого скрытого контекста не видит.
Если структура запутана, он быстрее запутается. Если тестам нельзя доверять, он быстрее внесёт регрессию. Если решения нигде не записаны, он уверенно повторит уже отвергнутый вариант.
AI не делает плохой проект хорошим.
Он делает последствия плохого проекта заметнее.
Подключить AI-агента к репозиторию технически несложно.
Сложнее сделать так, чтобы он не тратил большую часть времени на археологию: искал точку входа, угадывал контракты и пытался понять, почему странное решение трёхлетней давности нельзя просто удалить.
Не каждый проект готов к агентам.
Чтобы агент мог приносить пользу, кодовая база должна быть понятна не только людям, которые годами держат её контекст в голове.
Что для этого нужно:
— актуальная документация с командами запуска и описанием ключевых сценариев;
— тесты, которые проверяют поведение и быстро показывают, что именно сломалось;
— понятная структура проекта без десятка равноправных точек входа;
— небольшие модули с явными границами и ответственностью;
— наблюдаемость: логи, метрики, трассировка и диагностируемые ошибки;
— зафиксированные архитектурные решения;
— ADR с контекстом: какую проблему решали, какие варианты рассматривали и почему выбрали именно этот;
— Decision Log для менее масштабных, но важных договорённостей.
Всё это было полезно и до появления AI-агентов. Просто люди умеют компенсировать недостатки системы: спросить коллегу, вспомнить обсуждение в чате или осторожно не трогать подозрительный участок кода.
Агент такого скрытого контекста не видит.
Если структура запутана, он быстрее запутается. Если тестам нельзя доверять, он быстрее внесёт регрессию. Если решения нигде не записаны, он уверенно повторит уже отвергнутый вариант.
AI не делает плохой проект хорошим.
Он делает последствия плохого проекта заметнее.
👍2❤1
Код работает. Но команда не понимает почему
PR принят. Тесты зелёные. Решение уже в проде.
Но через месяц появляется новое требование — и выясняется, что никто не хочет трогать этот код.
Не потому, что он плохо написан. Просто команда не может уверенно ответить:
— почему выбрали именно это решение;
— какие предположения в него заложены;
— где проходят его границы;
— что сломается при изменении требований.
AI заметно ускорил путь от задачи до работающего кода. Но вместе с этим появился новый вид долга — долг понимания, или comprehension debt.
Это не совсем обычный технический долг.
Технический долг обычно заметен: дублирование, сложные зависимости, отсутствие тестов, устаревшие библиотеки. А здесь код может выглядеть вполне прилично.
Проблема в другом: команда формально владеет решением, но фактически не понимает его достаточно хорошо, чтобы безопасно развивать.
Особенно опасна фраза:
Проверка результата не равна пониманию решения.
Как тимлиду не допустить накопления такого долга?
На ревью обсуждать не только код, но и решение:
1. Почему выбран этот подход?
2. Какие альтернативы рассматривались?
3. На каких предположениях всё держится?
4. Где решение перестанет работать?
5. Сможет ли автор объяснить его без ссылки на чат с AI?
Не каждый PR должен превращаться в архитектурный трактат. Но чем выше цена ошибки, тем важнее зафиксировать ход мысли: в описании PR, ADR, комментарии к тесту или короткой схеме.
AI может генерировать код быстрее, чем команда успевает строить его ментальную модель. Поэтому новая задача тимлида — следить не только за скоростью разработки и качеством кода, но и за тем, остаётся ли понимание внутри команды.
Потому что код, который никто не понимает, — это уже не ускорение.
Это отложенный инцидент.
PR принят. Тесты зелёные. Решение уже в проде.
Но через месяц появляется новое требование — и выясняется, что никто не хочет трогать этот код.
Не потому, что он плохо написан. Просто команда не может уверенно ответить:
— почему выбрали именно это решение;
— какие предположения в него заложены;
— где проходят его границы;
— что сломается при изменении требований.
AI заметно ускорил путь от задачи до работающего кода. Но вместе с этим появился новый вид долга — долг понимания, или comprehension debt.
Это не совсем обычный технический долг.
Технический долг обычно заметен: дублирование, сложные зависимости, отсутствие тестов, устаревшие библиотеки. А здесь код может выглядеть вполне прилично.
Проблема в другом: команда формально владеет решением, но фактически не понимает его достаточно хорошо, чтобы безопасно развивать.
Особенно опасна фраза:
«Это AI предложил, мы проверили — работает».
Проверка результата не равна пониманию решения.
Как тимлиду не допустить накопления такого долга?
На ревью обсуждать не только код, но и решение:
1. Почему выбран этот подход?
2. Какие альтернативы рассматривались?
3. На каких предположениях всё держится?
4. Где решение перестанет работать?
5. Сможет ли автор объяснить его без ссылки на чат с AI?
Не каждый PR должен превращаться в архитектурный трактат. Но чем выше цена ошибки, тем важнее зафиксировать ход мысли: в описании PR, ADR, комментарии к тесту или короткой схеме.
AI может генерировать код быстрее, чем команда успевает строить его ментальную модель. Поэтому новая задача тимлида — следить не только за скоростью разработки и качеством кода, но и за тем, остаётся ли понимание внутри команды.
Потому что код, который никто не понимает, — это уже не ускорение.
Это отложенный инцидент.
👍2❤1
Долг понимания: новый вид технического долга
Код компилируется.
Тесты проходят.
PR смержен.
Фича работает.
Формально всё хорошо. Но через несколько месяцев выясняется, что никто в команде толком не понимает, почему решение устроено именно так.
С AI попасть в эту ситуацию стало проще.
Разработчик ставит задачу агенту. Агент исследует кодовую базу, предлагает реализацию, пишет тесты и исправляет ошибки. Результат выглядит убедительно, поэтому хочется проверить только внешнее поведение:
Работает?
Работает.
Значит, можно принимать.
Проблема проявится позже, когда изменятся требования. Тогда окажется, что команда не знает:
— какие предположения заложены в решение;
— почему выбран именно этот подход;
— какие альтернативы были отброшены;
— где находятся скрытые ограничения;
— что сломается при следующем изменении.
Я бы назвал это долгом понимания.
Обычный технический долг часто появляется как осознанный компромисс: сейчас делаем проще, потом переделаем.
С долгом понимания хуже. Команда может даже не знать, что компромисс существует. Код уже стал частью системы, а объяснение осталось где-то в истории диалога с агентом.
Особенно опасно принимать таким образом сложную бизнес-логику, инфраструктурный код, concurrency, безопасность, нетривиальные оптимизации и архитектурные изменения.
Поэтому правила «тесты зелёные» уже недостаточно.
Перед merge я бы добавил ещё одну проверку:
Могу ли я объяснить это решение другому инженеру без открытия истории диалога с AI?
Почему код устроен именно так? На каких предположениях он держится? Где его границы? Что придётся пересмотреть при изменении требований?
Если ответов нет, код может быть рабочим. Но ownership над ним у команды ещё не появился.
AI делает создание кода дешевле. Значит, понимание этого кода становится дороже и ценнее.
Код компилируется.
Тесты проходят.
PR смержен.
Фича работает.
Формально всё хорошо. Но через несколько месяцев выясняется, что никто в команде толком не понимает, почему решение устроено именно так.
С AI попасть в эту ситуацию стало проще.
Разработчик ставит задачу агенту. Агент исследует кодовую базу, предлагает реализацию, пишет тесты и исправляет ошибки. Результат выглядит убедительно, поэтому хочется проверить только внешнее поведение:
Работает?
Работает.
Значит, можно принимать.
Проблема проявится позже, когда изменятся требования. Тогда окажется, что команда не знает:
— какие предположения заложены в решение;
— почему выбран именно этот подход;
— какие альтернативы были отброшены;
— где находятся скрытые ограничения;
— что сломается при следующем изменении.
Я бы назвал это долгом понимания.
Обычный технический долг часто появляется как осознанный компромисс: сейчас делаем проще, потом переделаем.
С долгом понимания хуже. Команда может даже не знать, что компромисс существует. Код уже стал частью системы, а объяснение осталось где-то в истории диалога с агентом.
Особенно опасно принимать таким образом сложную бизнес-логику, инфраструктурный код, concurrency, безопасность, нетривиальные оптимизации и архитектурные изменения.
Поэтому правила «тесты зелёные» уже недостаточно.
Перед merge я бы добавил ещё одну проверку:
Могу ли я объяснить это решение другому инженеру без открытия истории диалога с AI?
Почему код устроен именно так? На каких предположениях он держится? Где его границы? Что придётся пересмотреть при изменении требований?
Если ответов нет, код может быть рабочим. Но ownership над ним у команды ещё не появился.
AI делает создание кода дешевле. Значит, понимание этого кода становится дороже и ценнее.
👍2