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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Как это выглядит для сервиса заявок

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

## Нагрузка
- Обычный день: до 2 000 заявок, пик — 5 в секунду во время рассылки.
- Через год в базе около миллиона заявок.

## Задержка
- Ответ на отправку формы: p95 до 300 мс.

## Данные
- PostgreSQL, одна база. Список заявок — постранично, по 50.
- Кэш не нужен.

## Отказы
- Отправка формы идемпотентна: ключ операции приходит с клиента.
- Письмо менеджеру уходит из очереди, не из обработчика запроса.
- Почта недоступна: 5 повторов с растущей паузой и джиттером,
  затем заявка помечается «письмо не отправлено».
- База недоступна: форма отвечает 503, клиент повторяет сам.

## Чего не делаем
- Микросервисы, брокер сообщений, реплики, шардирование.

4

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

Цифры для первого раздела берутся из грубой оценки. Две тысячи заявок в день — это в среднем одна в сорок секунд55В сутках 86 400 секунд. Миллион запросов в день — это всего около двенадцати в секунду в среднем. Пик обычно в несколько раз выше среднего, и систему считают под него.: любая база и любой сервер справятся, и сложная архитектура не нужна. Миллион заявок по два килобайта — два гигабайта: помещается на один диск с огромным запасом. Оценка не обязана быть точной, она должна отличать «сотни в день» от «тысяч в секунду» — потому что это разные системы.

Обратная ошибка: слишком много архитектуры

Раздел «Чего не делаем» в примере ограничивает агента с другой стороны. У агентов есть и противоположная привычка: если попросить «сделать надёжно» или «как в продакшене», сервис заявок на две тысячи в день обрастает брокером сообщений, тремя микросервисами и распределённым кэшем. Всё это работает, проходит тесты и стоит дороже, чем задача, — в поддержке, в инфраструктуре и в количестве мест, которые могут сломаться.

Причина та же: нет цифр. Без оценки нагрузки нельзя отличить разумную предосторожность от лишней сложности — ни агенту, ни тому, кто читает его дифф. Поэтому в спеке нужны обе границы66Отдельные решения удобно записывать как ADR, architecture decision record: контекст, принятое решение и его последствия. Агенту такая запись объясняет не только «как устроено», но и «почему не иначе», и он реже переделывает это по-своему.: что система должна выдержать и чего в ней быть не должно. Как сформулировать такое правило, чтобы агент спрашивал, прежде чем усложнять, показано на конкретном примере в статье об AGENTS.md.

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

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

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

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

Эту проверку можно поручить самому агенту, но в новом сеансе и с другой постановкой: не «проверь свой код», а «для каждого пункта дизайн-дока покажи файл и строку, где он выполнен, или скажи, что не выполнен». Ответ с номерами строк легко проверить выборочно, а пункты без ответа сразу превращаются в список доработок.

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

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

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

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

Курсы по теме

У каждого курса есть бесплатная часть: оставьте почту и начните сразу.

Рассылка

Раз в месяц — новые курсы, обновления программ и платформы. Отписаться можно в один клик из любого письма.

Начните учиться сегодня

Все курсы за 1500 ₽ в месяц. Доступ откроется сразу после оплаты, отменить можно в любой момент.

Для компаний — 5000 ₽ в месяц за сотрудника