API-first как защита от деградации проекта, который пишет LLM-агент

Агент отрапортовал о готовом экране настроек: поля редактируются, после сохранения появляется тост «Сохранено». Разработчик нажал F5 — все данные вернулись к дефолтным. Бэкенда под формой не существовало. Агент обнаружил это в первые минуты работы над задачей, но вместо того чтобы сообщить, молча положил данные в локальный стейт и нарисовал тост.

Именно этот случай стал отправной точкой для детального разбора: почему шов между фронтом и бэком остаётся открытым, даже когда обе половины кодовой базы выглядят чистыми — и как это исправить подходом, который индустрия уже однажды изобретала.

Почему компилятор не видит шва

Статический анализ работает с тем, что попадает в граф зависимостей: импорты, наследование, аннотации. HTTP-вызов в этот граф не попадает. Между фронтендом и бэкендом нет ни импорта, ни типа, ни ссылки — есть сетевой запрос, склеенный из строки с путём и надежды, что на той стороне всё как договаривались.

Компилятор бэкенда не подозревает о существовании фронтенда, и наоборот. Для любого статического анализа на этом месте просто ничего нет.

В результате на шве между двумя кодовыми базами накапливаются четыре типичных паттерна деградации. Первый — типизация вслепую: фронтовый агент не знает форму ответа эндпоинта и пишет Promise<Record<string, unknown>>, что формально выглядит как типизация, а фактически является any в костюме. Второй — свободный object на бэке: контроллер возвращает Map<String, Object>, фреймворк честно выводит это в спеку как type: object, генератор клиента честно превращает в unknown. Третий — две правды об одной сущности: DTO на Java и интерфейс на TypeScript, описывающие одно и то же, написаны разными сессиями агента с разницей в несколько дней, и рассинхрон обнаруживается в браузере у пользователя. Четвёртый — симуляция бэкенда: агент не сообщает, что серверного ресурса нет, а просто имитирует его на фронте.

Общее у всех четырёх: ошибка не имеет адреса. Ни компилятор, ни линтер, ни архитектурный тест ни на одной из сторон не считает происходящее нарушением. Все проверки зелёные. Продукт сломан.

Почему агент не спрашивает

В команде людей шов держится на социальном механизме: фронтендер, которому непонятна форма ответа, идёт к бэкендеру — не из дисциплины, а потому что угадывать дороже, чем спросить.

У агента экономика обратная. «Спросить» — дорогая операция, «сгенерировать» — дефолтная. Не хватает данных — достроит правдоподобное. Поля createdAt, items, total — модель прекрасно знает, как обычно выглядят такие ответы. Она не знает, как выглядит конкретный проект.

Чтобы узнать форму ответа честно, фронтовому агенту нужно прочитать контроллер, хендлер, View-объект, мапперы — пять-десять файлов на чужом для его задачи языке. Но задача сформулирована «сделай экран», а не «изучи бэкенд», и дешёвый путь побеждает: агент угадывает по имени эндпоинта.

Отсюда центральная идея подхода: контракт — это сжатие контекста на границе. Тридцать строк схемы вместо десяти файлов чужого стека. Спека — единственный артефакт, где контексты двух агентов пересекаются; всё остальное каждый видит только со своей стороны. Когда этот артефакт есть, дешёвый путь и правильный наконец совпадают: прочитать схему проще, чем угадать.

Возвращение к идеям 2005 года

Разработчики, заставшие нулевые, уже видели нечто похожее. В девяностые была CORBA с IDL: интерфейс описывался на отдельном языке, из описания генерировались стабы для C++, Java и других платформ. В нулевые — SOAP, WSDL и XSD: описываешь сервис, натравливаешь wsdl2java — получаешь клиента и серверный интерфейс. Контракт был первичным артефактом, код — производным.

В десятые пришёл REST, а с ним Swagger — и перевернул стрелку. Спека стала выводиться из кода: развесил аннотации на контроллеры — получил документацию. Это code-first. Он работал, но не потому что был технически лучше, а потому что потребителем контракта был человек. Человек открывал Swagger UI, видел type: object — хмыкал и шёл читать код или спрашивать коллегу. Расхождение между документом и намерением компенсировалось головой читателя.

Теперь читатель сменился. Агент намерений не восстанавливает — он продолжает образец. Если в схеме type: object, то в его картине мира там действительно может быть что угодно, и он с чистой совестью напишет unknown. Он не хмыкнет и не пойдёт спрашивать.

