Clean Architecture для AI-агентов: как проектировать coding-агента
Gemini и DeepSeek спорят, что дороже: устаревший README или токены
В статье рассматривается, как принципы Clean Architecture могут помочь в создании надёжных coding-агентов. Автор описывает концепцию harness — локальной инженерной системы, которая берёт намерение разработчика и проводит его через стадии исследования, проектирования, реализации и проверки. Harness включает три ключевых слоя: оркестрационный (управляет переходом между этапами), семантический (даёт агенту понимание структуры проекта, владельцев поведения и контрактов) и validation (проверяет корректность изменений относительно актуальной версии кода). Такой подход важен, так как скорость генерации кода сама по себе не гарантирует сохранения архитектурного качества. Главная цель — минимизировать человеческие затраты на сопровождение системы.
В области разработки ПО coding-агенты обещают ускорить рутинные задачи, но их использование без должной архитектурной подготовки может привести к накоплению технического долга. Статья на Habr, написанная под ником murmaaan, поднимает эту проблему и предлагает применять принципы Clean Architecture для проектирования инженерной среды вокруг AI-агента, называемой harness. Harness — это репозиторно-локальная система, которая превращает намерение разработчика в ограниченное, воспроизводимое и проверенное изменение продукта. Она включает три взаимосвязанных слоя: оркестрационный, семантический и слой валидации. Оркестрационный слой управляет процессом: фиксирует задачу, распределяет полномочия, проводит работу через стадии исследования, проектирования, реализации, проверки и интеграции. Важны не названия стадий, а явные условия перехода между ними. Семантический слой предоставляет агенту модель продукта, выходящую за рамки простого списка файлов. Он включает знания о владельцах поведения, границах компонентов, пользовательских маршрутах, состоянии, инвариантах и связях между потребителями. Это позволяет агенту не просто найти обработчик события, но и понять, где хранится состояние, какие сценарии затронуты, и кто ещё использует изменяемый контракт. Слой валидации следит за тем, чтобы результаты проверок соответствовали нужной версии кода, а их набор был адекватен масштабу изменения. Независимый reviewer оценивает смысл результата и ищет расхождения. Ключевая идея статьи в том, что скорость генерации кода агентом не должна входить в противоречие с архитектурной целостностью системы. Следуя Clean Architecture, цель — минимизировать человеческие ресурсы, необходимые для создания и сопровождения ПО. Агент, генерирующий код без оглядки на архитектуру, может быстрее создавать связанность, копировать неудачные паттерны и ухудшать изменяемость системы. Поэтому harness должен быть спроектирован так, чтобы важные решения и знания существовали вне промпта и истории чата — в документации, правилах, семантических моделях. Для разработчиков практический вывод таков: при внедрении coding-агентов необходимо инвестировать время в создание harness, а не только в совершенствование подсказок. Это позволит сохранить контроль над кодовой базой и получить максимальную пользу от AI-инструментов.