Когда мы начали отдавать цельные HTML-прототипы AI-агентам, ожидание было довольно естественным: если человек смотрит на страницу и понимает, что перед ним кнопка, карточка, таб, панель и состояние, то модель тоже должна это считать. На практике агент видит гораздо больше кода, чем смысла. Красивый и очевидный для человека экран может быть для него неоднозначным набором вложенных блоков.
Визуальная очевидность не равна структурной очевидности
Человек быстро группирует элементы по форме, расстоянию и назначению. Он видит одинаковые кнопки даже тогда, когда внутри HTML они собраны немного по-разному. Он понимает, что два блока являются вариантами одного компонента, хотя у них разные тексты и размеры.
AI-агент чаще опирается на то, что явно выражено в структуре. Если повторяемый элемент не выделен как сущность, модель должна сама догадаться, что это не три похожих блока, а один компонент в трех состояниях. Иногда догадка оказывается верной. Иногда агент начинает исправлять каждый экземпляр отдельно и постепенно разводит их еще сильнее.
Чем цельнее прототип, тем больше скрытых решений
В длинном HTML-файле одновременно живут композиция страницы, стили, локальные исключения, временные решения, обработчики событий и данные для демонстрации. Автор помнит, что часть кода экспериментальная, а часть уже является правилом. Агент такой памяти не имеет.
Поэтому просьба вроде "приведи табы к общему виду" может вызвать слишком широкую переработку. Модель пытается вывести систему из текущего состояния и иногда считает локальную особенность глобальным правилом. Проблема не в том, что агент недостаточно умный. Ему просто дали результат без карты принятия решений.
Мы начали давать агентам каталог элементов
Рабочим решением для нас стал Component HTML Catalog - отдельные минимальные примеры компонентов, состояний и вариантов. Вместо того чтобы объяснять устройство кнопки по целой странице, можно показать саму кнопку в изоляции. То же относится к карточкам, табам, панелям, служебным статусам и другим повторяемым элементам.
Такой каталог не заменяет цельный прототип. Он дополняет его. Прототип показывает композицию и реальное соседство элементов, а каталог объясняет, из каких сущностей эта композиция построена.
Токены уменьшают пространство для догадок
Отдельный слой дизайн-токенов решает похожую задачу для визуальных правил. Если цвета, поверхности, границы и типографика названы, агенту не нужно угадывать, почему два элемента выглядят одинаково. Он видит ссылку на одно правило.
Это особенно важно при массовых изменениях. Задача "сделать вторичные поверхности чуть светлее" превращается из поиска десятков CSS-значений в изменение понятной роли. Чем меньше агенту приходится реконструировать намерение по косвенным признакам, тем стабильнее результат.
Хорошая документация для AI похожа на хорошую документацию для людей
Разница лишь в степени формализации. Человеку иногда достаточно посмотреть на соседний экран и понять контекст. Агенту полезнее прямо сказать: что является системным, что локальным, что можно менять, что уже проверялось и что нельзя сломать.
Мы постепенно пришли к простой формуле: AI-агенту не нужно отдавать больше информации. Ему нужно отдавать более правильно организованную информацию.
Цельный прототип по-прежнему остается главным способом увидеть продукт целиком. Но когда он становится единственным источником истины, каждый новый исполнитель - человек или модель - вынужден заново восстанавливать скрытую архитектуру. Нам оказалось дешевле сделать эту архитектуру явной.