Системный дизайн — недостающая половина spec-driven development

Spec-driven development — способ работать с AI-агентом, при котором сначала пишется спецификация, а код делается по ней и проверяется на соответствие. Так устроены GitHub Spec Kit, Kiro от AWS и цепочка «спека → план → задачи», которую многие собирают вручную в Claude Code и Codex.

В хорошей спеке два слоя:

• что система делает: требования, сценарии, критерии приёмки;
• как она устроена: компоненты, хранилища, API, поведение под нагрузкой и при отказах.

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

Что агент решит за вас

Попросите агента сделать сервис заявок: форма, база, письмо менеджеру. Он сделает. А дальше молча примет за вас несколько решений:

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

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

Что писать в архитектурной части спеки

Это и есть системный дизайн, только записанный до промпта, а не нарисованный после аварии. Минимальный набор вопросов, на которые спека должна отвечать:

1. Нагрузка. Сколько запросов в секунду в обычный день и в пик, сколько данных через год. Оценка на салфетке с точностью до порядка уже меняет решения.
2. Задержка. Какой ответ считается быстрым — и по какому перцентилю. Среднее скрывает тех 5% пользователей, которые ждут по десять секунд.
3. Данные. Где хранить, что можно кэшировать и насколько кэш может отставать, когда понадобятся реплики.
4. Отказы. Что делать, когда не отвечает база, очередь или внешний API: таймауты, ретраи с джиттером, какие операции безопасно повторять.
5. Долгая работа. Что выносится в очередь: письма, отчёты, вызовы модели.
6. LLM как зависимость. Если в сервисе есть вызов модели — лимиты токенов, стоимость, кэш промптов и что делать, когда провайдер недоступен.

Такой документ обычно называют дизайн-доком. Для агента это часть контекста наравне с требованиями: с ним он строит то, что нужно, а не то, что проще.

Ревью архитектуры в коде агента

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

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

Если ответа в коде нет, значит, агент принял решение сам — обычно самое простое.

Где этому учиться

На курсе «Системный дизайн» мы разбираем ровно эти вопросы: оценку на салфетке, перцентили, хранилища и кэш, отказы, очереди и LLM внутри системы. Последний модуль — дизайн-док до промпта и ревью архитектуры в коде агента.

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