Тема: Часть 2. Почему разработка по спецификациям
Уровень сложности: Средний
Расчётное время изучения: 4-6 часов (теория + практика)
Предварительные требования: Базовое понимание работы с AI-ассистентами (Qwen, ChatGPT, Claude и др.)
Опыт работы с системами контроля версий (Git)
Начальные знания веб-разработки (HTML, CSS, JavaScript/TypeScript)
Понимание базовых концепций архитектуры ПО
Опыт работы с командной строкой и npm-скриптами
Цели обучения: Объяснить пять типовых сбоев вайб-кодинга и механизм их устранения через SDD (Specification-Driven Development)
Сформулировать ответы на семь контрольных вопросов для проверки готовности спецификации фичи к реализации
Составить полноценную мини-спецификацию фичи в формате requirements/plan/validation для проекта на Qwen Code
Провести различие между SDD на уровне фич и классической водопадной моделью проектирования
Применить практическое правило определения необходимости спецификации для конкретного изменения в коде
Обзор: Этот модуль посвящён переходу от хаотичного вайб-кодинга к дисциплинированной разработке по спецификациям (SDD) при работе с AI-агентами, в частности с Qwen Code. Вайб-кодинг — подход, при котором разработчик даёт последовательные импульсивные команды ИИ, теряя архитектурный контекст и накапливая технический долг. SDD решает эту проблему через создание версионируемых, проверяемых и агент-читаемых документов, которые фиксируют намерения, границы, принятые решения и критерии приёмки. Модуль охватывает типовые патологии вайб-кодинга, структуру устойчивого цикла работы с Qwen Code, семь вопросов качества спецификации, критерии избыточности SDD и практику написания мини-спецификаций.
Ключевые концепции: Вайб-кодинг (vibe coding): Подход к разработке с AI-ассистентами, основанный на непрерывной импровизации: разработчик даёт короткие команды в чат, агент немедленно выполняет, контекст существует только внутри эфемерной сессии. Полезен для прототипирования и исследования, но порождает пять критических сбоев: смещение намерения, распад контекста, непроверяемый результат, скрытые решения, усталость рецензента.
Sdd (specification-driven development): Методология разработки, при которой AI-агент получает не только команду «сделай», но и структурированный контекст в виде версионируемых файлов: миссия проекта, технический стек, дорожная карта, спецификации отдельных фич. Переносит знания из эфемерной переписки в репозиторий, делает ошибки ранними, маленькими и проверяемыми.
Смещение намерения: Типовой сбой вайб-кодинга: агент интерпретирует «простую форму» как повод добавить сложное управление состоянием, новую библиотеку, альтернативный стиль интерфейса — всё то, что разработчик не просил, но агент счёл разумным.
Распад контекста: Потеря архитектурных решений между сессиями работы с агентом. Через несколько итераций агент забывает, почему проект не использует ORM, почему API рендерит HTML на сервере, почему выбран конкретный стек — и принимает противоречащие решения заново.
Устойчивый цикл работы с qwen code: Альтернатива длинной импровизационной сессии: три разделённых фазы с принудительной очисткой контекста (/clear). Фаза 1 — чтение базовых спецификаций и создание плана фичи с уточняющими вопросами. Фаза 2 — реализация строго ограниченного подмножества задач по конкретному плану. Фаза 3 — валидация результата по заранее зафиксированным критериям с перечислением расхождений перед исправлениями.
Мини-спецификация фичи: Компактный документ (не 80 страниц водопада), ориентированный на одну фазу, одну ветку, одно слияние. Состоит из трёх файлов: requirements.md (требования и границы), plan.md (план реализации), validation.md (критерии проверки). Характеристики: маленькая, проверяемая, связанная с дорожной картой, понятная новому агенту без предыдущего чата, достаточно строгая чтобы исключить угадывание.
Семь вопросов спецификации: Проверочный список содержательной готовности: (1) бизнес-намерение за фичей, (2) пользователь и сценарий, (3) границы работы, (4) принятые и открытые решения, (5) неослабляемые ограничения, (6) что не должно сломаться, (7) как доказать корректность результата. Отсутствие ответа на любой вопрос означает неготовность к реализации.
Отрицательные требования: Фиксация существующего поведения, которое фича не должна задевать. Критически важны для предотвращения регрессий при работе с агентами, склонными к широким изменениям. Подробнее раскрываются в части 7 курса.
Практическое правило избыточности: Эвристика определения необходимости спецификации: если изменение понятно и проверяется за 5 минут — достаточно обычного запроса; если затрагивает архитектуру, данные, безопасность, публичное поведение или несколько файлов — требуется спецификация; если агент работает автономно дольше нескольких минут — спецификация почти всегда окупается.
Границы и за границами: Явно перечисленные включения и явные исключения в спецификации фичи. Защищают от расползания объёма работ (scope creep) и не позволяют агенту «додумывать» функциональность, которую разработчик не заказывал.
Практические упражнения: Название: Диагностика сбоя вайб-кодинга
Проблема: Прочитайте следующий сценарий и определите, какой из пяти типовых сбоев вайб-кодинга произошёл: Разработчик просит агента «добавить отзывы к товарам». Агент создаёт полноценную систему рейтингов с модерацией, уведомлениями, аналитикой и интеграцией с внешним сервисом. Разработчик хотел только отображение текстовых отзывов под карточкой товара. В следующей сессии агент предлагает заменить существующую SQLite на PostgreSQL для «масштабируемости». Разработчик тратит 2 часа на откат изменений.
Решение: Шаг 1: Идентифицируем первый сбой — агент добавил несвязанную функциональность (рейтинги, модерация, уведомления, аналитика, внешний сервис) вместо запрошенного минимума. Это классическое смещение намерения: интерпретация «отзывы» как повод для экосистемы. Шаг 2: Идентифицируем второй сбой — в новой сессии агент не помнит/не учитывает решение о SQLite, предлагая PostgreSQL. Это распад контекста: архитектурное решение о стеке хранения утрачено. Шаг 3: Идентифицируем третий сбой — результат требует 2 часа на откат, значит изменения были непроверяемыми по объёму и непредсказуемыми по последствиям (непроверяемый результат + усталость рецензента). Шаг 4: Предложим SDD-решение: создать specs/2026-05-08-reviews-display/requirements.md с явными границами («только отображение», «без рейтингов», «без модерации в этой фазе»), зафиксировать решение о SQLite в tech-stack.md, создать validation.md с проверкой отсутствия новых зависимостей.
Сложность: intermediate
Название: Составление мини-спецификации входа администратора
Проблема: Возьмите фичу «Добавь вход» из примера курса. Преобразуйте импульсивный запрос в полноценную мини-спецификацию с тремя файлами: requirements.md, plan.md, validation.md. Используйте семь вопросов как проверку содержания. Затем сформулируйте три уточняющих вопроса, которые вы бы задали агенту перед началом реализации.
Решение: Шаг 1: requirements.md — структура: # Требования — вход администратора; ## Границы (одна страница входа, cookie-сессия, без самостоятельной регистрации, без сброса пароля в этой фазе); ## За границами (OAuth, JWT, регистрация пользователей, сброс пароля, многофакторная аутентификация); ## Решения (один администратор в SQLite, httpOnly cookie, защита только /dashboard); ## Проверка (тестовые сценарии). Шаг 2: plan.md — декомпозиция на группы задач: (1) схема данных и модель пользователя, (2) маршруты /login и /dashboard с middleware, (3) форма и валидация, (4) тесты. Шаг 3: validation.md — конкретные проверки: неаутентифицированный GET /dashboard → 302 на /login; неверный пароль → общее сообщение об ошибке без утечки существования пользователя; верный пароль → httpOnly cookie + 302 на /dashboard; npm test и npm run typecheck проходят; отсутствие новых зависимостей кроме bcrypt и cookie-parser. Шаг 4: Проверка по семи вопросам: (1) намерение — ограниченный доступ к админ-панели, (2) пользователь — единственный администратор, (3) границы — явно перечислены, (4) решения — SQLite, cookie, bcrypt зафиксированы, (5) ограничения — httpOnly, защита только /dashboard, (6) отрицательные требования — не ломаем публичные страницы, (7) доказательство — 4 тестовых сценария + CI-проверки. Шаг 5: Уточняющие вопросы агенту: «Подтверди, что понимаешь: без сброса пароля в этой фазе означает отсутствие маршрута /forgot-password и отсутствие интеграции с email-сервисом»; «Предложи альтернативу bcrypt с обоснованием, если считаешь её неоптимальной для SQLite»; «Как ты проверишь, что cookie действительно httpOnly и не доступна из document.cookie?»
Сложность: intermediate
Название: Проектирование устойчивого цикла для фичи
Проблема: У вас есть проект блога на Next.js с дорожной картой: фаза 1 — базовые посты, фаза 2 — комментарии, фаза 3 — теги и поиск. Вы хотите реализовать фазу 2 (комментарии). Спроектируйте три сессии Qwen Code с использованием /clear, укажите какие файлы спецификаций читает агент в каждой сессии, и какие конкретные инструкции получает. Обоснуйте разделение на три сессии.
Решение: Шаг 1: Сессия «Исследование и планирование» — /clear; чтение @specs/mission.md (цель проекта: минималистичный блог с фокусом на читаемость), @specs/tech-stack.md (Next.js 14 App Router, Prisma + PostgreSQL, Tailwind, React Server Components по умолчанию), @specs/roadmap.md (фаза 1 завершена, фаза 2 — комментарии, фаза 3 — теги). Инструкция: «Создай спецификацию фичи для фазы 2 дорожной карты. Сначала задай мне вопросы по неясностям. Не пиши код.» Обоснование: агент должен понять контекст проекта, не смешивая его с предыдущими сессиями, и сформулировать неоднозначности до реализации. Шаг 2: Сессия «Реализация» — /clear; чтение @specs/mission.md, @specs/tech-stack.md, @specs/2026-05-15-comments/plan.md (созданный в сессии 1). Инструкция: «Реализуй только группы задач 1 и 2 плана: схема Prisma для комментариев и API-маршрут POST /api/posts/[id]/comments. Не меняй несвязанные файлы. Не добавляй UI в этой сессии.» Обоснование: ограничение объёма работ предотвращает смещение намерения, чёткие границы защищают от расползания. Шаг 3: Сессия «Валидация» — /clear; чтение @specs/2026-05-15-comments/validation.md. Инструкция: «Сравни текущую реализацию с validation.md. Перед исправлениями перечисли расхождения. Затем предложи минимальные правки.» Обоснование: отдельная сессия проверки предотвращает импульсивные исправления, форсирует явное признание проблем, защищает от усталости рецензента через структурированный протокол.
Сложность: advanced
Название: Применение практического правила избыточности
Проблема: Оцените по практическому правилу, требуется ли полноценная спецификация (requirements/plan/validation) для каждого из следующих изменений: (A) Исправление опечатки в заголовке главной страницы; (B) Добавление поля «биография» в профиль пользователя с валидацией длины 500 символов; (C) Переход с SQLite на PostgreSQL для поддержки конкурентных записей; (D) Создание одноразового скрипта миграции данных для внутреннего использования; (E) Реализация платёжной интеграции Stripe для подписок.
Решение: Шаг 1: (A) Исправление опечатки — изменение одного файла, понятно за 30 секунд, проверяется визуально. Практическое правило: < 5 минут, одноразовое, не затрагивает архитектуру. Решение: обычный запрос, без спецификации. Шаг 2: (B) Поле биографии — затрагивает схему данных, валидацию, форму, API, возможно тесты. Но изменение локализовано, шаблонное, агент работает < 5 минут. Границы очевидны. Решение: лёгкий запрос с контекстом в чате может быть достаточен, но минимальная фиксация в requirements.md повышает надёжность. Пограничный случай — можно обойтись без полного цикла. Шаг 3: (C) Переход SQLite → PostgreSQL — архитектурное решение, затрагивает данные, конфигурацию, возможно ORM-запросы, тесты, CI/CD. Агент будет работать долго, ошибки дороги. Решение: полная спецификация с явными решениями, отрицательными требованиями (что не ломаем), планом миграции, валидацией. Шаг 4: (D) Одноразовый скрипт миграции — внутренний, одноразовый, проверяется по результату. Но если агент работает автономно и трогает продакшен-данные, риск высок. Решение: если скрипт простой и данные не критичные — лёгкий запрос; если сложная логика или продакшен — минимальная спецификация с проверкой на копии данных. Шаг 5: (E) Платёжная интеграция Stripe — безопасность, публичное поведение, внешний сервис, деньги пользователей, юридические последствия ошибок. Решение: обязательная полная спецификация с явными границами (какие платежи, какие валюты, какие вебхуки), зафиксированными решениями (Stripe SDK vs API, обработка ошибок), неослабляемыми ограничениями (PCI compliance, idempotency keys), отрицательными требованиями (не храним CVV, не обрабатываем платежи синхронно), детальной валидацией.
Сложность: intermediate
Кейсы: Название: Миграция стартапа с вайб-кодинга на SDD: спасение проекта через спецификации
Сценарий: Стартап EdTech разрабатывал платформу для онлайн-курсов с помощью Claude и GitHub Copilot в режиме вайб-кодинга. За 4 месяца команда из 2 разработчиков создала работающий MVP: авторизация, видеоплеер, прогресс обучения, платежи. Проект рос импульсивно: каждая фича добавлялась по запросу «сделай X», архитектурные решения принимались агентом на лету без документации.
Задача: На 5-м месяце команда столкнулась с критическими проблемами: (1) Смещение намерения — система платежей содержала 3 разных подхода (Stripe Checkout, Stripe Elements, самописная форма), потому что в разных сессиях агенты выбирали разные решения; (2) Распад контекста — новый разработчик не мог понять, почему видеоплеер использует кастомный формат хранения прогресса вместо стандартного; (3) Непроверяемый результат — релиз содержал 47 изменённых файлов, ревью занимало 6 часов, ошибки просачивались в продакшен; (4) Скрытые решения — критическое решение о шардировании базы данных осталось только в истории чата ушедшего разработчика; (5) Усталость рецензента — CTO прекратила ночные релизы из-за невозможности гарантировать качество.
Решение: Команда внедрила SDD за 3 недели: (1) Ретроспектива — извлечение скрытых решений из историй чатов, фиксация в specs/mission.md, specs/tech-stack.md, specs/architecture-decisions/; (2) Дорожная карта — декомпозиция оставшихся фич на фазы с явными границами; (3) Мини-спецификации — каждая фича получила requirements/plan/validation, проверяемые по семи вопросам; (4) Устойчивый цикл — внедрение /clear между сессиями, разделение на планирование/реализацию/валидацию; (5) Автоматизация проверки — npm-скрипты и GitHub Actions для обязательного прохождения validation.md перед merge.
Результат: Через 2 месяца: время ревью сократилось с 6 часов до 45 минут; количество релизных багов упало на 70%; новый разработчик влился в проект за 3 дня вместо 3 недель; удалось удалить 2 из 3 платёжных систем без регрессий благодаря отрицательным требованиям. CTO возобновила ночные релизы с уверенностью. Проект привлёк раунд А.
Извлечённые уроки: Вайб-кодинг имеет скрытую стоимость: каждая сэкономленная минута на спецификации превращается в часы ревью и отката на горизонте 3-6 месяцев
Семь вопросов спецификации работают как ранний детектор неоднозначности: если агент задаёт неожиданные вопросы при проверке requirements.md, значит спецификация ещё не готова
Разделение сессий с /clear критически важно для предотвращения смешения контекстов: даже «умный» агент путает приоритеты, когда в одной сессии совмещены планирование, реализация и исправление багов
Отрицательные требования — наиболее недооценённый компонент: явное указание «что не делаем» защищает от расползания лучше, чем перечисление «что делаем»
SDD окупается не мгновенно, а через накопление версионируемого контекста: выгода растёт экспоненциально с размером команды и возрастом проекта
Связанные концепции: Вайб-кодинг (Vibe Coding)
Семь вопросов спецификации
Устойчивый цикл работы с Qwen Code
Отрицательные требования
Практическое правило избыточности
Название: Провал интеграции OAuth: когда «Добавь вход» обходится дороже спецификации
Сценарий: Инди-разработчик создавал SaaS для фрилансеров — трекер времени с инвойсингом. На этапе подготовки к публичному запуску потребовалась авторизация. Разработчик дал Claude импульсивный запрос: «Добавь вход через Google».
Задача: Агент реализовал полноценную OAuth 2.0 интеграцию с Google, включая: регистрацию новых пользователей через Google, связку существующих аккаунтов, обновление токенов, доступ к Google Calendar для импорта событий, профиль с аватаром из Google. Проблемы: (1) Разработчик хотел только аутентификацию, не авторизацию данных Calendar; (2) Связка аккаунтов создала уязвимость: пользователь А мог привязать email пользователя Б, если тот ранее входил по паролю; (3) Обновление токенов требовало cron-задачи, не задокументированной в инфраструктуре; (4) Регистрация через Google обошла обязательное поле «часовой пояс», критичное для инвойсинга; (5) Откат занял 8 часов, включая восстановление базы данных из бэкапа.
Решение: После инцидента разработник применил SDD- подход: создал specs/auth/requirements.md с границами (только аутентификация, без доступа к данным Google, без самостоятельной регистрации в этой фазе), зафиксировал решение о приоритете email-пароль над OAuth в первом релизе, описал отрицательные требования (не ломаем существующих пользователей, не требуем часовой пояс при OAuth-входе). План содержал 2 группы задач вместо 8, валидация — 5 конкретных проверок включая проверку отсутствия новых scopes в Google Console.
Результат: Повторная реализация заняла 2 часа вместо 8 часов отката + неопределённого времени на исправление. Спецификация предотвратила 3 из 5 проблем до написания кода (доступ к Calendar, связка аккаунтов, требование часового пояса). 2 оставшиеся проблемы были пойманы на этапе валидации за 15 минут. Разработник оценил, что написание спецификации заняло 25 минут — экономия в 12 раз относительно отката.
Извлечённые уроки: Импульсивный запрос «Добавь X» дешев только в моменте: полная стоимость включает откат, исправление, восстановление данных и репутационные потери
Агенты склонны к «полезным» расширениям, которые разработчик не заказывал: OAuth естественно тянет за собой профили, интеграции, синхронизации
25 минут на спецификацию — это инвестиция с ROI > 1000% при первом же серьёзном сбое
Отрицательные требования в форме «без доступа к данным Google» конкретнее и проверяемее, чем «только аутентификация»
Валидация через сравнение реализации с заранее зафиксированным списком защищает от «кажется нормально» при усталости рецензента
Связанные концепции: Смещение намерения
Границы и за границами
Практическое правило избыточности
Семь вопросов спецификации
Мини-спецификация фичи
Советы по изучению: Проходите материал последовательно: сначала осознайте проблемы вайб-кодинга через собственный опыт или кейсы, затем изучайте SDD как системное решение, а не как бюрократию
Ведите «дневник вайб-кодинга» — фиксируйте свои импульсивные запросы к AI в течение недели, затем анализируйте: какие привели к откату? какие можно было бы формализовать за 10 минут?
Практикуйте семь вопросов на реальных или вымышленных фичах: возьмите любую фичу из своего текущего проекта и проверьте, можете ли вы ответить на все семь вопросов за 5 минут. Если нет — спецификация нужна
Используйте технику «красная команда»: после написания спецификации попросите агента или коллегу найти в ней неоднозначности, через которые реализация может уйти в сторону. Это тренирует критическое мышление
Создайте шаблоны для трёх файлов спецификации в своём редакторе или сниппетах: requirements.md, plan.md, validation.md. Автоматизация создания снижает порог входа в SDD
Практикуйте разделение сессий буквально: закрывайте чат, открывайте новый с /clear, даже если «продолжение» кажется эффективнее. Измерьте разницу в качестве результата
Изучайте отрицательные требования отдельно: это наиболее контринтуитивная часть, требующая привычки думать «что я НЕ хочу» вместо «что я хочу»
Сравнивайте SDD с водопадом активно: водопад пытается предсказать будущее, SDD фиксирует достаточный контекст для следующего шага. Это разные логики, не разные масштабы
Измеряйте метрики: время ревью, количество багов в релизе, время онбординга нового разработчика. SDD оправдывается метриками, не интуицией
Начинайте с одной фичи: не пытайтесь покрыть весь проект спецификациями сразу. Выберите следующую нетривиальную фичу, пройдите полный цикл, измерьте результат, затем масштабируйте
Дополнительные ресурсы: Оригинальный курс по sdd: Материалы курса, из которого извлечена данная часть — фундамент для погружения в контекстно-зависимую разработку с AI-агентами
Документация qwen code: Официальные материалы по работе с контекстом, командами /clear, @-ссылками на файлы — техническая основа устойчивого цикла
«writing great specifications» by kamil nicieja: Книга о спецификациях в классическом смысле, применимая к AI-агентам с адаптацией масштаба
Adr (architecture decision records): Формат фиксации архитектурных решений — дополняет SDD на уровне проекта, защищает от распада контекста между фичами
«the checklist manifesto» by atul gawande: Книга о силе чек-листов в сложных системах — семь вопросов спецификации как чек-лист качества
Примеры спецификаций open-source проектов: Изучение того, как команды фиксируют границы фич в RFC (Request for Comments) — параллель с мини-спецификациями SDD
Курс по проектированию api (api design patterns): Помогает формулировать неослабляемые ограничения в спецификациях, особенно для фич с внешними интерфейсами
Резюме: Разработка по спецификациям (SDD) — это ответ на фундаментальное ограничение вайб-кодинга: эфемерность контекста. AI-агенты пишут код быстро, но без устойчивой памяти о намерениях, границах и принятых решениях. SDD переносит этот контекст в версионируемые файлы, создавая «карту проекта» для агента. Ключевые практики: устойчивый цикл с /clear и разделёнными сессиями планирования/реализации/валидации; мини-спецификации фич вместо монолитного проектирования; семь вопросов как проверка готовности; явные границы и отрицательные требования для защиты от расползания; практическое правило избыточности для экономии усилий. SDD не делает агента безошибочным — оно делает ошибки ранними, маленькими и проверяемыми. Внедрение требует дисциплины, но окупается экспоненциально с ростом проекта и команды.