TL;DR
Когда AI-агент пишет код по вашему описанию архитектуры, формат этого описания решает всё — но только если модель не топовая. Если вы дадите Claude Sonnet или GPT-5 обычный текст с описанием системы или формальную TypeScript-схему — результат почти одинаковый. Но дайте ту же задачу дешёвой модели (Haiku, Gemini Flash) — и разница огромная.
Слабая модель, получив описание архитектуры простым текстом, реализует треть от нужного функционала и никогда не проверяет свой код перед тем, как сказать «готово». Она путается в правилах («сервисы не должны звонить друг другу напрямую»), входит в бесконечный цикл исправления ошибок компиляции и тратит на это больше токенов, чем топовая модель — но получает результат хуже.
Решение — заменить текстовое описание архитектуры на код-подобный формат: TypeScript-интерфейсы с явными правилами или OpenAPI-спецификацию. Та же слабая модель, получив архитектуру в виде типизированных контрактов, реализует 100% нужного функционала вместо 33%. Формат спецификации работает как «протез» для слабой модели — компенсирует то, что она не может удержать в голове из расплывчатого текста.
Схема метода
ЕСЛИ модель топовая (Claude Sonnet, GPT-5-уровня):
→ формат архитектуры почти не важен, можно писать текстом
ЕСЛИ модель средняя/бюджетная (Haiku, GPT-5-mini, Gemini Flash/Pro):
→ замени текстовое описание на:
- TypeScript-интерфейсы + явные правила (лучше всего для самой слабой модели)
- OpenAPI-спецификацию (лучше всего для средних моделей)
- Mermaid-диаграммы + ограничения + ADR (записи о причинах решений)
→ каждый формат кодирует ОДНО И ТО ЖЕ содержание, меняется только представление
Пример применения
Задача: Вы фаундер небольшого стартапа, делаете MVP через Cursor или Claude Code с бюджетной моделью (экономите на токенах), а не через дорогой Sonnet/GPT-5. Нужен backend с несколькими сервисами — пользователи, заказы, уведомления — которые должны общаться только через единую шину событий, а не напрямую.
Промпт (вместо обычного текстового описания):
Вот архитектура системы. Реализуй её строго по контрактам ниже.
interface IOrderService {
create(input: CreateOrderInput): Order;
updateStatus(orderId: string, status: OrderStatus): Order;
}
interface INotificationService {
notify(event: OrderEvent): void;
}
ПРАВИЛА:
RULE 1: Файлы в services/*-service.ts НЕ МОГУТ импортировать
друг друга напрямую — только через EventBus.
RULE 2: Каждый сервис владеет только своим хранилищем данных.
RULE 3: Статусы заказа меняются только вперёд:
new → processing → shipped → delivered.
Структура файлов:
src/event-bus.ts
src/services/order-service.ts
src/services/notification-service.ts
src/router.ts
Результат: Модель получит чёткий «скелет» вместо расплывчатого описания. Она реже путает правила, реже уходит в циклы бесконечного исправления ошибок компиляции и с большей вероятностью реализует все нужные функции, а не половину. Итоговый код будет ближе к архитектуре, которую вы задумали, даже если модель бюджетная.
Почему это работает
Слабые модели плохо держат в голове расплывчатые словесные правила — они теряют детали при генерации кода, особенно когда правил много и они пересекаются друг с другом. Это как объяснить человеку архитектуру дома на словах вместо чертежа: он забудет, где несущая стена.
Зато LLM отлично работают с форматами, близкими к тому, что они сами генерируют — код, типы, интерфейсы. TypeScript-контракт — это почти готовый код, модели не нужно «переводить» текст в структуру, структура уже дана.
Метод превращает архитектурное описание в формат, который снижает нагрузку на «воображение» модели. Чем ближе формат к коду — тем меньше модель может ошибиться при интерпретации.
Рычаг управления: если работаете с топовой моделью — не тратьте время на формализацию архитектуры, обычный текст сработает так же. Если модель бюджетная — вложите время в структурированную спецификацию (TypeScript-интерфейсы или OpenAPI), это окупится кратным ростом качества.
Шаблон промпта
Архитектура системы "{название_проекта}":
КОМПОНЕНТЫ:
{список сервисов/модулей с кратким описанием каждого}
КОНТРАКТЫ (TypeScript-интерфейсы):
interface I{Компонент}Service {
{метод1}({входные_параметры}): {тип_результата};
{метод2}({входные_параметры}): {тип_результата};
}
ПРАВИЛА (обязательные ограничения):
RULE 1: {правило про то, что нельзя делать напрямую}
RULE 2: {правило про владение данными}
RULE 3: {правило про порядок операций/статусов}
СТРУКТУРА ФАЙЛОВ:
{прописанная структура папок и файлов}
Реализуй систему строго по этим контрактам и правилам.
Что подставлять: название проекта, реальные названия сервисов/модулей вашей системы, методы которые они должны выполнять, и жёсткие правила (что нельзя делать, кто чем владеет).
🚀 Быстрый старт — вставь в чат:
Вот шаблон архитектурной спецификации для AI-агента, пишущего код.
Адаптируй под мою задачу: {опиши свой проект}.
Задавай вопросы, чтобы заполнить поля.
[вставить шаблон выше]
LLM спросит про компоненты вашей системы, их методы и правила взаимодействия — потому что без этих деталей контракт не соберётся. Она возьмёт структуру TypeScript-интерфейсов из шаблона и наполнит вашими данными.
Ограничения
⚠️ Не работает на топовых моделях: если вы используете Claude Sonnet или GPT-5-уровня, разница между текстом и структурированной спецификацией почти незаметна — не тратьте время на формализацию.
⚠️ Нужна дополнительная работа заранее: чтобы описать архитектуру через TypeScript-контракты, вам нужно самому продумать интерфейсы и правила — это требует больше усилий, чем написать пару абзацев текста.
⚠️ Структурированные форматы иногда увеличивают нестабильность: на некоторых моделях (например Gemini Pro) один формат может внезапно давать аномально низкий результат в конкретном прогоне — гарантии стабильности нет.
⚠️ Проверено на одной системе: эксперимент строился на одном тестовом проекте (Task Management API из 7 компонентов) — на более сложных или нетипичных системах эффект может отличаться.
Как исследовали
Исследователь взял одну тестовую систему — Task Management API из семи компонентов (роутер, сервисы пользователей, проектов, задач, комментариев, уведомлений и шина событий) — и описал её архитектуру пятью разными способами: обычным текстом, Mermaid-диаграммами с правилами, OpenAPI-спецификацией, C4/Structurizr DSL и TypeScript-контрактами с правилами в стиле ArchUnit. Каждое описание содержало одну и ту же информацию — менялся только формат.
Эти пять спецификаций дали шести моделям трёх вендоров (Claude Sonnet/Haiku, GPT-5/mini, Gemini Pro/Flash) в агентном режиме — модель сама писала файлы, компилировала, чинила ошибки и запускала демо. Всего получилось 90 прогонов. Качество оценивал отдельный судья-LLM по четырём критериям плюс автоматическая проверка нарушений архитектуры.
Главный неожиданный результат: у топовых моделей разброс качества между форматами был мизерным (0.17–0.92 балла), а у слабых моделей — огромным (до 2.42 балла), причём слабая модель на структурированном формате обходила саму себя же на текстовом в разы по числу реализованных функций. Дополнительно нашли, что средние модели иногда тратят больше токенов на худший результат, чем топовые — потому что застревают в циклах исправления ошибок, которые сильная модель просто не совершает.