Часть 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 для проекта или пользователя.

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

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

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

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

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

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

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

Практика

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

mkdir agentclinic
cd agentclinic
git init

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

# AgentClinic

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

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

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

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

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