Часть 2. Почему разработка по спецификациям

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

SDD решает эту проблему не магией, а переносом контекста из эфемерной переписки в версионируемые файлы. Агент получает не только команду «сделай», но и карту проекта: зачем он существует, какие решения уже приняты, что сейчас строится, как проверить готовность.

Типовые сбои вайб-кодинга

1. Смещение намерения. Вы просили «простую форму», агент добавил сложное управление состоянием, новую библиотеку и другой стиль интерфейса.
2. Распад контекста. Через несколько сессий агент забывает, почему проект не использует ORM или почему API должен рендерить HTML на сервере.
3. Непроверяемый результат. Агент изменил 30 файлов, а вы не знаете, по каким критериям это принимать.
4. Скрытые решения. Важные решения остались внутри истории чата и не попали в репозиторий.

1. Усталость рецензента. Агент пишет быстро, а человек утомляется проверять большой поток изменений.

SDD не делает агента безошибочным. Оно делает ошибки более ранними, маленькими и проверяемыми.

Что меняется в работе с Qwen Code

Вместо одной длинной сессии вида:

qwen
> Построй всё приложение.
> Исправь это.
> Выглядит неправильно.
> Добавь тесты.
> Всё-таки используй SQLite.

вы создаёте устойчивый цикл:

qwen
> /clear
> Прочитай @specs/mission.md @specs/tech-stack.md @specs/roadmap.md.
> Создай спецификацию фичи для следующей фазы дорожной карты. Сначала задай мне вопросы.

Затем в новой сессии:

qwen
> /clear
> Прочитай @specs/mission.md @specs/tech-stack.md и @specs/2026-05-08-reviews-display/plan.md.
> Реализуй только группы задач 1 и 2. Не меняй несвязанные файлы.

И отдельно для проверки:

qwen
> /clear
> Сравни реализацию с @specs/2026-05-08-reviews-display/validation.md.
> Перед исправлениями перечисли расхождения.

Каждая сессия получает ровно тот контекст, который нужен для её роли.

SDD не равно водопадная модель

Классическая водопадная модель пытается заранее описать всю систему. В SDD с агентами спецификации маленькие, живые и ориентированы на одну фичу. Вы не пишете 80 страниц перед стартом. Вы фиксируете достаточный контекст для следующего осмысленного шага.

Хорошая спецификация фичи должна быть:

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

Семь вопросов, на которые отвечает хорошая спецификация

Чтобы не сводить спецификацию к набору заголовков, держите в голове семь вопросов. Если на какой-то ответа нет, спецификация ещё не готова к реализации.

1. Какое бизнес-намерение или продуктовая задача стоит за фичей? То есть зачем мы это делаем, а не «что» и «как».
2. Кто пользователь и какой у него сценарий? Если фичей пользуется только администратор, это другой набор решений, чем если её видит посетитель.
3. Что входит в работу, а что нет? Явно перечисленные границы и явное «за границами» защищают от расползания.

1. Какие решения уже приняты, какие открыты? Запись принятых решений нужна, чтобы агент не выбирал заново. Запись открытых — чтобы человек заметил их и закрыл до реализации.
2. Какие ограничения нельзя ослабить? Стек, инварианты, схема данных, формат API, ограничения безопасности.
3. Что не должно сломаться? Существующее поведение, которое фича не должна задеть (см. отдельный раздел про отрицательные требования в части 7).
4. Как будет доказано, что результат корректен? Команды, ручные сценарии, контрольные значения, признаки расхождения. Без этого спецификация — пожелание, а не договор.

Эти семь вопросов не диктуют структуру файла. Структура остаётся прежней: requirements.md, plan.md, validation.md. Семь вопросов — проверка содержания.

Когда SDD избыточен

Не нужно писать полноценную конституцию ради одноразового скрипта оболочки или маленькой правки текста. Лёгкий запрос иногда лучше. Практическое правило:

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

• если агент будет работать автономно дольше нескольких минут, спецификация почти всегда окупается.

Пример: плохая экономия времени

Вы просите:

Добавь вход.

Агент может выбрать JWT, сессии в cookie, OAuth, локальных пользователей, ссылки для входа без пароля, PostgreSQL, SQLite, Prisma, Drizzle, сброс пароля, промежуточный слой и интерфейс. Если половина выборов неверна, вы потратите время на откат.

Лучше сначала описать:

# Требования — вход администратора

## Границы
- Одна страница входа только для администратора.
- Аутентификация через cookie-сессию.
- Без самостоятельной регистрации.
- Без сброса пароля в этой фазе.

## Решения
- Хранить одного администратора в SQLite.
- Использовать httpOnly cookie.
- Защитить только `/dashboard`.

## Проверка
- Неаутентифицированный GET /dashboard перенаправляет на /login.
- Неверный пароль показывает общее сообщение об ошибке.
- Верный пароль устанавливает cookie и перенаправляет на /dashboard.
- `npm test` и `npm run typecheck` проходят.

Теперь агенту не нужно угадывать.

Практика

Возьмите любую фичу, которую вы обычно попросили бы сделать одной фразой. Перепишите её как мини-спецификацию:

# Требования — <название фичи>

## Границы

## За границами

## Решения

## Проверка

После этого задайте Qwen Code вопрос:

Проверь @requirements.md как спецификацию фичи. Что в нём достаточно неоднозначно, чтобы реализация ушла в сторону?

Не просите писать код, пока не устраните неоднозначность.

Контрольные вопросы

1. Чем SDD на уровне фич отличается от большого предварительного проектирования?
2. Почему «код работает» недостаточно для приёмки изменений, сделанных агентом?
3. Какие решения в вашем проекте должны быть записаны до генерации кода?