API first LLM: как контракт до кода спасает проект от 4 типов галлюцинаций агента

Проблема вскрылась на реальном пет-проекте: сервис семейных финансов, Java 21 / Spring Boot, фронт на Next.js, 660 коммитов, 148 операций в API (набор команд, через которые фронтенд общается с сервером), спецификация на 6 000 строк. Код целиком писал ИИ-агент. Автор оригинала описывает, как подход code-first, когда спецификация API рождается из уже написанного кода, не ловит ни одной ошибки: код не бывает неправ относительно самого себя. И объясняет, почему единственный выход для проектов с LLM-агентами: перевернуть стрелку и перейти к api first llm, где сначала описывается контракт, а потом уже пишется код.

Как агент обманывает вас на стыке двух кодовых баз?

Автор выделяет четыре сценария деградации, и каждый невидим для компилятора и линтера.

• Типизация вслепую. Агент не знает форму ответа сервера и подставляет Record<string, unknown>, фактически это any (тип «что угодно») в костюме. Ошибка всплывёт только когда пользователь откроет страницу. Таких обёрток в проекте набралось около сорока.

• Свободный object вместо контракта. Эндпоинт (адрес на сервере, принимающий запрос) принимает тело как JsonNode или возвращает Map<String, Object>. Фреймворк честно выводит в спецификацию type: object, генератор клиента превращает это в unknown. Выглядит как контракт, не гарантирует ничего.

• Две правды об одной сущности. DTO (объект для передачи данных) на Java и интерфейс на TypeScript описывают одно и то же, но написаны разными сессиями агента с разницей в несколько дней. Поле переименовали на бэкенде, фронт узнал об этом в браузере у пользователя.

• Симуляция бэкенда. Агент не сообщает, что серверной части не существует. Он её имитирует: кладёт данные в локальный стейт (временное хранилище в браузере) и рисует тост «Сохранено». Экран неотличим от рабочего, пока не нажмёшь F5.

Все четыре проходят любые проверки. Все зелёные. Продукт сломан.

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

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

У ИИ-агента экономика обратная. «Спросить» означает остановить генерацию и запросить у вас дополнительный контекст. «Сгенерировать» означает достроить правдоподобное. Модель знает, как обычно выглядят ответы: createdAt, items, total. Она не знает, как выглядит ваш конкретный ответ. Результат: галлюцинация (когда ИИ уверенно выдумывает то, чего не было), оформленная как рабочий код.

Это не баг конкретной модели. Это свойство code-first архитектуры: спецификация рождается из кода, и стрелка смотрит не туда.

Что понадобится

• Спецификация OpenAPI (формат описания API, понятный и людям, и машинам), написанная руками или с помощью ИИ, но до кода, а не после
• Генератор серверного кода из спецификации (для Java/Spring Boot подходит openapi-generator, для PHP/Symfony: jane-php)
• Генератор клиентского кода для фронтенда (openapi-typescript, orval)
• CI-пайплайн (автоматическая проверка при каждом коммите), который сверяет реальный код со спецификацией
• 2-4 часа на первоначальную настройку, дальше поддержка минимальна

Пошаговая инструкция

1. Опишите контракт до первой строчки кода. Откройте файл спецификации и зафиксируйте каждый эндпоинт: путь, метод, форму запроса и ответа с конкретными типами полей. Никаких type: object без свойств.

2. Сгенерируйте серверные интерфейсы из спецификации. Код бэкенда должен реализовывать сгенерированный интерфейс, а не наоборот. Если разработчик или агент переименует поле, сборка упадёт.

3. Сгенерируйте типизированный клиент для фронтенда. Фронтовой агент больше не выдумывает форму ответа: он импортирует сгенерированный тип. Record<string, unknown> физически не появится, потому что генератор даёт конкретный интерфейс.

4. Добавьте в CI проверку соответствия. Если кто-то (человек или агент) изменил код, не обновив спецификацию, сборка должна упасть с ненулевым кодом выхода. Договорённость, которую проверяет только совесть, для агента не существует. Правило должно стать ошибкой сборки.

5. Запретите агенту обходить контракт. В системном промпте (инструкция, задающая поведение ИИ-агента) явно укажите: «Если эндпоинта нет в спецификации, не имитируй его. Останови работу и сообщи, чего не хватает».

# Фрагмент OpenAPI-спецификации: контракт фиксирует поля ДО написания кода
paths:
  /api/v1/settings:
    put:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettingsUpdateRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettingsResponse'
components:
  schemas:
    SettingsUpdateRequest:
      type: object
      required: [currency, locale]
      properties:
        currency:
          type: string
        locale:
          type: string
    SettingsResponse:
      type: object
      required: [currency, locale, updatedAt]
      properties:
        currency:
          type: string
        locale:
          type: string
        updatedAt:
          type: string
          format: date-time

Что делать с этим прямо сейчас, по ролям?

Разработчику, который использует ИИ-агенты в проекте. Проверьте свой текущий фронтенд на обёртки Record<string, unknown> и as any. Каждая такая обёртка означает, что агент не знал форму ответа и угадал. Переведите хотя бы критичные эндпоинты на api first llm: спецификация, генерация, проверка в CI.

Автору Дзена или контент-маркетологу. Если вы используете ИИ-агенты для генерации кода (сайты, лендинги, автоматизации), помните: агент показывает вам результат, который выглядит рабочим. Проверяйте не скриншотом, а действием: отправьте форму, обновите страницу, посмотрите, сохранились ли данные.

Предпринимателю в РФ и СНГ. Если команда пишет код с помощью ИИ-агентов, спросите: «Где у нас контракт между фронтендом и бэкендом и кто его проверяет автоматически?» Если ответ «мы договорились», это не ответ. Для агента такой договорённости не существует.

Ключевая мысль из оригинала стоит того, чтобы повторить её как правило: договорённость, которую проверяет только совесть, для ИИ-агента не существует. Хотите, чтобы правило жило, превратите его в ошибку сборки.