Почему зелёные тесты не гарантируют правильную архитектуру AI-приложения
Зелёный статус тестов означает только одно: код проходит заданные проверки. Он не доказывает, что исходная постановка задачи, модель данных и выбранный маршрут данных соответствуют бизнес-смыслу. AI-агент может последовательно реализовать неверную интерпретацию требования, а затем закрепить её автоматическими тестами. В результате вы получаете стабильно работающую систему, которая делает не то, что нужно пользователю.
Цепочка ошибки выглядит так: расплывчатое требование -> неверная модель данных -> рабочая реализация -> тесты, проверяющие уже эту реализацию. AI-агент не обязан угадывать архитектурное намерение без явных ограничений, схем и критериев приёмки. Если вы не задали источник данных, роль элемента и ожидаемый конечный артефакт, модель выберет первый правдоподобный вариант и будет придерживаться его.
В этой статье разберём постмортем разработки Electron-редактора печатных меню. Покажем, как AI-агент ошибся с полем volume, почему TypeScript, визуальные проверки и почти две тысячи успешных тестов не спасли, и как выстроить процесс, чтобы не повторять эту ошибку.
Бытовая задача с типографскими допусками: что требовалось от Electron-редактора меню
Electron-редактор печатных меню позволяет пользователю редактировать элементы меню, видеть экранное превью и получать PDF для печати. Для такого продукта важны не только значения в интерфейсе, но и источник данных, роль каждого элемента, координаты, размеры, порядок слоёв и свойства конечного файла. Экранное превью и печатный PDF должны согласовываться, иначе пользователь увидит одно, а напечатает другое.
Одна сцена, два тонких рендера
Архитектурная предпосылка: SVG и PDF должны получать данные из одной согласованной модели, иначе представления начнут расходиться. Для этого вводится SceneTree - единое дерево сцены или каноническая модель, описывающая элементы меню, их роли, содержимое и геометрию. Два адаптера или рендера используют эту модель: SVG-превью для интерфейса и PDF-экспорт для печатного результата.
Дублирование логики между экраном и экспортом увеличивает риск расхождения. Если SVG-рендер и PDF-рендер по-разному интерпретируют данные, пользователь увидит правильное превью, но получит неправильный PDF. Единый SceneTree снижает этот риск, но не устраняет полностью: ограничения рендереров остаются.
Почему экранное превью нельзя считать готовым PDF
SVG-превью и PDF-рендерер могут по-разному обрабатывать текст, шрифты, размеры, координаты, переносы и графические возможности. PDFKit, популярная библиотека генерации PDF, имеет свои ограничения: не все SVG-фичи поддерживаются, шрифты могут подставляться иначе, а координатная система может отличаться. Поэтому корректный экран не заменяет проверку итогового PDF.
Практический вывод: после генерации PDF нужно открыть файл и проверить визуально, а не полагаться на превью в интерфейсе. Расхождения могут быть незаметны на экране, но критичны для печати.
Ошибка поля volume: как AI-агент реализовал неверный маршрут данных
Центральный кейс статьи: AI-агент получил сложную задачу, выбрал неверный маршрут для поля volume, реализовал его последовательно и затем создал проверки, которые соответствовали этой трактовке. Проблема возникла не в синтаксисе или типах, а в неверной интерпретации назначения поля.
Где модель данных допустила подмену
Для поля volume нужно задать три вопроса: откуда берётся значение, что именно оно означает в бизнес-модели и какому визуальному элементу или операции соответствует. Одинаковый тип, например число или строка, не сообщает, является ли значение объёмом напитка, частью подписи, параметром размера или данными другого элемента.
Агент выбрал один из возможных источников и закрепил его в коде. Если в задаче не было явного указания, что volume относится к конкретному элементу меню, агент мог взять значение из соседнего поля или из технически удобного места. Типовая система это пропустит.
Рабочий код не исправляет неверное намерение
Агент способен корректно провести значение через типы, компоненты и тестовые сценарии, если исходная трактовка не была оспорена. Локально аккуратная реализация усиливает архитектурную ошибку: код выглядит правильным, тесты проходят, но данные идут не туда.
Ключевое различие: «данные дошли по ожидаемому пути» и «данные должны были идти именно по этому пути». Первое проверяется тестами, второе - только бизнес-семантикой.
Почему TypeScript, визуальная проверка и почти две тысячи тестов не спасли
Большое число зелёных тестов увеличивает уверенность только в проверяемых предположениях. Если неверное предположение встроено в код и ожидаемые результаты, автоматизация будет стабильно подтверждать ошибочную систему. Разберём каждый уровень контроля.
Что действительно проверяет TypeScript
TypeScript помогает обнаруживать несовместимые типы, отсутствующие поля и часть ошибок интерфейсов между модулями. Он не знает, какой объект является владельцем volume, правильно ли выбрано поле источника и соответствует ли значение печатному макету. Типовая согласованность не равна бизнес-семантике.
Почему визуальная проверка может подтвердить ошибочный результат
SVG-превью может выглядеть правдоподобно, хотя данные пришли из неправильного места или относятся не к тому элементу. Визуальная проверка экрана не доказывает соответствие PDF, геометрии и бизнес-роли элемента. Человек видит красивую картинку и не замечает подмены.
Интеграционный сценарий проверяет заданный маршрут, а не правильный маршрут
Тест «ввод -> состояние -> отображение» полезен только при корректно заданном ожидаемом поведении. Если тест повторяет реализацию автора или агента и не содержит независимого эталона семантики, он подтверждает внутреннюю непротиворечивость, а не правильность продукта.
Почти две тысячи зелёных тестов: что они на самом деле доказали
Количество успешных тестов не компенсирует отсутствие проверки источника данных, роли элемента и конечного артефакта. Тестовый набор может быть широким по покрытию кода, но узким по покрытию бизнес-смысла. Почти две тысячи тестов подтвердили, что реализация соответствует сама себе, но не требованиям пользователя.
Одна модель данных для SVG и PDF: как должна выглядеть архитектура
Корректирующая архитектурная модель уменьшает вероятность расхождения между экраном и печатью. SceneTree должен быть каноническим источником, из которого оба выхода получают одну и ту же структуру сцены. Семантические данные и рендеринговые адаптеры разделяются.
SceneTree как источник истины, а не ещё один DTO
SceneTree описывает идентичность элемента, его роль, содержимое, связи с данными и геометрию. Он не должен просто копировать состояние интерфейса: он представляет сцену независимо от конкретного рендера. Тогда SVG-превью и PDF-экспорт используют одни и те же данные, и расхождения становятся явными.
Разделить семантику и отрисовку
Граница между данными меню и кодом, который превращает их в SVG или PDF, должна быть чёткой. Правила выбора значения и роли элемента находятся до рендера, а особенности SVG и PDFKit локализованы в соответствующих экспортных слоях. Так ограничения одного рендера не начнут определять бизнес-модель.
Проверять геометрию на уровне конечного результата
Проверяемые свойства: наличие элемента, его позиция, размеры, порядок, переносы, видимость и соответствие содержимого ожидаемой роли. Для PDF отдельно проверяйте сформированный файл, а не только промежуточное дерево или SVG. Геометрия на экране и в печати может отличаться.
Как перестроить работу с AI-агентом после такого сбоя
Сложные задачи нельзя поручать одной расплывчатой инструкцией. До генерации кода нужно зафиксировать архитектурные ограничения, схему данных, запрещённые маршруты, критерии остановки и способ независимой проверки.
Разделить контекст автора и контекст проверяющего
Два режима работы: автор получает задачу и ограничения, проверяющий получает бизнес-правило, ожидаемый источник данных и критерии результата без необходимости защищать предыдущую реализацию. Проверяющий должен искать подмену смысла, а не только ошибки выполнения. Иначе агент оценивает собственную реализацию по тем же предположениям, на которых она построена.
Явные запреты для неоднозначных полей
Прямо фиксируйте, какой объект является источником значения, какие поля запрещено использовать, что означает volume, в каком элементе оно отображается и какие преобразования недопустимы. Запреты должны быть частью задания и тестовой спецификации. Это снижает пространство для догадок модели.
STOP-условия вместо бесконечного продолжения
Условия остановки: неоднозначен владелец данных, не подтверждена роль поля, SVG и PDF расходятся, не найден независимый эталон или агент предлагает менять тесты вместо исправления модели. После STOP-условия сначала уточняется контракт, затем продолжается реализация. Не позволяйте агенту продолжать рефакторинг поверх неподтверждённой архитектурной гипотезы.
Приёмочные критерии через источник, роль и геометрию
Шаблон критерия: «значение берётся из ..., описывает ..., отображается в элементе ..., имеет такие-то координаты и размеры, а в итоговом PDF должно ...». Разделяйте функциональные, архитектурные и визуально-печатные критерии. Это превращает бизнес-смысл в проверяемую инструкцию для человека и AI-агента.
Чек-лист проверки AI-приложения перед выпуском
Источник данных и владелец значения
Проверьте происхождение volume, связи элемента с моделью и отсутствие скрытых fallback-маршрутов. Зафиксируйте источник в тесте или контракте, а не только в комментарии. Каждое важное поле должно приходить из предусмотренного источника и не подменяться соседним или технически удобным значением.
Роль элемента и бизнес-семантика
Для каждого значимого поля опишите, что оно означает, где должно отображаться и какие значения считаются ошибочными. Сопоставьте это описание с SceneTree и экспортными адаптерами. Значение должно использоваться для правильного объекта и правильной операции.
SVG-превью и итоговый PDF
Проверьте экранное превью, затем сформированный PDF. Сравните наличие элементов, текст, позиционирование, размеры и порядок слоёв. Учитывайте ограничения PDFKit и не считайте SVG автоматическим эталоном печати. Расхождения, которые не видны на одном из уровней, могут быть критичны.
Независимый тестовый эталон
Ожидаемый результат должен быть выведен из бизнес-правила или заранее описанной сцены, а не скопирован из текущего кода. Для критичных сценариев полезно проверять путь данных, семантическую роль и конечную геометрию отдельно. Тесты не должны просто повторять ошибочную реализацию.
Вместо вывода: зелёный статус - это только начало проверки
AI-агент может ускорить реализацию, но не заменяет архитектурный контракт и независимую приёмку. Надёжность сложного приложения определяется не числом зелёных тестов, а тем, подтверждают ли они правильный источник данных, роль элемента, геометрию и конечный пользовательский артефакт. При неоднозначности требования лучше остановить генерацию и уточнить смысл, чем масштабировать неверную трактовку.