OpenAPI как общий контракт для AI-кодинга: разбор подхода Powerduck

Проблема: «готово» живёт только в чате

Автор материала на DEV.to описывает типичный сценарий: вы даёте AI задачу построить систему бронирования — выбор слота, создание брони, отмена администратором. Страница есть, эндпоинт есть, таблица в базе есть. Каждый кусок по отдельности выглядит корректно.

Но при соединении всплывают расхождения: фронтенд трактует метку времени как локальное время, бэкенд хранит UTC; эндпоинт отмены возвращает 200, а список всё ещё показывает «reserved»; один и тот же слот бронируется дважды.

Ключевая мысль автора: AI пишет много кода быстро, но если определение корректности существует лишь в нескольких сообщениях чата, каждый модуль формирует собственную интерпретацию.

Что предлагается: OpenAPI как общий референс

OpenAPI Specification (OAS) описывает эндпоинты, параметры, ответы и аутентификацию в структурированном формате. Его читают и люди, и инструменты.

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

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

Один файл на всём пути AI-воркфлоу

Автор перечисляет стадии, на которых, по его описанию, OAS продолжает использоваться в воркфлоу Powerduck:

• Дизайн — AI предлагает изменения эндпоинтов и схем относительно существующих определений.

• Реализация — локальный MCP-сервер передаёт кодинг-ассистенту конкретный контракт, а не вставленный PDF.

• Ожидание зависимостей — мок отвечает на основе примеров и схем из спецификации, чтобы фронтенд мог двигаться дальше.

• Верификация — агент отправляет реальные запросы, запускает проверки контракта и проходит сценарные тесты.

• Поставка — документация рендерится из того же файла, а MCP-эндпоинт может быть опубликован по требованию.

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

«AI-native» — это про петли обратной связи

После появления эндпоинта брони, по описанию автора, можно попросить AI запросить контракт через MCP и отправить запрос в тестовый сервис. Несовпадение параметров, отсутствующее поле ответа или ломающийся на середине сценарий становятся конкретным сигналом для следующей итерации.

Автор противопоставляет это «done» от модели: реальные ответы и результаты ассертов дают больше для разбора — какой шаг прошёл, какое поле не совпало с контрактом, какое правило всё ещё отсутствует.

Ограничения OAS

Автор честно отмечает границы подхода: OAS сам по себе не выразит гонки при бронировании слота, кросс-сервисные транзакции и не каждый бизнес-инвариант. Для этого нужны сценарии, ассерты и тесты уровня реализации. Задача инструмента вроде Powerduck, по его формулировке, — поместить структурированные части контракта в петлю обратной связи, которая ловит пробелы рано.

Local-first: консенсус принадлежит проекту

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

Автор уточняет: local-first не означает «только офлайн». При использовании облачной модели передаваемый контекст всё равно уходит наружу. Смысл в том, что файл и ежедневный воркфлоу принадлежат вам, а не заперты в чат-окне вендора.

Итог

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

Первоисточник: DEV.to