В визуальном инструменте очень естественно обсуждать ошибки по скриншотам. Видно, что полка собрана неправильно, свет выглядит неестественно или геометрия персонажа развалилась. Для человека изображение отлично показывает симптом. Но Builder должен уметь объяснить еще и то, что происходило внутри сборки. Поэтому вместе со скриншотами мы начали использовать диагностические JSON-файлы.
Скриншот показывает результат, но не причину
По изображению можно уверенно сказать, что объект оказался не там. Нельзя так же уверенно определить, почему это произошло. Ошибка может быть в распознавании референса, в параметрах генерации, в координатах, в неправильном выборе режима или на одном из промежуточных этапов.
Если делать вывод только по финальной картинке, разработка быстро превращается в серию предположений.
Диагностика фиксирует состояние конкретного запуска
Полезный диагностический файл хранит параметры задания, выбранные режимы, версии, результаты этапов и другие данные, которые позволяют восстановить контекст. В следующий раз не нужно спрашивать, какие настройки были включены, или пытаться вспомнить, что именно произошло перед ошибкой.
Особенно это важно для проблем, которые проявляются не каждый раз.
Визуальная и техническая диагностика дополняют друг друга
JSON без скриншота тоже недостаточен. Технические значения могут выглядеть корректно, хотя итог визуально плохой. Поэтому лучшая единица разбора для нас - пара: изображение показывает дефект, диагностика показывает путь, который к нему привел.
Это позволяет обсуждать не абстрактное "сделай лучше", а конкретную связь между внутренним состоянием и результатом.
Версия Builder должна быть частью контекста
Когда инструмент быстро меняется, одинаковые настройки в двух версиях могут привести к разному поведению. Поэтому диагностический отчет должен позволять понять, какой именно сборкой получен результат.
Иначе исправленная проблема может неожиданно "возвращаться" только потому, что сравниваются результаты разных веток или старых сборок.
Диагностика делает работу с AI-агентами предметной
Если агент получает только фразу "что-то не так с полками", он вынужден гадать. Если вместе с изображением есть структурированный отчет конкретного запуска, можно просить его искать несоответствие в реальных параметрах и логике.
Чем больше инструмент умеет описать собственную работу машинно-читаемым способом, тем меньше исправление зависит от визуальной интуиции исполнителя.
Мы не рассматриваем диагностический файл как журнал для разработчиков, который пользователь никогда не увидит. Для экспериментального Builder это часть самого рабочего процесса. Он превращает визуальный дефект из субъективного впечатления в воспроизводимую инженерную задачу.