Тема: Глоссарий SDD (Spec-Driven Development)
Уровень сложности: Средний
Расчётное время изучения: 6-8 часов (теория + практика)
Предварительные требования: Базовое понимание разработки программного обеспечения
Опыт работы с системами контроля версий (Git)
Знакомство с принципами работы ИИ-агентов в разработке
Понимание базовых концепций тестирования и валидации
Цели обучения: Самостоятельно создать полный набор артефактов SDD (mission.md, tech-stack.md, roadmap.md) для учебного проекта
Сформулировать не менее 5 проверяемых фактов в validation.md с правильным распределением по уровням (пример, инвариант, свойство, контракт)
Идентифицировать и устранить не менее 3 антипаттернов SDD в предоставленном фрагменте документации
Разработать правила эскалации для QWEN.md, покрывающие все критические сценарии из глоссария
Обзор: Глоссарий SDD — это сводный словарь терминов методологии Spec-Driven Development, служащий единым источником истины для всех участников процесса разработки с применением ИИ-агентов. Он охватывает три ключевые области: артефакты проектной документации (конституция проекта, спецификации фич и исправлений), жизненный цикл фактов и их валидацию, а также инструменты и процессы работы с агентами (Qwen Code). Глоссарий решает критическую проблему «разночтений» — когда разные части команды или сам агент трактуют термины по-разному, что приводит к отклонению (drift) реализации от спецификации. Каждый термин определён так, чтобы быть исполняемым или однозначно проверяемым, что отражает фундаментальный принцип SDD: спецификация существует для управления, а не для отчётности.
Ключевые концепции: Конституция проекта: Три файла в specs/ — mission.md (зачем и для кого), tech-stack.md (как), roadmap.md (что и в каком порядке). Ключевое ограничение: меняется только в фазе перепланирования, что предотвращает хаотичные изменения в середине разработки фичи. Это архитектурный аналог конституции государства — основной закон, требующий особой процедуры для изменения.
Спецификация фичи: Папка specs/YYYY-MM-DD-feature-name/ с тремя обязательными файлами: requirements.md (границы и решения), plan.md (пронумерованные группы задач), validation.md (факты и критерии готовности). Дата в названии обеспечивает хронологический порядок и предотвращает коллизии имён.
Спецификация исправления: Отдельный тип спецификации для багфиксов с обязательными разделами: «Текущее поведение», «Ожидаемое поведение», «Доказательство первопричины», «Что не должно измениться», «Сценарии регрессии». Критическое отличие от фичи — наличие факт-репро в validation.md: команда, которая до исправления падает, а после проходит.
Отрицательные требования: Раздел, описывающий что не должно измениться при реализации. В фиче — «За границами», в багфиксе — «Что не должно измениться». Защищает от «улучшений по дороге» — характерного поведения агентов, которые видят «очевидное» улучшение и вносят его без разрешения, ломая совместимость.
Факт и уровни фактов: Исполняемое или однозначно проверяемое утверждение. Четыре уровня: пример (конкретная пара вход-выход), инвариант (всегда истинно), свойство (класс случаев), контракт (формальная связка условие-действие-результат). Статусы: draft → spec → implemented → deferred.
Усталость от ии: Утомление человека от объёма изменений, которые агент производит быстрее, чем человек способен проверять. SDD борется с ней через маленькие фазы, явные границы и факт-проверку — снижение когнитивной нагрузки на ревьюера.
Отклонение (drift): Расхождение реализации со спецификацией. Три вида: в коде (реализация не соответствует плану), в фактах (тесты проверяют не то), в самой спецификации (правила проекта изменились, фича — нет). Требует регулярного аудита.
Правила эскалации: Записанный в QWEN.md или навыке список ситуаций, когда агент обязан остановиться и вернуть управление человеку: неоднозначные требования, отсутствие факта в validation.md, конфликт с tech-stack.md, разрушительные команды, новые зависимости. Без них агент молча принимает необратимые решения.
Деградация контекста (context rot): Ухудшение качества ответов модели на длинном нерелевантном контексте. Практические следствия: /clear между ролями, инъекция только релевантных записей в QWEN.md, ограничение длины подмешиваемого контекста.
Шкала зрелости sdd: Описательная шкала от 0 («вайб-кодинг») до 4 («обучаемый процесс»). Учебник ставит целью уровень 2 на дидактическом проекте. Используется как зеркало для приоритизации улучшений — не для сертификации, а для понимания, какой шаг даст максимальный эффект.
Практические упражнения: Название: Создание конституции проекта
Проблема: Вам поручили начать новый проект — веб-приложение для управления задачами (Task Tracker) с ИИ-ассистентом. Создайте три файла конституции проекта в specs/. Для mission.md определите: назначение (упрощение планирования для малых команд), аудитория (фрилансеры и стартапы до 10 человек), тон (деловой, без излишней технической детализации), определение успеха (пользователь создаёт первый проект за <5 минут). Для tech-stack.md выберите стек и зафиксируйте ограничения (например, «без serverless-функций, только монолит»). Для roadmap.md определите 4 фазы: MVP (авторизация + проекты + задачи), Интеграции (календарь, уведомления), ИИ-фичи (автоприоритизация), Масштабирование (команды >10 человек).
Решение: 1. Создайте директорию specs/ в корне репозитория. 2. Напишите mission.md с чёткими измеримыми критериями — «<<5 минут» вместо «быстро». 3. В tech-stack.md явно запишите не только выбранные технологии, но и отклонённые с причиной («не Kubernetes — избыточно для MVP, усложняет деплой агентом»). 4. В roadmap.md каждая фаза должна иметь статус (proposed/active/completed/deferred) и критерий перехода к следующей. 5. Проверьте: можно ли изменить tech-stack.md в середине фичи? Нет — только в перепланировании. Это и есть защита от drift.
Сложность: intermediate
Название: Диагностика антипаттернов в документации
Проблема: Вам передали следующий фрагмент validation.md от другой команды. Найдите и классифицируйте антипаттерны:
# validation.md для фичи "Экспорт в PDF"
## Факты
1. Экспорт работает корректно.
2. После экспорта пользователь доволен.
3. Если файл большой, система не падает (проверено на 100 МБ).
4. [После бага QWEN-42] Файл не должен превышать 50 МБ.Также в проекте обнаружены: QWEN.md на 500 строк без структуры; навык deploy который вызывается без чтения SKILL.md; хук, который молча выполняет git push --force.
Решение: Антипаттерны в validation.md: (1) «Экспорт работает корректно» — не факт, неисполняемо, нет способа проверить (ритуальный validation.md); (2) «пользователь доволен» — субъективно, не однозначно проверяемо; (3) ослабление факта после ошибки — был 100 МБ, стал 50 МБ без объяснения, вместо исправления производительности; (4) отсутствие факт-репро для багфикса. В проекте: QWEN.md как свалка — разбить на секции с оглавлением, регулярно архивировать устаревшее; навык как магическая кнопка — ввести обязательное логирование вызова с хешем SKILL.md; хук без обратной связи — добавить подтверждение человека и логирование в чат.
Сложность: intermediate
Название: Формулировка фактов разных уровней
Проблема: Для фичи «Автоматическое резервное копирование БД» сформулируйте по одному факту каждого уровня: пример, инвариант, свойство, контракт. Каждый факт должен быть исполняемым или однозначно проверяемым.
Решение: Пример: «При запуске команды backup create --name=test в 2024-01-15T10:00:00Z создан файл /backups/test_2024-01-15T10-00-00.sql размером 1.2 МБ с хешем sha256:abc123». Инвариант: «После любой операции backup create количество файлов в /backups/ увеличивается ровно на 1». Свойство: «Для любого имени резервной копии длиной 1-64 символов, содержащего только [a-z0-9-], команда backup create завершается с кодом 0 и создаёт файл». Контракт: «При условии, что диск /backups/ заполнен менее чем на 90%, действие backup create приводит к созданию валидного архива; при заполненности ≥90% — к ошибке с кодом DISK_FULL и отсутствию частичных файлов».
Сложность: intermediate
Название: Проектирование правил эскалации
Проблема: Ваш агент Qwen Code работает над интеграцией платёжной системы. История показывает, что агент трижды: (1) подключил неправильное API из-за неоднозначности в требованиях, (2) обновил tech-stack.md прямо в ветке фичи, (3) выполнил DROP TABLE в продакшене, считая это «миграцией». Сформулируйте 5 правил эскалации для QWEN.md.
Решение: 1. Неоднозначность требований: при наличии двух или более интерпретаций в requirements.md — остановиться, вывести цитаты с конфликтом, запросить уточнение. 2. Изменение tech-stack.md: запрещено в любой ветке кроме replan/*; при обнаружении diff в этом файле — остановиться, предупредить о нарушении конституции. 3. Разрушительные команды: любая команда содержащая DROP, TRUNCATE, DELETE без WHERE, rm -rf — требует явного подтверждения через промпт, даже в dev-окружении. 4. Новые зависимости: установка пакета, не указанного в tech-stack.md — эскалация с аргументацией необходимости. 5. Отсутствие факта в validation.md: если реализация требует проверки, для которой нет факта в статусе spec или implemented — остановиться, предложить добавить факт.
Сложность: advanced
Кейсы: Название: Спасение проекта от усталости от ИИ в стартапе TaskFlow
Сценарий: Стартап TaskFlow (5 разработчиков, 2 продукта) внедрил Qwen Code для ускорения разработки. За первый месяц агент произвёл 340 коммитов против обычных 80. Команда не справлялась с ревью: фичи мержились с багами, тесты писались постфактум, документация отставала. Ключевой инцидент: агент «улучшил» схему БД в ветке уведомлений, сломав авторизацию в продакшене.
Задача: Критическая усталость от ИИ: разработчики тратили 70% времени на ревью агентских коммитов, 20% на откаты, 10% на собственную работу. Отклонение (drift) достигло 40% — почти половина кода не соответствовала спецификациям или спецификации были устаревшими. Отсутствовали: конституция проекта, отрицательные требования, правила эскалации. validation.md существовал, но факты никто не запускал (ритуальный документ).
Решение: Внедрение SDD по глоссарию: (1) Экстренное перепланирование — создание конституции проекта с явным запретом изменения схемы БД вне фазы миграций. (2) Разбиение на фазы ≤3 дней каждая — снижение когнитивной нагрузки на ревью. (3) Обязательные отрицательные требования в каждой спецификации: «Схема users остаётся неизменной, новые таблицы только в отдельной миграции». (4) Правила эскалации: агент останавливается при затрагивании таблиц auth_* или при отсутствии факт-репро. (5) Пакет доказательств в MR: ссылка на спецификацию, скриншоты тестов, логи ручной проверки.
Результат: Через 6 недель: время ревью сократилось с 70% до 25% рабочего времени, drift снизился до 8%, количество инцидентов в продакшене — с 12 до 1 в месяц. Команда достигла уровня 2 шкалы зрелости SDD. Ключевой метрикой стал «коэффициент доверия» — процент MR, прошедших без доработок: вырос с 15% до 67%.
Извлечённые уроки: Усталость от ИИ не решается «более умным» агентом — только структурными ограничениями (границы, эскалация, маленькие фазы)
Отрицательные требования критичны для систем с legacy-компонентами — агенты склонны к «улучшениям» в чужих модулях
Пакет доказательств снимает с ревьюера обязанность воспроизводить сценарий с нуля — это инвестиция агента в доверие человека
Связанные концепции: Усталость от ИИ
Отрицательные требования
Правила эскалации
Отклонение (drift)
Пакет доказательств
Шкала зрелости SDD
Название: Миграция с «вайб-кодинга» на SDD в агентстве WebCraft
Сценарий: Агентство WebCraft (12 разработчиков, 30+ проектов) использовало Qwen Code в режиме «запросил — получил» без спецификаций. Проект интернет-магазина для клиента «ЭкоПродукт» вырос за 2 месяца до 15 000 строк кода, 0 тестов, документация в голове у одного разработчика. Клиент потребовал аудит — обнаружилось 47 критических рисков.
Задача: Уровень зрелости 0 по шкале SDD: отсутствие конституции, спецификации писались после кода для отчётности клиенту, QWEN.md был свалкой из 200 скопированных советов из интернета. Агенты конфликтовали друг с другом — разные разработчики имели разные «неписаные» правила в своих сессиях. Контекст деградировал: /clear использовался ритуально после каждого сообщения, теряя важные ограничения.
Решение: Пошаговая миграция по шкале зрелости: (1) Уровень 1 — введение mission.md и tech-stack.md для всех новых проектов, обучение 2 амбассадоров. (2) Уровень 2 — обязательные спецификации фич с validation.md, внедрение навыков с обязательным чтением SKILL.md. (3) Особое внимание к деградации контекста: /clear только при смене роли, внедрение структурированного QWEN.md с секциями и оглавлением. (4) Для legacy-проекта «ЭкоПродукт» — фаза перепланирования: создание конституции задним числом, документирование текущего поведения как «спецификации реальности», постепенное приведение к SDD.
Результат: Новые проекты выходили на уровень 2 за 2 недели. Legacy-проект «ЭкоПродукт» достиг уровня 1 через 3 месяца — не полный SDD, но предсказуемый процесс. Клиент продлил контракт. Внутренняя метрика: время onboarding нового разработчика сократилось с 3 недель до 3 дней благодаря явной конституции и спецификациям.
Извлечённые уроки: Миграция с уровня 0 возможна только пошагово — попытка внедрить всё сразу приводит к сопротивлению и обходу правил
Деградация контекста — не техническая проблема, а организационная: /clear ритуально использовался как «решение» от невозможности управлять контекстом
Спецификация после кода (антипаттерн) может быть трансформирована в валидную отправную точку, если честно задокументировать «что есть» как базовую линию
Связанные концепции: Шкала зрелости SDD
Конституция проекта
Деградация контекста
Спецификация после кода
Навык как магическая кнопка
QWEN.md как свалка
Советы по изучению: Создайте физическую или цифровую «карту связей» — термины глоссария тесно переплетены (например, отрицательные требования защищают от drift, который вызывает усталость от ИИ). Визуализация помогает запомнить причинно-следственные связи, а не изолированные определения.
Практикуйтесь на контрастных примерах: для каждого «хорошего» факта из глоссария сформулируйте «плохой» аналог. Например, хороший: «HTTP-статус 200 при GET /health»; плохой: «Система работает корректно». Это развивает чувство границы между исполняемым и ритуальным.
Используйте метод «воспроизведения антипаттерна»: намеренно напишите 5 строк «плохого» QWEN.md, затем 5 строк «хорошего». Контрастное обучение ускоряет распознавание проблем в реальных проектах.
Для понимания уровней фактов — практикуйтесь на бытовых примерах вне IT: «пример» = «эта конкретная кофеварка выдаёт 200 мл», «инвариант» = «объём всегда 180-220 мл», «свойство» = «для любого зёрна арабики результат питьевой», «контракт» = «при наличии воды — кофе, при отсутствии — ошибка и отключение».
Изучайте глоссарий в паре с реальным репозиторием — форкните учебный проект из учебника SDD и попробуйте найти каждый термин «вживую». Абстрактные определения закрепляются только через прикладной контекст.
Для аудитории с опытом классической разработки: проводите аналогии с известными практиками. Конституция проекта = архитектурное решение (ADR) с повышенной процедурой изменения. validation.md = Definition of Done с исполняемыми критериями. Правила эскалации = exception handling в организационном коде.
Дополнительные ресурсы: Учебник sdd (оригинал): Полный текст учебника с частями 1-21, включая детальные разборы каждого термина глоссария в контексте
Приложение a — sdd-диалекты: Сравнение учебного подхода с GitHub Spec Kit и AWS Kiro — помогает адаптировать глоссарий под существующие инструменты команды
Часть 11 — спецификация исправления: Углубленное рассмотрение bugfix.md, факт-репро и отрицательных требований в контексте багфиксов
Часть 14 — построение собственного workflow: Практическое применение правил эскалации, хуков, навыков и борьба с деградацией контекста
Часть 19 — агентная память sqlite: Расширение QWEN.md через структурированное хранилище — антипаттерн «память как скрытый источник истины» и как его избежать
Часть 20 — антипаттерны: Детальный разбор всех 12 антипаттернов с симптомами, последствиями и способами выхода
Часть 21 — заключение и шкала зрелости: Самооценочный инструмент для определения текущего уровня команды и планирования следующего шага
Резюме: Глоссарий SDD — это не просто словарь терминов, а операционная система для управления ИИ-агентами в разработке. Ключевые принципы: (1) Всё, что можно проверить, должно быть фактом — от примера до контракта. (2) Границы важнее возможностей: отрицательные требования защищают от непреднамеренных изменений. (3) Агент должен знать, когда остановиться — правила эскалации предотвращают необратимые ошибки. (4) Контекст управляется осознанно, а не ритуально — борьба с деградацией через структуру и чистку. (5) Зрелость измеряется практикой, а не декларациями — шкала от 0 до 4 помогает найти следующий шаг. Применение глоссария требует дисциплины, но возвращает предсказуемость в мир, где агенты производят изменения быстрее, чем человек способен их осмыслить.