Thema: Часть 3. Обзор процесса SDD (Structured Design Driven)
Schwierigkeitsgrad: Mittel
Geschätzte Lernzeit: 4-6 часов (теория + практика)
Voraussetzungen: Базовое понимание Git и работы с ветками
Опыт работы с markdown-документами
Понимание основ разработки ПО (требования, планирование, тестирование)
Знакомство с концепцией AI-агентов для кодинга (желательно Qwen Code)
Пройдены Часть 1 и Часть 2 курса (или эквивалентный опыт)
Lernziele: Объяснить трёхслойную архитектуру процесса SDD (конституция → спецификация → реализация) и описать роль каждого слоя
Самостоятельно создать структуру specs/ с файлами mission.md, tech-stack.md, roadmap.md для учебного проекта
Применять контур «Планируй — Реализуй — Проверяй» при работе с AI-агентом, формулируя чёткие запросы для каждой фазы
Использовать команду /clear для валидации полноты спецификации и объяснять её диагностическую ценность
Выбирать подходящий режим спецификации (Requirements-First, Design-First, Bugfix) в зависимости от типа задачи
Übersicht: Эта часть курса раскрывает архитектуру процесса Structured Design Driven (SDD) — методологии разработки ПО, оптимизированной для работы с AI-агентами. Процесс моделируется как три слоя памяти: верхний (конституция проекта), средний (спецификации фич) и нижний (реализация и проверки). Ключевое новшество — явное разделение режимов работы с агентом и строгий контур «Планируй — Реализуй — Проверяй», который предотвращает «утечку» контекста между фазами. Материал ориентирован на практическое применение: вы научитесь создавать репозиторий, где знание «живёт» в файлах, а не в истории чата, что критически важно для воспроизводимости работы с AI-ассистентами.
Schlüsselkonzepte: Трёхслойная архитектура sdd: Метафора памяти процесса: верхний слой (конституция: mission.md, tech-stack.md, roadmap.md) отвечает на вопросы, которые не должны решаться заново в каждой фиче; средний слой (спецификация фичи: requirements.md, plan.md, validation.md) описывает конкретную работу; нижний слой (реализация: код, тесты, миграции + проверки) — исполнение. Между слоями происходит перепланирование при обнаружении неточностей.
Конституция проекта: Фундаментальные документы, фиксирующие миссию, аудиторию, технический стек, архитектурные ограничения и фазы дорожной карты. В проектах с Qwen Code дополняется файлом QWEN.md, который говорит агенту КАК вести себя в репозитории, в отличие от specs/*.md, которые говорят ЧТО строит продукт.
Спецификация фичи: Изолированная папка для каждой фазы дорожной карты (например, specs/2026-05-10-feedback-form/), содержащая три обязательных файла: requirements.md (границы, исключения, решения, контекст), plan.md (группы задач), validation.md (критерии слияния ветки). Эти файлы важнее истории чата — новая сессия продолжает работу, прочитав только репозиторий.
Git-ветки как когнитивные границы: Каждая фаза фичи живёт в отдельной ветке (git checkout -b phase-1-hello-hono). Это создаёт чёткую границу: все изменения ветки должны соотноситься с конкретной папкой спецификации. При избыточных изменениях агента есть точка отката.
Команда /clear как диагностика: Проверка полноты спецификации: если агент может реализовать фичу после очистки контекста, значит знание записано в файлах. Разумные уточняющие вопросы нормальны; угадывание сигнализирует о недописанной спецификации.
Четыре режима работы с агентом: Интервью (написание спецификации), Реализация (конкретные группы задач), Проверка (несоответствия код ↔ спецификация), Перепланирование (обновление конституции, дорожной карты, журнала). Смешение режимов в одной сессии приводит к «загрязнению» контекста.
Контур планируй — реализуй — проверяй (plan-act-verify): Внутри режима реализации и проверки: Планируй — агент перечисляет намерения без изменения файлов; Реализуй — код в рамках одобренного плана (расширение запрещено); Проверяй — сравнение с validation.md, отчёт без правок кода. Смешение фаз = потеря точки контроля.
Три режима спецификации: Requirements-First (по умолчанию — что должно появиться), Design-First (как реализовать — для миграций, API, реорганизации), Bugfix (что воспроизводит баг, ожидаемый результат, что не должно измениться). Выбор режима предотвращает растягивание неподходящего шаблона.
Übungsaufgaben: Name: Создание скелета конституции
Problem: В учебном проекте AgentClinic создайте структуру specs/ с пустыми файлами mission.md, tech-stack.md, roadmap.md. Затем напишите промпт для Qwen Code, который заставит агент заполнить эти файлы, задавая ровно три сгруппированных вопроса (миссия и аудитория, технический стек, дорожная карта). Важно: агент не должен писать код или создавать файлы до получения ответов.
Lösung: 1. В терминале: mkdir -p specs && touch specs/mission.md specs/tech-stack.md specs/roadmap.md
- Промпт для Qwen Code:
Ты помогаешь мне работать по SDD.
Пока не пиши код.
Прочитай @README.md и посмотри структуру репозитория.
Предложи начальный каталог specs/:
- mission.md
- tech-stack.md
- roadmap.md
Перед записью файлов задай ровно три сгруппированных вопроса:
1. Миссия и аудитория
2. Технический стек и ограничения
3. Дорожная карта и первая фаза- Проверьте, что агент действительно задаёт вопросы, а не создаёт файлы с шаблонными данными.
Komplexität: beginner
Name: Диагностика спецификации через /clear
Problem: У вас есть частично заполненная спецификация фичи формы обратной связи. Напишите последовательность действий для проверки, достаточна ли спецификация для реализации после /clear. Сформулируйте промпт, который агент должен выполнить после очистки контекста. Опишите, как интерпретировать три возможных результата: (а) агент реализует без вопросов, (б) агент задаёт разумные уточнения, (в) агент начинает угадывать.
Lösung: 1. Убедитесь, что файлы спецификации содержат: requirements.md (границы фичи), plan.md (группы задач с приоритетами), validation.md (критерии приёмки).
- Выполните /clear в чате Qwen Code.
- Промпт:
Прочитай @QWEN.md, @specs/mission.md, @specs/tech-stack.md
и @specs/2026-05-10-feedback-form/plan.md.
Реализуй только группу задач 1. Остановись после списка изменённых файлов.- Интерпретация результатов:
- (а) Успешная реализация без вопросов → спецификация достаточна, знание в файлах
- (б) Разумные уточнения (например, «какой формат email-валидации?») → норма, уточните и допишите в requirements.md
- (в) Угадывание (например, «я предположу, что форма отправляет на API /api/feedback») → спецификация недописана, требуется доработка requirements.md с явными решениями
Komplexität: intermediate
Name: Разделение режимов в одной сессии
Problem: Вы обнаружили, что в предыдущей длинной сессии с агентом смешались обсуждение продукта, написание кода и проверка. В результате агент предложил изменения, выходящие за рамки фичи, и часть проверок была пропущена. Спроектируйте стратегию разделения на четыре отдельных сессии с явными запросами для каждого режима. Для режима реализации дополнительно разбейте на три фазы контура Планируй — Реализуй — Проверяй.
Lösung: Сессия 1 — Режим интервью:
Режим: интервью. Помоги дописать спецификацию фичи @specs/2026-05-10-feedback-form/.
Прочитай requirements.md и задай уточняющие вопросы по неопределённым границам.
Не предлагай код, не пиши план реализации.Сессия 2 — Режим реализации, фаза Планируй:
Режим: реализация, фаза Планируй.
Прочитай @specs/2026-05-10-feedback-form/plan.md.
Перечисли, что собираешься делать для группы задач 2, какие файлы тронешь, какие проверки запустишь.
Не пиши код, не меняй файлы.Сессия 3 — Режим реализации, фаза Реализуй:
Режим: реализация, фаза Реализуй.
План одобрен: [вставить одобренный план из предыдущей сессии].
Выполни только этот план. Если возникнет новая идея — остановись и предложи отдельную группу задач.Сессия 4 — Режим проверки:
Режим: проверка.
Прочитай @specs/2026-05-10-feedback-form/validation.md.
Сравни текущий код в ветке с критериями валидации.
Перечисли: что прошло, что упало, что не проверялось.
Не правь код, только отчёт.Komplexität: intermediate
Name: Выбор режима спецификации
Problem: Для трёх сценариев выберите и обоснуйте подходящий режим спецификации (Requirements-First, Design-First, Bugfix), опишите структуру создаваемых документов и отличия от дефолтного шаблона:
Сценарий А: Нужно добавить страницу с отзывами пациентов — новая функциональность для AgentClinic. Сценарий Б: Требуется мигрировать базу данных с SQLite на PostgreSQL без потери данных. Сценарий В: Пользователь сообщает, что форма обратной связи отправляет пустые сообщения при отключённом JavaScript.
Lösung: Сценарий А — Requirements-First:
- Стандартная структура: requirements.md (что отображается, фильтры, модерация), plan.md (верстка, API, интеграция), validation.md (тесты отображения, защита от XSS)
- Отличий от шаблона нет — классическая новая фича
Сценарий Б — Design-First:
- Сначала design.md или расширенный plan.md: схема миграции, стратегия переключения (параллельное использование, blue-green), rollback-план
- Затем requirements.md: совместимость существующих запросов, ограничения downtime, критерии целостности данных
- validation.md: проверки миграции тестовых данных, performance-тесты
- Отличие: требования вторичны, главный риск — «как», не «что"
Сценарий В — Bugfix:
- Структура адаптирована: reproduction.md (шаги воспроизведения: отключить JS, отправить форму), expected.md (ожидаемое: валидация на сервере, ошибка), invariant.md (что не должно измениться: успешная отправка при включённом JS, стилизация)
- plan.md: минимальные изменения, серверная валидация
- validation.md: тесты с отключённым JS, регрессионные тесты нормального сценария
- Отличие: фокус на сохранении, а не добавлении; явное указание неизменяемого
Komplexität: advanced
Fallstudien: Name: AgentClinic: от хаотичных промптов к воспроизводимому процессу
Szenario: Команда из трёх разработчиков создавала MVP медицинской платформы для записи к пациентам (AgentClinic). Первые две недели работы с Qwen Code проходили в режиме «потока сознания»: длинные сессии, где обсуждались требования, сразу писался код, иногда делалась проверка. Результат — ветки содержали изменения, не связанные с заявленной фичей; спецификации были разрозненными заметками в Notion; новый разработчик не мог воспроизвести работу агента при перезапуске сессии.
Aufgabe: 1. Контекст чата «размывался» между фазами — агент тянул обсуждения продукта в код и наоборот
- Отсутствие явной валидации приводило к слиянию веток с непроверенными сценариями
- Знание жило в истории чатов разных разработчиков, а не в репозитории
- Перепланирование происходило неявно — архитектурные решения менялись без обновления конституции
Lösung: Команда внедрила SDD-процесс из Части 3:
- Создали конституцию: mission.md (платформа для независимых врачей, аудитория — пациенты 35-65 лет), tech-stack.md (Hono, Drizzle ORM, SQLite → PostgreSQL в Q3), roadmap.md (4 фазы: прототип, MVP, интеграция с Телеграм, мобильная версия)
- Для каждой фичи — отдельная папка specs/YYYY-MM-DD-название/ с тремя файлами
- Ввели правило: каждая фаза — отдельная Git-ветка, именованная по плану
- Использовали /clear как обязательный шаг перед реализацией
- Разделили сессии по четырём режимам с явными маркерами в начале промпта
- Внедрили контур Планируй — Реализуй — Проверяй с запретом расширения плана в ходе реализации
Ergebnis: Через три недели: время входа нового разработчика в контекст сократилось с 2 дней до 2 часов; процент веток, требующих переделки после code review, упал с 60% до 15%; агент после /clear успешно реализовывал 80% фич без угадывания; архитектурные решения стали прослеживаемыми — при смене стека с Hono на FastAPI обновление tech-stack.md автоматически подхватывалось во всех новых сессиях.
Gewonnene Erkenntnisse: Знание в файлах важнее удобства чата — краткосрочные затраты на документирование окупаются воспроизводимостью
Жёсткие границы между режимами работы агента предотвращают «загрязнение» контекста лучше, чем инструкции «будь внимателен»
Команда /clear — не техническая деталь, а организационная метрика зрелости спецификации
Перепланирование должно быть видимым актом: обновление конституции с записью в changelog, а не неявная корректировка в разговоре
Verwandte Konzepte: Трёхслойная архитектура SDD
Четыре режима работы с агентом
Контур Планируй — Реализуй — Проверяй
Команда /clear как диагностика
Name: Миграция API: когда Design-First спасает от технического долга
Szenario: В рамках AgentClinic требовалось изменить публичное API для интеграции с внешней системой электронной записи. Требования были формально понятны (новые эндпоинты для слотов записи), но существовало риск нарушить контракты, используемые мобильным приложением в разработке у партнёра.
Aufgabe: 1. Классический шаблон Requirements-First привёл бы к детальному описанию «что» без проработки «как сохранить обратную совместимость»
- Неправильная миграция грозила отказом партнёрского приложения на этапе, когда собственное мобильное приложение ещё не было готово
- Необходимость версионирования API не была очевидна до анализа вариантов реализации
Lösung: Команда применила режим Design-First:
- Сначала создан design.md с тремя вариантами: URL-versioning (/v1/, /v2/), header-based versioning, и deprecate-стратегия
- Сравнительный анализ: URL-versioning — простота для партнёра, но загрязнение роутов; header-based — чистота, но сложность документирования; deprecate — минимум кода, но риск внезапного отказа
- Выбран гибрид: /v2/ для новых эндпоинтов, заголовок X-API-Version для будущих изменений, 6-месячный deprecate на /v1/
- Только после фиксации design.md написаны requirements.md с явными ограничениями совместимости и validation.md с тестами контрактов
Ergebnis: Партнёрское приложение мигрировало за 2 недели без инцидентов; собственное мобильное приложение использовало /v2/ с первого дня; при последующем изменении формата ответа команда повторно применила Design-First, сократив время принятия архитектурного решения с 3 дней до 4 часов.
Gewonnene Erkenntnisse: Design-First применяется, когда главный риск — способ реализации, а не неопределённость требований
Сознательный выбор между вариантами в design.md создаёт аудиторский след для будущих архитектурных решений
Отложенное написание requirements.md не ускоряет процесс, но повышает качество конечного результата
Validation для Design-First должен включать тесты не только нового кода, но и регрессию существующих контрактов
Verwandte Konzepte: Три режима спецификации
Конституция проекта (tech-stack.md)
Роль веток как когнитивных границ
Контур Планируй — Реализуй — Проверяй
Lerntipps: Визуализируйте процесс: нарисуйте на бумаге трёхслойную архитектуру для вашего текущего или воображаемого проекта, отметив, какие решения на каждом уровне уже приняты, а какие ещё варьируются
Практикуйте /clear мысленно: перед отправкой промпта агенту представьте, что контекст чата исчез — достаточно ли информации в файлах specs/ для продолжения работы?
Создайте шаблоны промптов для четырёх режимов в виде сниппетов в вашем редакторе или менеджере буфера обмена — это снизит соблазн смешать режимы ради экономии времени
Ведите «журнал перепланирования»: при обновлении конституции фиксируйте, какая работа показала неточность старых решений — это обучает интуицию о типичных «местах трения»
Для изучения контура Планируй — Реализуй — Проверяй используйте ролевую игру: вы — агент, коллега или воображаемый «контролёр» — проверяет, не смешали ли вы фазы в ответе
Проверяйте свои спецификации «на угадывание»: попросите коллегу или другую модель AI прочитать только specs/ и описать, что она ПРЕДПОЛАГАЕТ о ненаписанных деталях — совпадения с вашими намерениями = хорошая спецификация
Начинайте с Bugfix-режима для простых задач: он короче и учит фокусироваться на «что не должно измениться» — навык, полезный во всех режимах
Zusätzliche Ressourcen: Оригинальный курс sdd (части 1-2): Предшествующие материалы для понимания контекста — рекомендуется пройти перед углубленным изучением Части 3
Документация qwen code: https://github.com/QwenLM/Qwen2.5-Coder — официальное руководство по работе с агентом, включая команды /clear и @-ссылки
Git branching strategy (git flow / github flow): Сравнение стратегий ветвления для понимания, почему SDD предлагает ветки по фазам, а не по разработчикам
«writing great specifications» by kamil nicieja: Книга о спецификациях в BDD — аналоги с Gherkin-подходом помогают понять, почему validation.md отделяется от requirements.md
Rfc-процессы в open source (python pep, rust rfc): Примеры Design-First в крупных проектах — как tech-stack.md масштабируется до архитектурных решений сообщества
Практика: репозиторий-шаблон agentclinic/: Создайте форк учебного проекта и пройдите все практические упражнения из гайда в реальном окружении
Zusammenfassung: Часть 3 представляет SDD как трёхслойный процесс, где знание умышленно «замораживается» в файлах конституции и спецификаций, а не размывается в истории чатов. Ключевые практики: изолированные Git-ветки по фазам, диагностика через /clear, чёткое разделение четырёх режимов работы с агентом, контур Планируй — Реализуй — Проверяй с запретом расширения плана в ходе реализации, и гибкий выбор между тремя режимами спецификации. Освоение этих практик переводит работу с AI-агентом из режима «магии» в режим инженерной дисциплины с воспроизводимыми результатами.