# Глоссарий

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

## Артефакты 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](part-11-second-feature-phase.md).

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

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

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

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

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

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

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

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

## Процессы

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

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

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

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

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

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

## Инструменты 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](part-14-build-your-own-workflow.md) и [части 19](part-19-agent-memory-sqlite.md).

## Внешние 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](appendix-a-sdd-dialects.md).

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

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