Тема: Часть 1. Введение в разработку по спецификациям (SDD)
Уровень сложности: Промежуточный
Расчётное время изучения: 8-10 часов
Предварительные требования: Базовые навыки программирования на JavaScript или TypeScript
Понимание принципов работы с терминалом и командной строкой
Начальный опыт работы с системами контроля версий (git)
Представление о принципах веб-разработки (HTML, CSS, базы данных)
Готовность к изучению новой методологии работы с ИИ-агентами
Цели обучения: Сформулировать определение SDD и объяснить принципиальные отличия от традиционного подхода «вайб-кодинга» с ИИ-агентами
Идентифицировать роль спецификации как главного артефакта разработки и описать процесс создания конституции проекта
Применить методику SDD для инициализации учебного проекта AgentClinic с соблюдением всех структурных требований
Проанализировать различия между «плохим» свободным запросом и запросом в стиле SDD, создав собственные примеры
Оценить готовность проекта к работе с агентом-инструментом по чек-листу критериев успеха
Обзор: Часть 1 «Введение» представляет фундаментальные концепции методологии Specification-Driven Development (SDD) — разработки по спецификациям. Учебный материал знакомит с принципиальным смещением точки управления в разработке: от хаотичного взаимодействия с ИИ-агентами в режиме «вайб-кодинга» к структурированному процессу, где спецификация становится главным источником правды. Вводится понятие агента-инструмента (на примере Qwen Code CLI), объясняется распределение ответственности между человеком и машиной, а также даётся обзор учебного проекта AgentClinic — сатирического веб-приложения, которое будет развиваться на протяжении всего учебника. Особое внимание уделяется терминологическим договорённостям, классификации утверждений по силе (Стандарт, Рекомендация, Фронтир) и минимальному словарю ключевых понятий SDD. Материал подготавливает к практическому созданию конституции проекта, спецификаций фич и организации работы с агентом.
Ключевые концепции: Sdd (specification-driven development): Методология разработки, при которой спецификация является главным управляющим артефактом. Код генерируется агентом на основе спецификации, а не на основе свободного запроса. Человек отвечает за намерение, ограничения и критерии приёмки; агент — за скорость, поиск по коду и рутинную реализацию. Подход позволяет сохранять проектную память между сессиями и агентами.
Вайб-кодинг (vibe coding): Неформальный подход к взаимодействию с ИИ-агентом, при котором разработчик пишет короткий свободный запрос (например, «сделай мне форму обратной связи») и принимает результат «на ощущение». Характеризуется быстрой генерацией кода с последующей серией исправлений. Работает для прототипов, но плохо масштабируется на большие системы: решения остаются в чате, архитектура расползается.
Спецификация фичи: Документ, содержащий требования, план реализации и критерии проверки для одной функциональности. Включает файлы requirements.md, plan.md и validation.md. Является входным файлом для агента и определяет качество результата. Создаётся до написания кода и обновляется после завершения фазы.
Конституция проекта: Совокупность документов, определяющих identity проекта: миссия (mission.md), стек технологий (tech-stack.md), дорожная карта (roadmap.md) и ключевые договорённости. Загружается при старте каждой сессии и обеспечивает преемственность понимания проекта.
Qwen.md: Файл постоянного контекста для Qwen Code CLI, содержащий правила работы с проектом. Загружается автоматически при старте сессии агента. Может располагаться на уровне пользователя или проекта.
Агент-инструмент: Программный инструмент (Qwen Code CLI, Claude Code, Codex CLI, Cursor и др.), который читает спецификации и генерирует код. В контексте учебника термин «агент» обозначает именно такой инструмент, а не персонажей клиники AgentClinic.
Разделение ответственности: Фундаментальный принцип SDD: человек отвечает за формулирование намерения, определение ограничений, валидацию результатов и обновление спецификаций. Агент отвечает за скорость выполнения, поиск по коду, рутинную реализацию и механические изменения. Обе стороны выполняют работу, для которой наиболее приспособлены.
Навык (skill.md): Повторяемая инструкция для агента в стандартизированном формате. Хранится в директории .qwen/skills/. Пример: skill для спецификации фичи, который агент может применять многократно без дополнительных указаний.
Критерии приёмки: Конкретные, проверяемые условия, которым должна соответствовать реализация. Определяются до написания кода и включаются в validation.md. Позволяют объективно оценить, что задача выполнена корректно.
Перепланирование: Процесс обновления конституции и дорожной карты между фичами. Производится, когда понимание проекта меняется в ходе работы. Обеспечивает актуальность документации.
Валидация: Подтверждение соответствия реализации спецификации. Проводится человеком на основе критериев из validation.md. Независима от процесса разработки и является формальным подтверждением качества.
Важные даты: Стандарт (standard): Зафиксированное поведение инструмента или общепринятая практика SDD. Не подлежит обсуждению.
Рекомендация (recommendation): Опытная практика, работающая в большинстве случаев, но допускающая разумные исключения.
Фронтир (frontier): Подход, который применяют, но он ещё не устоялся; результат сильно зависит от конкретной команды.
Практические упражнения: Название: Анализ различий между подходами
Проблема: Прочитайте два варианта запросов к агенту: «плохой» запрос «Добавь страницу отзывов» и «хороший» запрос в стиле SDD. Составьте таблицу, в которой сравните: (1) количество неопределённостей в каждом запросе, (2) риски для проекта, (3) что должен решить агент самостоятельно в каждом случае, (4) что остаётся в чате после выполнения запроса.
Решение: 1. Плохой запрос: создаёт множество неопределённостей — где хранить данные, нужны ли рейтинги, форма, валидация, навигация, тесты. Агент принимает все решения самостоятельно, что может противоречить архитектуре проекта. Решения остаются в чате и теряются при смене сессии.
- Хороший запрос в стиле SDD: содержит явную инструкцию прочитать конституцию, задать вопросы, создать артефакты в репозитории. Агент не пишет код, а готовит спецификацию. Все решения документируются и сохраняются.
- Таблица сравнения:
| Критерий | Плохой запрос | Запрос в стиле SDD |
|---|---|---|
| Неопределённости | >10 | 0 |
| Решения агента | Архитектурные | Процедурные |
| Сохранность | В чате | В репозитории |
| Повторяемость | Нет | Да |
Сложность: intermediate
Название: Инициализация проекта AgentClinic
Проблема: Создайте пустую директорию для учебного проекта AgentClinic. Инициализируйте git-репозиторий. Создайте черновой README.md с описанием проекта, включающим: (1) название проекта, (2) его назначение, (3) три группы участников (инженерная команда, продуктовая команда, маркетинг) с их пожеланиями. Пока не пишите код, не просите Qwen Code о помощи.
Решение: 1. Создание директории и инициализация git: mkdir agentclinic cd agentclinic git init
- Создание чернового README.md:
# AgentClinic
AgentClinic — вымышленная клиника, где ИИ-агенты восстанавливаются после работы с людьми.
## Пожелания участников проекта
### Инженерная команда
- Понятный учебный код на TypeScript
- Чистая архитектура с разделением ответственности
- Наличие тестов и документации
### Продуктовая команда
- Функциональность: агенты-пациенты, недуги, терапии, записи на приём
- Отзывы и обратная связь
- Система управления очередью
### Маркетинг
- Запоминающийся браузерный опыт
- Привлекательный пользовательский интерфейс
- Брендированная эстетика клиники
Сложность: beginner
Название: Классификация утверждений
Проблема: Ниже приведены утверждения из учебника. Определите, какие из них являются Стандартом, Рекомендацией или Фронтиром: (a) QWEN.md загружается при старте сессии Qwen Code; (b) фазу длиной больше двух дней следует разбивать на две; (c) полная автоматизация ревью через многоагентный конвейер; (d) спецификация — это входной файл для машины; (e) агента можно заменить без потери проектной памяти.
Решение: a) Стандарт — зафиксированное поведение инструмента, подтверждаемое документацией.
b) Рекомендация — практика, основанная на опыте. Двухдневный срок фазы оптимален, но возможны исключения (например, очень маленькая фича).
c) Фронтир — подход находится в стадии экспериментов, результат сильно зависит от конкретной команды и контекста.
d) Стандарт — основополагающее определение, принятое в SDD.
e) Рекомендация — цель, достижимая при правильной организации спецификаций, но не гарантированная автоматически.
Сложность: intermediate
Название: Создание чек-листа критериев успеха
Проблема: На основе раздела «Что будет считаться успехом» составьте чек-лист из 10 пунктов для проверки готовности репозитория к работе с агентом-инструментом. Каждый пункт должен содержать глагол действия (есть, создана, написаны и т.д.) и быть проверяемым.
Решение: Чек-лист готовности репозитория:
- Есть файл QWEN.md с правилами работы для Qwen Code
- Создана директория specs/
- Есть specs/mission.md с описанием миссии проекта
- Есть specs/tech-stack.md с перечнем технологий
- Есть specs/roadmap.md с планом развития
- Каждая крупная фича начинается с requirements.md
- Каждая фича содержит plan.md с планом реализации
- Каждая фича содержит validation.md с критериями проверки
- Реализация ведётся в отдельной ветке (не в main/master)
- Критерии проверки написаны до кода
- После фазы обновляются дорожная карта и спецификации
- Есть файл .qwen/skills/feature-spec/SKILL.md
- Журнал изменений ведётся и актуален
Сложность: advanced
Название: Переработка свободного запроса
Проблема: Преобразуйте следующий свободный запрос в запрос в стиле SDD: «Сделай мне форму регистрации нового пациента в клинике AgentClinic». Запрос должен: (1) включать указание прочитать соответствующие документы, (2) содержать инструкцию задать вопросы перед работой, (3) определять, какие артефакты создать, (4) содержать запрет на написание кода на первом этапе.
Решение: Запрос в стиле SDD:
«Начни новую спецификацию фичи для следующей фазы дорожной карты: регистрация пациента в клинике.
Сначала прочитай specs/mission.md, specs/tech-stack.md и specs/roadmap.md. Убедись, что понимаешь миссию проекта и текущий стек технологий.
Затем задай мне вопросы по следующим темам:
- Какие данные о пациенте необходимо собирать (имя, контакты, историю недугов)?
- Нужна ли валидация полей (формат email, длина имени)?
- Должна ли форма поддерживать автосохранение?
- Какие ограничения по безопасности данных учитывать?
После получения ответов создай следующие артефакты в новой директории specs/YYYY-MM-DD-patient-registration/:
- requirements.md — требования к функциональности
- plan.md — план реализации с оценкой этапов
- validation.md — критерии проверки
Код пока не пиши. Дождись моего утверждения спецификации.»
Сложность: intermediate
Кейсы: Название: Миграция стартапа с «вайб-кодинга» на SDD: опыт команды CloudFlow
Сценарий: Команда стартапа CloudFlow из 4 разработчиков работала над облачной платформой управления проектами. На ранних этапах взаимодействие с Claude Code строилось на «вайб-кодинге»: короткие запросы, быстрые правки, минимальная документация. К моменту достижения 10 000 строк кода команда столкнулась с серьёзными проблемами: кодовая база стала неуправляемой, агент давал противоречивые советы в разных сессиях, а интеграция нового разработчика занимала недели.
Задача: Основные проблемы: (1) архитектурные решения принимались агентом без документирования, (2) при смене сессии агент не помнил контекст предыдущих решений, (3) рефакторинг одной функции затрагивал 15+ связанных мест из-за несогласованности, (4) два разработчика получили противоречивые реализации одной и той же фичи от разных сессий агента.
Решение: Команда провела трёхнедельную миграцию: (1) создали конституцию проекта с mission.md, tech-stack.md, roadmap.md; (2) написали QWEN.md с явными правилами работы; (3) переработали backlog в спецификации фич; (4) внедрили правило: каждая фича проходит этапы requirements → plan → validation → code; (5) создали навык SPEC.md для стандартизации процесса; (6) настроили CI с обязательными критериями из validation.md.
Результат: Через 2 месяца после миграции: время онбординга нового разработчика сократилось с 3 недель до 3 дней; количество багов на релиз уменьшилось на 60%; скорость добавления новых фич выросла на 30% (парадоксально, несмотря на дополнительные этапы); возможность замены агента без потери контекста подтверждена при переходе с Claude Code на Qwen Code.
Извлечённые уроки: Спецификация — это не бюрократия, а инвестиция в управляемость проекта; стоимость написания спецификации многократно окупается при масштабировании
Связанные концепции: SDD (разработка по спецификациям)
Конституция проекта
Спецификация фичи
Разделение ответственности человек-агент
Критерии приёмки
Советы по изучению: Начните с понимания «почему» — прежде чем разбирать механику SDD, осознайте ограничения «вайб-кодинга» на больших проектах
Работайте с учебным проектом руками: создание директорий и файлов гораздо важнее теоретического понимания
Обращайте внимание на маркировку утверждений (Стандарт, Рекомендация, Фронтир) — это помогает понять, где можно экспериментировать, а где нет
Практикуйте преобразование свободных запросов в запросы в стиле SDD — это ключевой навык, требующий практики
Запомните минимальный словарь: конституция, спецификация фичи, проверка, перепланирование, навык — без этих терминов невозможна эффективная коммуникация в рамках SDD
Изучите инструмент Qwen Code CLI до практических упражнений — понимание возможностей агента поможет лучше сформулировать запросы
Не пытайтесь сразу применить SDD к существующему проекту — начните с учебного проекта AgentClinic, чтобы получить чистый опыт
Обсуждайте материал с коллегами: классификация утверждений и анализ запросов — хорошие темы для парного разбора
Ведите заметки о своём понимании — написание конспекта своими словами помогает выявить пробелы в понимании
Не бойтесь показаться «медленным» на этапе спецификации — ускорение происходит на этапе реализации, когда спецификация устранена неопределённость
Дополнительные ресурсы: Qwen code cli documentation: Официальная документация Qwen Code CLI, включая описание QWEN.md, режимы работы и доступные команды
Agentclinic repository: Учебный проект на GitHub, демонстрирующий полный цикл SDD от спецификации до имплементации
Sdd methodology overview: Обзор методологии Specification-Driven Development с примерами применения в командах
Примеры навыков (.qwen/skills/): Коллекция SKILL.md файлов для стандартизации повторяемых операций агента
Статья «от чата к артефакту»: Рассуждение о трансформации роли ИИ-агента от генератора кода к исполнителю спецификаций
Резюме: Часть 1 «Введение» закладывает фундамент для работы с методологией SDD. Ключевой вывод: спецификация — не бюрократический документ, а входной файл для машины, определяющий качество результата. SDD принципиально отличается от «вайб-кодинга» смещением точки управления: вместо серии итераций «запрос — исправление» создаётся структурированный процесс с конституцией проекта, спецификациями фич и чётким разделением ответственности. Человек отвечает за намерение, ограничения и критерии приёмки; агент — за рутинную реализацию. Учебный проект AgentClinic служит устойчивой моделью для практики; после освоения методологии его можно заменить на любой собственный проект. Конечная цель — репозиторий, где агента можно заменить без потери проектной памяти, а спецификации обеспечивают повторяемое качество.