Тема: Часть 21. Заключение и рабочая система
Уровень сложности: Средний
Расчётное время изучения: 4-6 часов (теория: 2 часа, практика: 2-4 часа)
Предварительные требования: Основы работы с Git и ветками
Понимание базового CI/CD
Знакомство с LLM-агентами (Qwen Code, Claude Code или аналоги)
Прохождение частей 1-20 курса SDD (желательно, но не обязательно)
Базовый опыт работы с Markdown и структурированием документации
Цели обучения: Сформировать полную структуру SDD-репозитория и объяснить назначение каждого файла
Выполнить операционный цикл 'спецификация → реализация → проверка → слияние' с использованием /clear между ролями
Определить уровень зрелости SDD в своей команде по шкале 0-4 и составить план перехода на следующий уровень
Создать минимальный работающий SDD-процесс для реального проекта из 5 файлов
Провести ретроспективу после 2-3 фич и выделить наблюдения, пригодные для кодификации в правила агента
Обзор: Эта заключительная часть курса SDD превращает теорию в рабочую систему. SDD — это не набор файлов ради файлов, а инфраструктура контроля, которая помогает человеку сохранять суверенитет, когда агент способен за минуты изменить то, что раньше занимало часы. Главный навык — не писать максимально длинные промпты, а выстроить правильные границы между намерением (спецификация), планированием, реализацией и проверкой. Учебник проведёт вас через итоговую структуру репозитория, операционный цикл, границы решений, типичные ошибки, шкалу зрелости и практическое внедрение в реальной команде. Цель — довести команду до уровня 2 на дидактическом проекте AgentClinic и дать инструменты для дальнейшего роста.
Ключевые концепции: Рабочая система sdd: SDD — это не документация ради документации, а живой процесс, который работает только при соблюдении дисциплины. Ключевая формула: спецификация хранит долговременное намерение, факты решают, можно ли сливать ветку, агент быстро исполняет, человек отвечает за суждение. Или ещё короче: спецификации направляют, факты допускают к слиянию.
Итоговая структура репозитория: Полная структура включает: корневые файлы (AGENTS.md, QWEN.md, README.md, CHANGELOG.md, package.json, tsconfig.json); директорию .qwen/ с настройками, хуками, памятью и навыками; директорию specs/ с mission.md, tech-stack.md, roadmap.md и фича-спецификациями по шаблону YYYY-MM-DD-feature-name/ (requirements.md, plan.md, validation.md); исходный код в src/, тесты в tests/, шаблон PR в .github/pull_request_template.md.
Операционный цикл: Чёткая последовательность действий: подготовка (git checkout main, git pull, git status, npm test, npm run typecheck) → спецификация с навыком feature-spec и /clear → коммит спецификации → реализация с чётким ограничением 'только группа задач 1' и /clear → проверка по validation.md с перечислением подтверждённых, проваленных, отсутствующих и неоднозначных фактов → обновление CHANGELOG с навыком changelog → финальные проверки и слияние → перепланирование перед следующей фичей.
Границы решений: Каждый файл хранит свой тип решений: mission.md — аудитория, продуктовый смысл, тон, определение успеха; tech-stack.md — язык, среда, фреймворк, БД, тестирование, ограничения развёртывания, запрещённые технологии; roadmap.md — порядок фаз, статусы, поставляемые результаты, следующий шаг; спецификация фичи — границы, out of scope, группы задач, факты validation.md, команды проверки, статусы фактов, ручные проверки; QWEN.md/AGENTS.md — правила поведения, команды проверки, запрет на спекулятивные рефакторинги, требование спецификации перед кодом.
Шкала зрелости sdd: Пятиуровневая шкала: 0 — вайб-кодинг (один длинный чат, решения в истории сессии); 1 — спецификации факультативно, validation.md как пожелания, /clear забывается; 2 — SDD как стандарт по умолчанию, исполняемые факты, /clear привычка, перепланирование между фичами; 3 — кодифицированный процесс, навыки, защитные хуки, четырёхслойное ревью, распознавание антипаттернов; 4 — обучаемый процесс, наблюдения превращаются в правила, память агента осознанно управляется, проверена заменяемость агента. Цель учебника — уровень 2.
Минимальный шаблон sdd: Для начала достаточно 5 файлов: specs/mission.md, specs/tech-stack.md, specs/roadmap.md, specs/YYYY-MM-DD-feature/(requirements.md, plan.md, validation.md). Не нужно ждать идеального фреймворка — начните с минимума и наращивайте по наблюдениям.
Кодификация наблюдений: Ключевой механизм роста с уровня 2 на 3: когда повторяющаяся ошибка агента фиксируется, кто-то спокойно предлагает «давайте добавим правило в QWEN.md», и это правило действительно появляется. Ретроспектива после 2-3 фич анализирует: где агент угадывал, какие спецификации были бесполезны, какие проверки поймали реальные ошибки, какие пункты были пожеланиями, а не фактами, что стоит автоматизировать.
Заменяемость агента: Принцип, проверяемый на уровне 4: команда меняла инструмент (Qwen → Claude → другой) и не потеряла процесс. Достигается через чёткую документированность намерений и фактов, независимых от конкретного агента.
Практические упражнения: Название: Упражнение 1: Создание минимального SDD-скелета
Проблема: Возьмите свой текущий проект (или создайте новый репозиторий). Создайте минимальный SDD-шаблон из 5 файлов: specs/mission.md, specs/tech-stack.md, specs/roadmap.md, specs/2026-01-15-auth-module/requirements.md, specs/2026-01-15-auth-module/plan.md, specs/2026-01-15-auth-module/validation.md. Заполните каждый файл по правилам границ решений. Затем выполните операционный цикл до этапа спецификации (включительно): подготовка ветки, /clear, запрос к агенту с навыком feature-spec, коммит спецификации.
Решение: Шаг 1: Создайте директорию specs/ в корне проекта. Шаг 2: В mission.md запишите: аудитория (например, 'внутренние разработчики медицинской клиники'), продуктовый смысл ('автоматизация записи пациентов'), тон ('деловой, без эмодзи'), определение успеха ('время записи сокращается с 10 до 2 минут'). Шаг 3: В tech-stack.md зафиксируйте: TypeScript, Node.js 20, Hono, SQLite, Vitest, Docker, запрещён MongoDB. Шаг 4: В roadmap.md опишите 3 фазы: 1) инфраструктура (статус: done), 2) аутентификация (статус: in progress), 3) расписание (статус: planned). Шаг 5: Для фичи auth-module создайте requirements.md с границами ('включает: JWT-логин, refresh-токены; не включает: OAuth, 2FA'), plan.md с 3 группами задач, validation.md с 5 фактами и командами проверки. Шаг 6: git checkout -b feat/auth-spec, git add specs/, git commit -m 'Add auth-module spec'. Проверка: структура репозитория соответствует минимальному шаблону SDD.
Сложность: beginner
Название: Упражнение 2: Диагностика уровня зрелости команды
Проблема: Проанализируйте текущий процесс разработки в вашей команде (или в гипотетической команде из 3 разработчиков, использующих Cursor). По шкале 0-4 определите текущий уровень зрелости SDD. Для каждого признака перехода между уровнями (0→1, 1→2, 2→3, 3→4) укажите конкретные факты из вашей практики, которые подтверждают или опровергают достижение уровня. Составьте план из 3 конкретных шагов для перехода на следующий уровень с оценкой времени внедрения.
Решение: Шаг 1: Создайте таблицу с 5 столбцами: Уровень, Признаки, Факты из практики, Подтверждён?, Доказательства. Шаг 2: Заполните для уровня 0: 'Один длинный чат с агентом' → 'Разработчик Иван держит 200-сообщенийый чат в Cursor, решения не задокументированы' → Подтверждён → скриншот истории. Для уровня 1: 'Спецификации факультативно' → 'Для больших фич пишем README, для мелких — нет, validation.md отсутствует' → Частично. Для уровня 2: 'SDD как стандарт по умолчанию' → 'Нет, новые фичи начинаются с просьбы «напиши код»' → Не подтверждён. Шаг 3: Текущий уровень = 1 (между 1 и 2). Шаг 4: План перехода на 2: (а) Внедрить правило 'Ни одной многофайловой фичи без requirements.md, plan.md, validation.md' — 1 неделя; (б) Добавить /clear между ролями в шаблоне промптов — 3 дня; (в) Провести первую ретроспективу после 2 фич — 2 недели. Итого: 4 недели до стабильного уровня 2.
Сложность: intermediate
Название: Упражнение 3: Симуляция проверки с отклонением
Проблема: Агент реализовал фичу 'hello-hono' (API на Hono с эндпоинтом GET /health). Тесты проходят, но при проверке по validation.md обнаружены расхождения: (1) в спецификации указан порт 3000, агент использовал 8080; (2) в спецификации требовался заголовок X-Request-ID, агент его не добавил; (3) тесты агента проверяют только 200 OK, а validation.md требует проверки структуры ответа {status: 'ok', timestamp: ISO8601}. Составьте отчёт проверки в формате 'подтверждённые факты, проваленные факты, отсутствующие факты, неоднозначные пункты'. Определите, можно ли сливать ветку, и опишите следующие шаги.
Решение: Отчёт проверки: Подтверждённые факты: (а) сервер запускается без ошибок (npm run dev выполняется); (б) эндпоинт GET /health существует; (в) возвращается HTTP 200. Проваленные факты: (а) порт сервера — 8080 вместо 3000 (требование validation.md §3.1); (б) отсутствует заголовок X-Request-ID (требование §4.2); (в) структура ответа не соответствует {status: 'ok', timestamp: ISO8601}, возвращается просто 'OK' (требование §5.1). Отсутствующие факты: (а) не проверен graceful shutdown (§6.1, тест отсутствует в реализации); (б) не проверена обработка SIGTERM (§6.2). Неоднозначные пункты: (а) 'сервер должен быть production-ready' — не определён критерий; (б) 'документация эндпоинта' — не ясно, Swagger или README. Решение о слиянии: Ветку сливать НЕЛЬЗЯ. Проваленные факты §3.1, §4.2, §5.1 являются обязательными (статус: обязательный в validation.md). Следующие шаги: (1) Вернуть ветку агенту с отчётом и требованием исправить проваленные факты; (2) Уточнить неоднозначные пункты в спецификации; (3) После исправления — повторная проверка только проваленных и отсутствующих фактов; (4) Обновить QWEN.md правилом: 'Порт сервера всегда бери из specs/tech-stack.md или спецификации фичи, не используй дефолтные значения фреймворка'.
Сложность: intermediate
Название: Упражнение 4: Кодификация после ретроспективы
Проблема: После 3 фич в команде AgentClinic собраны следующие наблюдения: (а) агент 2 раза из 3 делал 'спекулятивный рефакторинг' — менял структуру директорий без запроса; (б) validation.md для фичи 'agents-ailments' был полностью скопирован из предыдущей фичи и не соответствовал реальным требованиям; (в) команда забывала /clear между спецификацией и реализацией, агент путал контексты; (г) навык feature-spec был создан до того, как команда поняла свой процесс, и содержит устаревшие инструкции. Превратите эти наблюдения в 4 конкретных правила для QWEN.md и опишите процесс обновления навыка feature-spec.
Решение: Правила для QWEN.md: (1) 'ЗАПРЕЩЕНО: изменять структуру директорий, имена файлов, зависимости без явного указания в спецификации. Если видишь необходимость рефакторинга — остановись, сообщи в отчёте, жди подтверждения.' (2) 'Перед использованием validation.md проверь, что он соответствует текущей фиче: даты, имена сущностей, команды проверки должны быть специфичны, а не скопированы.' (3) 'Обязательная последовательность: /clear перед каждой сменой роли (спецификатор → разработчик → проверяющий). Контекст чата не переносится между ролями.' (4) 'Навыки — живые артефакты. При обнаружении устаревшей инструкции немедленно сообщи, не следуй ей слепо.' Обновление навыка feature-spec: Шаг 1: Создать задачу 'Обновить feature-spec после ретроспективы 2026-05-15'. Шаг 2: Внести изменения в .qwen/skills/feature-spec/SKILL.md: добавить раздел 'Антипаттерны' с 3 примерами из практики, обновить шаблон validation.md с напоминанием о специфичности, добавить чек-лист 'Перед созданием спецификации'. Шаг 3: Протестировать обновлённый навык на одной маленькой фиче. Шаг 4: Если агент задаёт меньше уточняющих вопросов — навык улучшен, зафиксировать версию в CHANGELOG.
Сложность: advanced
Кейсы: Название: Кейс: Миграция стартапа MedFlow с вайб-кодинга на SDD уровня 2
Сценарий: MedFlow — стартап телемедицины, 4 разработчика, активно используют Cursor с Composer. За 6 месяцев накоплено 15k сообщений в чатах, продакшен ломался 3 раза из-за 'оптимизаций' агента, документация устарела в момент создания. CTO принял решение внедрить SDD после очередного инцидента: агент удалил таблицу appointments, 'оптимизируя' схему, потому что в чате 200 сообщений назад обсуждалась другая структура.
Задача: (1) Разработчики сопротивлялись: 'Это замедлит нас, мы и так быстро движемся'. (2) Не было единого понимания продукта: каждый разработчик имел своё видение. (3) Агенты привыкли к длинным чатам и 'догадывались' о намерениях. (4) Нужно было сохранить скорость доставки фич при одновременном росте надёжности.
Решение: Неделя 1: Внедрён единственный жёсткий правило — 'Ни одной многофайловой фичи без requirements.md, plan.md, validation.md'. Созданы specs/mission.md (единое видение: 'платформа для асинхронных консультаций, не синхронных звонков'), specs/tech-stack.md (запрещён Firebase, зафиксирован PostgreSQL). Неделя 2-3: Добавлен короткий AGENTS.md с 5 правилами, включая запрет на спекулятивные рефакторинги. Навык feature-spec создан после 2 ручных спецификаций — не раньше. Неделя 4: Внедрён /clear между ролями, разработчики отслеживают это в парном программировании. Неделя 6: Первая ретроспектива — обнаружено, что 40% пунктов validation.md были пожеланиями, а не проверяемыми фактами. Уточнены критерии. Неделя 8: Проверена заменяемость — один разработчик перешёл с Cursor на Claude Code для одной фичи, процесс сработал без потерь.
Результат: Через 3 месяца: время от идеи до продакшена сократилось с 14 до 9 дней (контринтуитивно: меньше откатов и багов), инциденты из-за агента — с 3/месяц до 0, новый разработчик влился за 3 дня вместо 2 недель (читал specs/, не историю чатов). Команда достигла уровня 2, планирует переход на 3 через автоматизацию хуков.
Извлечённые уроки: Начинать не с идеального процесса, а с одного неукоснительного правила — это единственный способ преодолеть сопротивление
Навыки агента нельзя создавать до понимания процесса: первые 2 спецификации должны быть ручными, чтобы увидеть паттерны
Ретроспектива после 2-3 фич критична: без неё validation.md остаётся списком пожеланий, а процесс — формальностью
Заменяемость агента — не абстрактная цель, а практическая проверка: попробуйте другой инструмент для одной фичи и увидите пробелы в документации
Связанные концепции: Минимальный шаблон SDD
Шкала зрелости SDD
Операционный цикл
Кодификация наблюдений
Заменяемость агента
Название: Кейс: Корпоративная команда BigTech, застрявшая на уровне 3 из-за преждевременной автоматизации
Сценарий: Команда из 12 разработчиков в крупном e-commerce проекте быстро перешла с уровня 1 на 3: создали 15 навыков, 8 защитных хуков, автоматическое ревью. Через 4 месяца процесс захлебнулся: хуки отклоняли 60% коммитов по ложным срабатываниям, навыки противоречили друг другу, разработчики обходили систему через 'вайб-кодинг в личных ветках'.
Задача: (1) Автоматизация опередила понимание: хуки кодировали предположения, а не проверенные паттерны. (2) Навыки размножились без централизованного владения — каждый разработчик добавлял 'свой' навык. (3) Процесс стал самоцелью: метрики 'уровня зрелости' важнее реальной эффективности. (4) Забытая ретроспектива: команда не анализировала, какие правила работают, а какие — нет.
Решение: Радикальное упрощение: отключены все хуки кроме 2, удалены 10 из 15 навыков, оставлены только feature-spec и changelog. Введён ежемесячный аудит: каждое правило в QWEN.md должно иметь ссылку на конкретный инцидент, который оно предотвратило. Возвращены ручные проверки для 20% фич — случайная выборка для валидации автоматики. Ретроспектива стала обязательной перед каждым планированием спринта, не только между фичами.
Результат: Через 2 месяца: ложные срабатывания хуков снизились с 60% до 8%, время цикла 'спецификация → слияние' сократилось на 35%, разработчики вернулись в основной процесс. Команда осознанно вернулась к уровню 2 с элементами 3, планируя возврат на 3 через 6 месяцев наблюдений.
Извлечённые уроки: Уровни 3 и 4 не должны быть самоцелью: преждевременная автоматизация хуже отсутствия автоматизации
Каждое правило в QWEN.md должно иметь 'родословную' — конкретный инцидент, иначе это спекуляция
Случайная ручная проверка 20% автоматизированных процессов — необходимый контроль качества
Шкала зрелости — диагностический инструмент, не метрика KPI: используйте её для понимания, а не для отчётности
Связанные концепции: Шкала зрелости SDD
Кодификация наблюдений
Самые частые ошибки
Границы решений
Советы по изучению: Практикуйте /clear физически: откройте Qwen Code, выполните команду, убедитесь, что контекст чата действительно сброшен. Многие забывают это сделать на автомате, и агент путает роли.
Создайте 'шаблонный репозиторий' SDD на GitHub и клонируйте его для каждого нового проекта — это снижает порог начала и предотвращает 'паралич чистого листа'.
Проводите 'аудит границ' раз в неделю: откройте mission.md, tech-stack.md, roadmap.md и проверьте, не противоречат ли они друг другу. Несогласованность этих трёх файлов — главная причина бесполезных спецификаций.
Для визуального стиля: нарисуйте операционный цикл на бумаге A3 и повесьте рядом с монитором. SDD работает только при буквальном следовании последовательности, без пропусков.
Практикуйте 'красную команду': попросите коллегу намеренно сломать вашу спецификацию — пропустить validation.md, проигнорировать /clear, сделать рефакторинг вне плана. Это выявляет слепые зоны в QWEN.md.
Ведите 'журнал инцидентов агента': фиксируйте дату, промпт, неожиданное поведение, добавленное правило. Через 10 записей увидите паттерны, пригодные для кодификации.
Для аудиторного стиля: обсудите с командой кейс MedFlow, затем проведите ролевую игру — один 'агент' (с закрытыми глазами на исходные документы), один 'спецификатор', один 'проверяющий'. Почувствуйте на себе, где процесс даёт сбои.
Не читайте эту часть 'за один присест'. Остановитесь после каждого раздела и выполните микро-практику: создайте один файл, проверьте одну гипотезу, задайте агенту один тестовый промпт.
Дополнительные ресурсы: Репозиторий agentclinic (образец структуры): Изучите итоговую структуру из материалов курса как эталон для своих проектов
Шаблон минимального sdd: specs/mission.md + specs/tech-stack.md + specs/roadmap.md + specs/YYYY-MM-DD-feature/(requirements.md, plan.md, validation.md)
Документация qwen code по навыкам (skills): https://github.com/QwenLM/Qwen2.5-Coder (официальные примеры структуры .qwen/skills/)
Часть 16 курса sdd (четырёхслойное ревью): Материалы курса — для подготовки к уровню 3
Часть 20 курса sdd (антипаттерны): Материалы курса — для распознавания типичных ошибок
Часть 10 курса sdd (кодификация): Материалы курса — для механизма превращения наблюдений в правила
Часть 15 курса sdd (заменяемость агента): Материалы курса — для проверки независимости от конкретного инструмента
Книга 'working effectively with legacy code' (michael feathers): Классика про границы изменений — применима к границам решений в SDD
Практика 'prompt engineering for developers' (deeplearning.ai): Для понимания роли /clear и разделения контекстов
Резюме: SDD — это рабочая система контроля, а не бюрократия. Её ядро — четыре границы: спецификации хранят намерение, факты допускают к слиянию, агент быстро исполняет, человек отвечает за суждение. Начните с минимума: 5 файлов и одного неукоснительного правила. Достигните уровня 2 через дисциплину /clear, исполняемых фактов в validation.md и перепланирования между фичами. Уровни 3 и 4 придут сами, если регулярно проводить ретроспективы и кодифицировать наблюдения — но не делайте их самоцелью. Проверьте свой путь финальным тестом: попросите агента действовать без контекста чата, только по файлам. Если он задаёт хорошие вопросы — вы на правильном пути.