Спецификация раньше кода. AI снимает операционную боль поддержки спеки в актуальном виде.
Описание
Разработчик сначала проектирует спецификацию (TypeSpec → OpenAPI), а уже от неё генерирует и бэкенд, и клиент, и моки, и тесты. Поддержка спецификации легче за счёт связки с AI-агентом.
Предусловия
- Используется TypeSpec (или эквивалентный design-first инструмент)
- Команда согласна с design-first как процессом
Постусловия / гарантия успеха
- Существует актуальная спецификация, от которой синхронизированы код бэкенда и клиента
- Изменения проходят через спецификацию, а не через «доделай руками»
Основной сценарий
- Разработчик описывает контракт в TypeSpec
- Агент помогает уточнить и проревьюить контракт (валидность, согласованность)
- Из спецификации генерируются типы бэкенда и клиента, моки и базовые тесты
- Реализация заполняет хендлеры, агент опирается на типы как на надёжный контекст
- При изменениях правится сначала спецификация, потом код
Расширения / альтернативные потоки
- 1a. Для существующих проектов — переход к design-first итеративно, начиная с новых модулей
Исключения и риски
Бизнес-правила и ограничения
- Источник истины — спецификация, а не реализация
- Контракт должен быть совместим с предыдущими версиями (обратная совместимость)
Примечания
Подход особенно силён в сочетании с эталонными реализациями (UC-011 · Эталонная реализация) и типизацией.
Частые вопросы
Чем TypeSpec лучше прямого OpenAPI?+
TypeSpec — это TypeScript-подобный язык для описания API: компактный, типизированный, с переиспользованием. Из него генерируется OpenAPI, JSON Schema, gRPC Proto. Писать TypeSpec в разы быстрее, чем YAML OpenAPI вручную.
Это работает только для greenfield?+
Нет. На существующих проектах переход итеративный: новый модуль = design-first, остальное живёт как есть. Постепенно покрытие растёт.
Что генерируется из спеки?+
Типы для бэкенда и клиента, валидация, моки для тестов, базовые e2e-тесты на контракт. Реализация хендлеров остаётся ручной (или агентской), но опирается на сгенерированные типы как на надёжный фундамент.
Как поддерживать обратную совместимость?+
Через линтер TypeSpec на breaking changes в CI. Любое изменение, нарушающее контракт, ловится автоматически до мерджа.