# Часть 1. Введение

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

В SDD главным артефактом становится спецификация. Код остаётся важным, но появляется как результат исполнения спецификации. Человек отвечает за намерение, ограничения, критерии приёмки и контроль качества. Агент отвечает за скорость, поиск по коду, рутинную реализацию и механические изменения.

В этом учебнике мы будем использовать Qwen Code CLI. Сама методика SDD не привязана к конкретному агенту: её можно реализовать в Qwen Code, Claude Code, Codex CLI, Cursor, JetBrains AI Assistant. Qwen Code подходит для такой работы, потому что запускается из терминала, читает файлы проекта, поддерживает `QWEN.md`, команды `@file`, команды оболочки через `!`, режим без интерфейса, проектные навыки и MCP.

**Терминологическая договорённость.** В тексте слово «агент» означает Qwen Code CLI (или его аналог) — инструмент, который читает спецификации и пишет код. У учебного проекта AgentClinic есть свои внутри-доменные «агенты» — выдуманные ИИ-персонажи-пациенты клиники. Если из контекста неочевидно, будет уточнение «агент-инструмент» или «персонаж клиники».

## Как читать утверждения учебника

Учебник опирается на разные по силе утверждения. Чтобы не смешивать «как точно работает Qwen Code» с «как принято делать в команде» и с «что только пробуют», в спорных местах будут стоять пометки:

- **Стандарт.** Зафиксированное поведение инструмента или общепринятая практика SDD. Пример: «`QWEN.md` загружается при старте сессии Qwen Code» — стандарт.
- **Рекомендация.** Опытная практика, которая работает в большинстве случаев, но допускает разумные исключения. Пример: «фазу длиной больше двух дней разбивайте на две» — рекомендация.
- **Фронтир.** Подход, который применяют, но он ещё не устоялся; результат сильно зависит от команды. Пример: «полная автоматизация ревью через многоагентный конвейер» — фронтир.

Если пометки нет, считайте утверждение либо стандартом, либо рекомендацией. Фронтир будет помечен явно.

## Что вы построите

Учебный проект называется AgentClinic. Это сатирическое веб-приложение: ИИ-агенты приходят в клинику, чтобы восстановиться после работы с людьми. Пример смешной по содержанию, но технически серьёзный: TypeScript, Hono, серверный JSX, SQLite, Vitest, CSS, спецификации фич и журнал изменений.

Вы не обязаны копировать этот проект буквально. Его роль — дать устойчивую учебную модель. После прохождения можно заменить AgentClinic на свой сервис, внутренний инструмент, аналитическое приложение или унаследованный проект.

## Что будет считаться успехом

К концу учебника у вас должен быть репозиторий, где:

- есть `QWEN.md` с правилами работы для Qwen Code;
- есть `specs/mission.md`, `specs/tech-stack.md`, `specs/roadmap.md`;
- каждая крупная фича начинается с `requirements.md`, `plan.md`, `validation.md`;
- реализация идёт в отдельной ветке;
- критерии проверки написаны до кода;
- после фазы обновляются дорожная карта, спецификации и журнал изменений;
- повторяемый процесс спецификации фичи оформлен как `.qwen/skills/feature-spec/SKILL.md`;
- агента можно заменить без потери проектной памяти.

## Базовая роль человека

В SDD разработчик не исчезает. Его работа становится более похожей на работу архитектора и редактора слоя намерений:

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

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

## Минимальный словарь

Конституция — проектная конституция: миссия, стек, дорожная карта, ключевые договорённости.

Спецификация фичи — требования, план и критерии проверки для одной фичи.

Проверка — подтверждение, что реализация совпала со спецификацией.

Перепланирование — обновление конституции и дорожной карты между фичами.

Навык — повторяемая инструкция для агента в формате `SKILL.md`.

`QWEN.md` — постоянный контекст Qwen Code для проекта или пользователя.

## Первый пример: плохой и хороший запрос

Плохой запрос:

```text
Добавь страницу отзывов.
```

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

Запрос в стиле SDD:

```text
Начни новую спецификацию фичи для следующей фазы дорожной карты: отображение отзывов.
Сначала прочитай specs/mission.md, specs/tech-stack.md и specs/roadmap.md.
Затем задай мне вопросы про границы, решения и контекст.
После ответов создай specs/YYYY-MM-DD-reviews-display/requirements.md,
plan.md и validation.md. Код пока не пиши.
```

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

## Практика

Создайте пустую директорию для учебного проекта:

```bash
mkdir agentclinic
cd agentclinic
git init
```

Создайте черновой файл `README.md`:

```markdown
# AgentClinic

AgentClinic — вымышленная клиника, где ИИ-агенты восстанавливаются после работы с людьми.

Пожелания участников проекта:
- инженерная команда хочет понятный учебный код на TypeScript;
- продуктовая команда хочет агентов, недуги, терапии, записи на приём, отзывы и обратную связь;
- маркетингу нужен запоминающийся браузерный опыт.
```

Пока не просите Qwen Code писать код. На этом этапе задача — зафиксировать идею проекта и подготовить почву для конституции.

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

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