Тема: Приложение A. Как учебник соотносится со Spec Kit и Kiro
Уровень сложности: Средний
Расчётное время изучения: 3-4 часа активного изучения + 2 часа практики
Предварительные требования: Базовое понимание SDD (Specification-Driven Development)
Знакомство с Markdown-форматированием
Опыт работы с хотя бы одним AI-ассистентом для программирования
Понимание базовых концепций управления проектами (дорожные карты, требования, планирование)
Цели обучения: Сопоставить семь артефактов учебника с аналогичными элементами в Spec Kit и Kiro, используя таблицу соответствия
Обосновать выбор формата (учебник/Spec Kit/Kiro) для конкретного проекта на основе критериев из приложения
Выполнить перенос процесса из одной системы в другую, сохраняя смысл артефактов, а не только их названия
Сформулировать явные проверочные факты в validation.md для гипотетического проекта
Определить недостатки упрощённого формата учебника и предложить дополнительные соглашения для большой команды
Обзор: Данное приложение учебника по SDD раскрывает взаимосвязь между авторским форматом спецификаций (файлы mission.md, tech-stack.md, roadmap.md, requirements.md, plan.md, validation.md, QWEN.md) и двумя промышленными системами: Spec Kit и Kiro. Ключевой тезис — формат не должен становиться догмой; важно сохранять намерение, план, проверку и решения в ревьюируемых артефактах. Учебник преднамеренно упрощён для обучения и прямой работы с Qwen Code, тогда как Spec Kit и Kiro предлагают более богатую инфраструктуру команд, шаблонов и интеграций. Изучение этого приложения позволит читателю свободно перемещаться между системами, адаптировать процессы под нужды команды и принимать обоснованные решения о выборе инструментария.
Ключевые концепции: Авторский диалект sdd для qwen code: Семь Markdown-файлов, образующих полный цикл спецификации: от миссии до валидации. Формат разработан для прямого чтения AI-агентом без специальных CLI-утилит. Каждый файл отвечает за отдельный аспект мышления: зачем проект существует, какие ограничения, в каком порядке строить, что именно строить, как разбить реализацию, какие факты допускают слияние, и как агент должен вести себя.
Validation.md как отдельный этап мышления: Главное архитектурное отличие учебника от альтернатив. Вместо распределения проверочных критериев по задачам, чек-листам или анализу плана — явный файл с фактами, решающими, можно ли сливать ветку. Это создаёт отдельный слой мышления о качестве, видимый до начала реализации.
Spec kit: Система спецификаций с командами вида /speckit.specify, /speckit.clarify, /speckit.plan, /speckit.tasks, /speckit.analyze. Предоставляет готовые шаблоны, расширения, пресеты и повторяемые рабочие процессы. Ориентирована на команды с несколькими проектами, требующими единого стандарта.
Kiro: Платформа с тремя слоями: steering-файлы (постоянные правила), specs (конкретные фичи), задачи и тесты (проверяемый путь). Тесно интегрирована с IDE-процессом, использует agent hooks и steering для управления поведением агента.
Таблица соответствия артефактов: Инструмент маппинга между системами. Показывает, что mission.md = конституция проекта (Spec Kit) = steering-файлы (Kiro); requirements.md = /speckit.specify + /speckit.clarify = requirements; plan.md = /speckit.plan + /speckit.tasks = design + tasks; validation.md = частично /speckit.analyze + чек-листы = критерии в задачах и тестах.
Перенос процесса через сохранение смысла: Методология адаптации: не навязывать имена файлов, а переносить принципы — явная конституция, уточнение неоднозначностей до плана, отделение архитектурных решений от списка задач, видимые проверочные факты до реализации, сравнение реализации с артефактами а не с памятью чата.
Три слоя kiro для переноса: Steering-файлы (постоянные правила проекта), specs (конкретные спецификации фич), задачи и тесты (проверяемый путь к реализации). При миграции из учебника в Kiro нужно распределить содержимое по этим слоям.
Критерии выбора формата: Учебник — для обучения, маленьких проектов, прозрачности в Markdown, независимости от платформы. Spec Kit — для готовых команд, уточнения неоднозначностей, расширений, множества проектов. Kiro — для существующих пользователей Kiro, IDE-интеграции, встроенных specs и agent hooks.
Недостатки упрощённого формата: В большой команде требуются дополнительные соглашения: запросы на слияние, владельцы дорожной карты, ревью спецификаций, шаблоны задач. Эти темы раскрыты в части 16 учебника.
Ревьюируемые артефакты как ядро процесса: Главная мета-принцип: не важно, как называются файлы или какая CLI используется — важно, чтобы намерение, план, проверка и решения существовали в артефактах, которые можно ревьюировать, версионировать и сравнивать с реализацией.
Практические упражнения: Название: Упражнение 1: Построение таблицы соответствия для гипотетического проекта
Проблема: Вам дан проект: мобильное приложение для отслеживания привычек. В учебном формате уже созданы файлы: mission.md («помочь пользователям выстроить устойчивые привычки через геймификацию»), tech-stack.md (Flutter, Firebase, Provider), roadmap.md (MVP → социальные функции → аналитика), requirements.md (список пользовательских сценариев), plan.md (архитектура + задачи по спринтам), validation.md (метрики удержания, покрытие тестами). Задача: заполните таблицу соответствия, указав, как каждый файл учебника отобразился бы в Spec Kit (конкретные команды) и в Kiro (конкретные слои/файлы). Для validation.md обоснуйте, почему его отдельное существование — архитектурное решение, а не просто удобство.
Решение: Шаг 1: mission.md → Spec Kit: конституция проекта (вводится через /speckit.init или вручную в заголовке спецификации); Kiro: steering-файл project.md или habits-steering.md. Шаг 2: tech-stack.md → Spec Kit: часть конституции + план (ограничения фиксируются в /speckit.clarify, технический план в /speckit.plan); Kiro: steering-файл tech-steering.md + design/specs. Шаг 3: roadmap.md → Spec Kit: порядок спецификаций и задач, управляемый через /speckit.tasks; Kiro: список фич в specs/ с приоритетами. Шаг 4: requirements.md → Spec Kit: /speckit.specify для функциональных требований, /speckit.clarify для неоднозначностей; Kiro: файлы specs/habit-tracking.md, specs/gamification.md. Шаг 5: plan.md → Spec Kit: /speckit.plan для архитектурных решений, /speckit.tasks для декомпозиции; Kiro: design/architecture.md + tasks/ с отдельными задачами. Шаг 6: validation.md → Spec Kit: частично /speckit.analyze (проверка после реализации) + чек-листы в задачах; Kiro: критерии приёмки в каждой задаче + тесты. Обоснование отдельного validation.md: он создаёт 'фронтир качества' — факты, которые должны быть видны до реализации, а не выводиться постфактум. Это меняет психологию команды: разработчик видит критерии успеха до написания кода, что предотвращает 'движение ради движения'. В Spec Kit и Kiro эта идея 'растворена' в процессе, что требует дополнительной дисциплины. Шаг 7: QWEN.md → Spec Kit: правила агента в пресетах; Kiro: agent hooks и steering-файлы для поведения.
Сложность: intermediate
Название: Упражнение 2: Миграция с сохранением смысла — из учебника в Kiro
Проблема: Команда из 4 разработчиков 3 месяца работала по формату учебника. Накоплено: mission.md, tech-stack.md, roadmap.md с 12 пунктами, requirements.md с 8 пользовательскими историями, plan.md с архитектурным решением использовать Clean Architecture, validation.md с 5 критериями. Команда переходит на Kiro. Задача: определите, какое содержимое попадёт в steering-файлы, specs, задачи и тесты. Особое внимание: validation.md содержит критерий 'время отклика API < 200 мс для 95-го перцентиля' — где он окажется в Kiro и как обеспечить его видимость ДО реализации, как это делал отдельный файл?
Решение: Шаг 1: Steering-файлы (постоянные правила): mission.md → project-steering.md; tech-stack.md → tech-steering.md; принципы из QWEN.md → agent-steering.md. Шаг 2: Specs (конкретные фичи): каждый пункт roadmap.md + связанные требования → отдельный файл в specs/: auth-spec.md, habit-creation-spec.md, gamification-spec.md и т.д. requirements.md разбивается и встраивается в соответствующие specs. Шаг 3: Архитектура из plan.md → design/clean-architecture.md (отдельный spec уровня системы). Шаг 4: Задачи и тесты: декомпозиция plan.md → tasks/ с привязкой к specs. Шаг 5: Критерий производительности из validation.md: в Kiro он попадаёт в критерии приёмки задач, связанных с API. Проблема: он 'растворяется' в задачах. Для сохранения видимости ДО реализации: создать performance-steering.md в steering-файлах с глобальным SLA; добавить performance-spec.md как системный spec; включить критерий в Definition of Done для всех API-задач; создать отдельную задачу 'Настроить нагрузочное тестирование' в первом спринте. Таким образом, смысл 'явных проверочных фактов до реализации' сохраняется через многоуровневое дублирование и системные спецификации, хотя форма изменилась.
Сложность: intermediate
Название: Упражнение 3: Обоснование выбора формата для конкретного контекста
Проблема: Три сценария: (А) Соло-разработчик, изучающий SDD, создаёт pet-project на выходных. (Б) Продуктовая команда из 15 человек, 3 проекта на React, нужен единый стандарт спецификаций для передачи между дизайнерами, аналитиками и разработчиками. (В) Команда из 8 человек уже год работает в VS Code с Kiro, довольны IDE-интеграцией, но чувствуют, что спецификации 'размываются' по задачам и чатам. Для каждого сценария: выберите формат, обоснуйте по 3 критериям из приложения, укажите риск и митигацию.
Решение: Сценарий А: Формат учебника. Критерии: (1) изучает SDD — прямое соответствие; (2) проект маленький — не требует инфраструктуры; (3) нужна независимость от платформы — pet-project не привязан к корпоративным лицензиям. Риск: при масштабировании потеряется структура. Митигация: заранее договориться о соглашениях из части 16, если проект вырастет. Сценарий Б: Spec Kit. Критерии: (1) готовые команды и шаблоны — нужен единый стандарт для 15 человек; (2) отдельный шаг уточнения неоднозначностей — критично при передаче между ролями; (3) несколько проектов — требуется единый стандарт. Риск: избыточная формализация замедлит стартап-проекты. Митигация: создать 'лёгкий' пресет Spec Kit для MVP-фаз. Сценарий В: Kiro с доработкой. Критерии: (1) уже работают в Kiro — миграционные издержки минимальны; (2) нужна IDE-интеграция — сохраняется; (3) проблема 'размывания' specs — решается внедрением явных steering-файлов и отдельных spec-файлов по аналогии с validation.md. Риск: команда воспринимает доработку как 'ещё одну бюрократию'. Митигация: провести воркшоп, показав, как явные specs экономят время на уточнениях в чате.
Сложность: intermediate
Название: Упражнение 4: Создание validation.md для существующего Spec Kit-проекта
Проблема: Дан проект на Spec Kit: e-commerce платформа. Команда использует /speckit.specify для требований, /speckit.plan для архитектуры, /speckit.tasks для декомпозиции, /speckit.analyze для проверки после реализации. Проблема: критерии приёмки 'размазаны' по задачам в Jira, нет единого места для проверки перед merge. Задача: создайте validation.md в духе учебника, извлекая и консолидируя критерии. Содержимое должно включать: (1) функциональные критерии для корзины; (2) нефункциональные (производительность, безопасность); (3) процесс 'валидационного ревью' перед merge.
Решение: Структура validation.md: Раздел 1: Контекст — 'Этот файл содержит факты, которые должны быть подтверждены перед слиянием в main. Ни одна ветка не мержится без проверки по этому списку.' Раздел 2: Функциональные критерии (корзина): [F1] Добавление товара обновляет счётчик за < 100 мс без перезагрузки; [F2] При изменении количества пересчёт стоимости происходит на клиенте с валидацией на сервере; [F3] Сохранение корзины между сессиями для авторизованных пользователей; [F4] Очистка корзины после успешного оформления заказа с подтверждением. Раздел 3: Нефункциональные критерии: [N1] Время отклика API корзины < 200 мс (p95) при нагрузке 1000 RPS; [N2] Все операции модификации требуют валидного JWT; [N3] SQL-инъекции невозможны по результатам автоматического сканирования; [N4] Логи не содержат PII (проверка регулярным выражением в CI). Раздел 4: Процесс валидационного ревью: Шаг 1 — автор ветки заполняет validation-checklist.md в PR; Шаг 2 — CI прогоняет автоматические проверки N1-N4; Шаг 3 — ревьюер верифицирует F1-F4 вручную на staging; Шаг 4 — при несоответствии — блокировка merge с указанием невыполненного пункта; Шаг 5 — после merge — /speckit.analyze для выявления скрытых рисков. Интеграция с Spec Kit: validation.md не заменяет /speckit.analyze, а предшествует ему, создавая 'ворота' перед merge. Команда сохраняет привычные команды, но добавляет явный артефакт качества.
Сложность: advanced
Кейсы: Название: Кейс: Миграция стартапа с учебного формата на Spec Kit при росте команды с 2 до 12 человек
Сценарий: EdTech-стартап 'LinguaFlow' начинал с двух основателей, использовавших формат учебника для разработки платформы изучения языков. За 8 месяцев проект вырос: появились отдельный дизайнер, аналитик, 6 разработчиков, 2 QA. Файлы mission.md, roadmap.md и т.д. хранились в общем репозитории, но процесс 'размывался': разработчики трактовали requirements.md по-разному, QA не знали, по каким критериям проверять фичи, аналитик вносил изменения в roadmap.md без уведомения команды.
Задача: Три конкретные проблемы: (1) requirements.md превратился в 'стену текста' на 400 строк, который никто не обновлял; (2) validation.md существовал, но разработчики мержили ветки, 'помня' критерии, не сверяясь с файлом; (3) при onboarding новых разработчиков формат учебника требовал личного разъяснения от основателей — масштабирование знаний не работало. Команда рассматривала Kiro (один разработчик использовал в личных проектах), но основатели боялись потерять 'простоту' и 'контроль'.
Решение: Переход на Spec Kit с сохранением смысла: (1) mission.md и tech-stack.md консолидировали в конституцию проекта, доступную через /speckit.init; (2) requirements.md разбили на 8 отдельных спецификаций (/speckit.specify), каждая с владельцем-аналитиком; (3) ввели обязательный /speckit.clarify перед планированием — дизайнер и аналитик должны разрешить все 'TBD' в требованиях; (4) plan.md трансформировали в /speckit.plan + /speckit.tasks с явным разделением архитектуры и задач; (5) критерии из validation.md встроили в чек-листы задач и добавили /speckit.analyze как пост-реализационную проверку; (6) создали пресет 'LinguaFlow-Standard' с правилами агента, наследующими QWEN.md. Ключевое решение: сохранить идею 'явных проверочных фактов' через обязательный чек-лист в /speckit.tasks, а не отдельный файл.
Результат: Через 3 месяца: время onboarding сократилось с 2 недель до 3 дней (новый разработчик запускает /speckit.init и получает полный контекст); количество 'возвратов' фич из QA к разработке снизилось на 60% (благодаря /speckit.clarify); аналитик и дизайнер стали владельцами спецификаций, разработчики — владельцами задач; основатели сохранили контроль через ревью конституции и /speckit.analyze. Непредвиденный эффект: пресет 'LinguaFlow-Standard' оказался настолько удачным, что команда начала продавать консалтинг по внедрению Spec Kit другим EdTech-компаниям.
Извлечённые уроки: Простота формата учебника становится ловушкой при росте команды — масштабирование требует институционализации процессов
Идея 'явных проверочных фактов' переносима между системами, но форма должна адаптироваться к культуре команды
Сопротивление миграции часто связано не с техническими рисками, а с потерей 'контроля' основателями — это решается через их роль в конституции и /speckit.analyze
Успешная миграция требует 'посредника', понимающего обе системы — в данном случае, разработчика с опытом Kiro, который перевёл принципы на язык Spec Kit
Связанные концепции: Таблица соответствия артефактов
Перенос процесса через сохранение смысла
Недостатки упрощённого формата
Критерии выбора формата
Название: Кейс: Интеграция validation.md в существующий Kiro-проект корпоративного банка
Сценарий: Команда цифрового банка 'FinSecure' (20 разработчиков, 5 продуктовых команд) использовала Kiro 2 года. Структура: steering-файлы для compliance-требований, specs для каждой фичи, задачи в Jira с критериями приёмки. Регуляторное давление усилилось: требовалось доказать, что каждая фича проверена по 47 контрольным пунктам до попадания в production. Существующие критерии в задачах оказались фрагментированы, аудит не мог восстановить полную картину.
Задача: Kiro не предусматривал 'единого места истины' для валидационных фактов — они были распределены по задачам, тестам, чек-листам в Confluence. При аудите команда тратила 3-5 дней на сбор доказательств по одной фиче. Риск: невозможность пройти регуляторный аудит, штрафы, ограничение лицензии. Миграция на другую систему была исключена из-за глубокой интеграции Kiro с банковской IDE и security-политиками.
Решение: Адаптация идеи validation.md внутри Kiro: (1) создан отдельный слой 'validation specs' — файлы вида specs/validation/feature-X-validation.md, обязательные для всех фич, затрагивающих деньги или данные клиентов; (2) validation spec содержит 47 контрольных пунктов, сгруппированных по рискам, с явными полями 'подтверждающий артефакт' (ссылка на тест, лог, ревью); (3) в CI добавлен шаг 'validation gate' — сборка блокируется, если validation spec не ревьюирован security-офицером; (4) steering-файл validation-steering.md определяет, какие фичи требуют validation spec; (5) агентный hook в Kiro автоматически предлагает шаблон validation spec при создании specs для критичных фич. Таким образом, смысл 'отдельного этапа мышления о качестве' был интегрирован в Kiro без нарушения существующей инфраструктуры.
Результат: Время подготовки к аудиту сократилось с 3-5 дней до 2 часов (все validation specs в одной директории с чёткой структурой). Первый регуляторный аудит прошёл без замечаний по процессу валидации. Неожиданный эффект: разработчики стали раньше думать о compliance — validation spec создавался на этапе проектирования, а не в спешке перед релизом. Команда зафиксировала паттерн как 'Kiro Validation Extension' и передала в open-source сообщество.
Извлечённые уроки: Идея из 'простого' учебника может решать 'enterprise'-проблемы при правильной адаптации
Распределённые критерии качества создают 'скрытый долг' — единое место истины необходимо для регуляторных и аудиторских требований
Интеграция нового артефакта в существующую систему требует автоматизации (CI gate, агентные hooks) — иначе дисциплина не удержится
Steering-файлы в Kiro идеально подходят для определения политик, а specs — для конкретных проверок: это соответствует изначальной архитектуре Kiro
Связанные концепции: validation.md как отдельный этап мышления
Три слоя Kiro для переноса
Ревьюируемые артефакты как ядро процесса
Перенос процесса через сохранение смысла
Советы по изучению: Создайте физическую или цифровую 'карту соответствия': распечатайте таблицу из приложения и дополните её собственными примерами из ваших проектов — моторная память и визуализация усиливают запоминание
Практикуйте 'обратный перевод': возьмите спецификацию в формате Spec Kit (/speckit.specify) или Kiro (spec-файл) и перепишите её в формат учебника — это развивает глубинное понимание структуры, а не только поверхностное распознавание названий
Проведите 'аудит своего проекта': какие артефакты из таблицы соответствия существуют у вас явно, какие 'растворены' в чатах, памяти, задачах? Это упражнение раскрывает 'скрытый долг' спецификаций
Изучайте через сравнение трёх колонок: для каждого артефакта задайте вопросы — 'Что добавляется?', 'Что теряется?', 'Что меняет порядок мышления?' — это предотвращает механистический перенос названий без переноса смысла
Используйте 'сценарийный метод': придумайте конкретную команду (размер, опыт, существующие инструменты) и обоснуйте выбор формата — лучше 3 глубоких сценария, чем 10 поверхностных
Фокусируйтесь на validation.md: это главное архитектурное отличие. Попробуйте объяснить коллеге, почему 'отдельный файл' меняет психологию разработки — если объяснение убедительно, вы поняли суть
Читайте часть 16 учебника параллельно: недостатки упрощённого формата раскрыты там, и понимание границ формата критично для осознанного выбора
Практикуйте 'перевод' на уровне процессов, не только артефактов: как шаг /speckit.clarify в Spec Kit соотносится с 'уточнением неоднозначностей до плана' в учебнике? Это требует понимания workflow, не только структуры файлов
Дополнительные ресурсы: Оригинальный учебник по sdd для qwen code: Полный текст курса, включая часть 16 о масштабировании процессов в больших командах
Документация spec kit: Официальные руководства по командам /speckit.*, пресетам, расширениям и интеграциям
Документация kiro: Руководства по steering-файлам, specs, agent hooks и IDE-интеграции
Сравнительный анализ sdd-инструментов: Обзорные статьи о Spec Kit, Kiro, а также менее известных системах (например, Aider, Claude Code projects)
Паттерны спецификации в регулируемых индустриях: Кейсы из fintech, healthtech, aerospace о том, как 'явные проверочные факты' решают compliance-задачи
Исходные материалы курса (база знаний): Полный контекст, на основе которого сгенерирован данный гайд — для углублённого изучения связей между разделами
Резюме: Приложение A демонстрирует, что формат спецификаций — это инструмент, а не догма. Авторский диалект учебника (семь Markdown-файлов от mission.md до validation.md) сознательно упрощён для обучения и прямой работы с Qwen Code, тогда как Spec Kit и Kiro предлагают промышленную инфраструктуру команд, шаблонов и интеграций. Главное архитектурное отличие учебника — validation.md как отдельный этап мышления о качестве, создающий 'фронтир' проверочных фактов до реализации. Таблица соответствия позволяет перемещаться между системами, сохраняя смысл артефактов. Выбор формата зависит от контекста: учебник для обучения и маленьких проектов, Spec Kit для команд с готовыми процессами и множеством проектов, Kiro для глубокой IDE-интеграции и agent hooks. Успешная адаптация требует понимания не только 'что' переносить, но и 'зачем' — намерение, план, проверка и решения должны жить в ревьюируемых артефактах независимо от выбранной платформы.