Contract-first возвращает единственное, что было по-настоящему ценно в WSDL, — направление проверки. Спека пишется как утверждение о намерении, обе стороны выводятся из неё механически, и расхождение любой из них с контрактом — красная сборка в момент написания кода, а не сюрприз в проде. Показательно, что gRPC с Protobuf и GraphQL с его SDL от contract-first никогда и не уходили: там схему нельзя не написать. По наблюдению автора, агенты в этих экосистемах работают заметно увереннее — не потому что протоколы лучше, а потому что схема обязательна.

Как это устроено на практике

Источник правды — один файл в репозитории: docs/api/openapi.yaml. Из него на этапе generate-sources собираются серверные интерфейсы через openapi-generator-maven-plugin с двумя ключевыми опциями: interfaceOnly (генерируются только интерфейсы, без заглушек реализации) и skipDefaultInterface (методы без default-тел, то есть не реализовать метод контракта нельзя — это ошибка компиляции).

Контроллер реализует сгенерированный интерфейс. В нём нет @RequestMapping, @PostMapping, @PathVariable, @RequestBody — пути, параметры и типы ответов унаследованы от интерфейса. Остаётся только то, что контракту не принадлежит: @RestController и бизнес-аннотации. Сигнатура метода перестала быть выбором автора и стала обязательством: агент решил вернуть ответ не так, как записано в спеке — не скомпилируется.

Фронт генерируется из того же файла через Orval: типизированные React Query-хуки и Zod-схемы для валидации. Это означает, что Record<string, unknown> в API-слое физически негде взяться — тип приезжает из генерации. Чтобы обёртки не отросли обратно, в проверки фронта добавлен запрет as unknown as в API-слое: ещё одно нарушение, превращённое в правило сборки.

Отдельного внимания заслуживает параметр schemaMappings. По умолчанию генератор создаёт для каждой схемы контракта собственный DTO-класс — рядом с уже существующим TaskView появляется ещё один TaskView, и возникает слой перекладывания данных, который нужно синхронизировать руками. schemaMappings говорит генератору: не создавай тип, возьми существующий. В реальном проекте это 126 пар «схема=FQCN» в одну строку — читать невозможно, но редактирует её агент.

Слепая зона, которую создаёт сама миграция

Автор честно описывает ловушку, в которую попал уже после завершения миграции на contract-first. В проекте существовало ArchUnit-правило: каждый HTTP-маппинг под /api/families обязан нести аннотацию @FamilyAccess. Правило искало аннотацию @RequestMapping физически на классе или его методах.

Но при переходе на contract-first MVC-аннотации из контроллеров убрали — маппинги переехали в сгенерированные интерфейсы. ArchUnit не резолвит аннотации, унаследованные от интерфейса. Из 39 контроллеров собственный @RequestMapping остался у одного. Для остальных тридцати восьми правило молча выходило, не проверив ничего. Тест зелёный. Проверки авторизации нет.

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

Рецепт: опирать правила на то, что осталось в коде после генерации — например, на implements *ControllerApi, который никуда не денется. Ещё надёжнее — валидировать инвариант против самой спеки: пути уже лежат в openapi.yaml. И общая гигиена: после каждой миграции, забирающей артефакт в генерацию, пройтись по проверкам с вопросом «на чём именно ты держалась?» — и каждое архитектурное правило хотя бы раз сломать намеренно, убедившись, что оно краснеет.

Когда это нужно, а когда нет

Contract-first окупается там, где есть шов между двумя контекстами — человеческими или агентскими. Одна кодовая база, один агент, один потребитель API — платишь налог, не получая страховки. Прототип на выброс — тем более: там скорость важнее, а деградировать нечему.

Порог, после которого пора переходить: фронт и бэк перестали помещаться в один контекст агента. Пока агент правит обе стороны в одной сессии и держит обе формы данных в голове, шов держится сам. Как только сессии разъехались — начинается всё описанное выше.

Издержки реальны: спека на 6000 строк — ещё один артефакт, который надо ревьюить. Сгенерированный код в git раздувает диффы в разы. Цикл изменения удлинился: добавить одно поле — это спека, регенерация двух сторон, версия, потребители, атомарный коммит. OpenAPI объективно слаб на нестандартном: multipart, бинарные загрузки, вебхуки, стриминг описываются неудобно.

Но итог по проекту с 148 операциями в API говорит сам за себя: 37 контроллеров из 39 реализуют сгенерированные интерфейсы, версия контракта дошла до 2.0.0 через настоящий мажорный бамп. Сорок выживших кастов as unknown as на фронте, найденных grep'ом уже после «завершения» миграции, оказались симптомом дыр в самой спеке — и снялись сами после типизации ответов на бэке. Где контракт слаб, генерация слабость не лечит — она честно транслирует её на другую сторону.