Архитектурный дрифт: как спецификации и тесты спасают код от хаоса ИИ-агентов

Habr AI · оригинал

Материал подготовлен автоматизированной редакционной системой. Факты можно сверить по указанному первоисточнику.

Разработчик описывает проблему «архитектурного дрифта», когда ИИ-агенты нарушают единые стилистические правила проекта. Решение заключается в переносе истины из кода в документацию и автоматической проверке соответствия через спек-тесты.

Материал демонстрирует практический подход к управлению качеством кода, генерируемого ИИ, через строгую документацию и автоматизированные проверки, что критично для масштабируемости проектов с агентной разработкой.

В эпоху активного внедрения ИИ в процесс разработки возникает специфическая проблема, которую автор материала называет архитектурным дрифтом. Ситуация напоминает известный эксперимент с генерацией изображений: если просить нейросеть «не менять ничего», результат всё равно деградирует с каждой итерацией. Аналогично происходит и с кодом: даже если агенту указано использовать конкретный шрифт, размеры текста могут «летать» на разных страницах, разрушая общую стилистику продукта. Основная причина кроется в отсутствии единого источника истины (single source of truth), который бы связывал намерения разработчика и действия алгоритма.

Автор утверждает, что истина должна находиться не в самом коде, а в документации. В его подходе спецификации выступают в роли чертежа, по которому «вытачивается» деталь кода. Документация структурирована в папке docs с использованием правила «7 плюс-минус 2», что позволяет легко ориентироваться даже в массиве из более чем 7000 файлов. Например, все правила типографики собраны в одном файле typography.md, где чётко прописаны допустимые семейства шрифтов (Charis и Inter), веса (400 и 700) и другие параметры. Такой подход исключает противоречия между различными частями проекта.

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

Спек-тесты представляют собой детерминированные проверки кода на соответствие документации. В отличие от обычных тестов, они не проверяют логику работы, а сверяют фактические значения в коде с разрешёнными значениями из спецификаций. Например, тест может обходить весь фронтенд и проверять, что используемые пары шрифта и размера присутствуют в реестре typography.md. Если обнаруживается несоответствие, сборка проекта прерывается с указанием файла и строки ошибки.

В ходе подготовки материала автор столкнулся с тем, что в коде накопилось около 150 пар параметров вне спецификации. За один прогон ИИ-агент исправил 637 употреблений, приведя их в соответствие с документацией, а также добавил недостающие строки в реестр и переписал тест из «чёрного» списка в «белый». Этот пример наглядно демонстрирует эффективность связки документации и автоматических проверок.

Термин «архитектурный дрифт» (architectural drift) был введён ещё в 1992 году Перри и Вульфом, но с появлением ИИ-агентов он приобрёл новое звучание. Когда документация и код расходятся, система защиты срабатывает поэтапно: сначала тесты, затем механизмы self-heal на проде, и лишь в крайнем случае вмешивается человек. Задача разработчика при этом — не просто исправить ошибку, а понять, почему она возникла, и доработать систему так, чтобы подобное не повторялось. Такой подход позволяет поддерживать стабильность архитектуры даже при высокой степени автоматизации разработки.