Глоссарий

Сводный список терминов учебника. Используется как опора в любой части — определения дублируются здесь, чтобы не плодить разночтения в тексте.

Артефакты SDD

Конституция проекта — три файла в specs/, фиксирующие долговременные решения: mission.md (зачем и для кого), tech-stack.md (как), roadmap.md (что и в каком порядке). Меняется только в фазе перепланирования.

**mission.md** — назначение, аудитория, тон, определение успеха.

**tech-stack.md** — язык, среда, фреймворк, база данных, тестирование, ограничения. Если решение не записано здесь, оно может быть домыслено агентом.

**roadmap.md** — упорядоченные фазы со статусами. Каждая фаза — кандидат на отдельную ветку фичи.

Спецификация фичи — папка specs/YYYY-MM-DD-feature-name/ с тремя файлами:

• **requirements.md** — границы, то, что в них не входит, решения именно этой фичи, контекст.
• **plan.md** — пронумерованные группы задач для реализации.
• **validation.md** — набор фактов и критериев готовности (см. ниже).

**QWEN.md** — постоянный контекст Qwen Code: правила поведения агента в этом репозитории.

**AGENTS.md** — общий контракт для любого ИИ-агента. Qwen Code читает оба файла, если они присутствуют.

**CHANGELOG.md (проекта)** — журнал изменений учебного проекта. Обновляется навыком changelog перед слиянием.

Спецификация исправления — папка specs/YYYY-MM-DD-bugfix-name/ с файлами bugfix.md, plan.md, validation.md. Применяется вместо обычной спецификации фичи, когда задача — починить уже работающее поведение, а не добавить новое. В bugfix.md обязательны разделы «Текущее поведение», «Ожидаемое поведение», «Доказательство первопричины», «Что не должно измениться», «Сценарии регрессии». В validation.md обязателен факт-репро: команда или сценарий, который до исправления падает, а после проходит. Подробнее — в части 11.

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

Жизненный цикл фактов

Факт — исполняемое или однозначно проверяемое утверждение, по которому можно вынести однозначный вердикт «прошло / не прошло». Командой, тестом, HTTP-статусом, инвариантом БД.

Уровни фактов в validation.md:

• Пример — конкретная пара вход-выход.
• Инвариант — то, что всегда истинно (после действия, в любом состоянии БД и т.п.).
• Свойство — проверяет класс случаев.
• Контракт — формальная связка «при условии X, действие Y приводит к Z».

Статусы факта:

• draft — предложен, но ещё не принят.
• spec — принят как обязательный для фичи.
• implemented — есть тест, команда или ручное подтверждение.
• deferred — осознанно перенесён в будущую фазу.

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

Процессы

Перепланирование — отдельная ветка между фичами, в которой обновляются mission.md, tech-stack.md, roadmap.md, политика тестирования, журнал изменений. Не реализует продуктовые фичи.

MVP-фаза — собрать минимально жизнеспособную версию из нескольких фаз сразу. Стресс-тест зрелости спецификаций; рискованнее обычной фичи.

Усталость от ИИ (раньше встречалось как калька от AI fatigue) — утомление человека от объёма изменений, которые агент производит быстрее, чем человек способен проверять. SDD снижает её через маленькие фазы, явные границы и факт-проверку.

Отклонение (англ. drift) — расхождение реализации со спецификацией. Бывает в коде, в фактах и в самой спецификации (когда правила проекта успели измениться, а фича — нет).

Правила эскалации — записанный в QWEN.md или в навыке список ситуаций, при которых агент обязан остановиться и вернуть управление человеку: неоднозначные требования, отсутствие нужного факта в validation.md, конфликт со specs/tech-stack.md, необходимость разрушительной команды, новая зависимость. Без этих правил агент склонен молча принимать решения, которые потом приходится откатывать. Подробнее — в части 14.

Шкала зрелости SDD — короткая описательная шкала состояния процесса в команде, от 0 («вайб-кодинг») до 4 («обучаемый процесс»). Не претендует на канон; используется как зеркало, чтобы заметить, какой шаг сейчас даст больше всего. Цель учебника — довести команду до уровня 2 на дидактическом проекте. Подробнее — в части 21.

Инструменты Qwen Code

Навык (Skill) — директория с SKILL.md, описывающая, когда и как агент должен применять конкретный процесс. Личный (~/.qwen/skills/) или проектный (.qwen/skills/).

Хук (Hook) — команда оболочки, которую Qwen Code выполняет при наступлении события (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop и др.). Полезен для логирования, добавления контекста, охраны границ.

MCP — Model Context Protocol; внешний слой инструментов и источников данных, подключаемых к агенту через mcpServers в settings.json или qwen mcp add.

ACP — Agent Client Protocol; протокол связи агента и IDE/клиента. Используется, например, при работе Qwen Code из JetBrains.

Режим без интерфейса (англ. headless) — qwen -p "..."; запускает агента без интерактивной сессии, для автоматизации и CI.

Деградация контекста (англ. context rot) — наблюдаемое в исследованиях ухудшение качества ответов модели по мере роста входа: на длинном нерелевантном контексте релевантные куски находятся хуже, чем на коротком сфокусированном. Практические следствия в учебнике: /clear между ролями, инъекция в QWEN.md только релевантных записей памяти, ограничение длины подмешиваемого контекста. Подробнее — в части 14 и части 19.

Внешние SDD-фреймворки

GitHub Spec Kit — открытый фреймворк со стандартным циклом /constitution → /specify → /clarify → /plan → /tasks → /analyze → /implement.

AWS Kiro — IDE с собственной моделью SDD: spec'и (requirements.md + design.md + tasks.md), steering-файлы, агентные хуки.

Соответствие учебника со Spec Kit и Kiro см. в Приложении A.

Антипаттерны (см. часть 20)

• Спецификация после кода — артефакт пишется для отчётности, а не для управления.
• **Гигантский requirements.md** — спецификация на 50 пунктов, никто не запускает.
• **validation.md, который никто не запускал** — факты теоретические.
• Ослабление фактов после ошибки — переписывание факта вместо исправления кода.
• **Ритуальный /clear** — очистка контекста без понимания, что она реально делает.
• Навык как магическая кнопка — команда зовёт навык, не читая SKILL.md.
• **QWEN.md как свалка** — превращается в нечитаемое полотно, агент перестаёт следовать главному.
• Хук, который молча меняет проект — без логирования, без обратной связи человеку.
• Память как скрытый источник истины — обязательные правила живут только в SQLite, а не в спецификациях.

• MCP без задачи — подключают, потому что можно.
• Слишком большой MVP — без зрелости спецификаций.