# Анализ схемы Spec‑Driven Development (openspec) для pet‑проектов ## 1. Введение Данный документ содержит оценку пользовательской схемы `schema.yaml`, предназначенной для организации процесса **Spec‑Driven Development (SDD)** с использованием фреймворка `openspec`. Схема описывает жизненный цикл изменения: от формулирования намерения (`proposal`) до реализации (`tasks`) и выполнения (`apply`). Анализ выполнен на основе предоставленных артефактов (`proposal.md`, `spec.md`, `design.md`, `tasks.md`) и самой схемы. **Общая оценка:** схема **качественная, продуманная и функциональная**. Она соответствует лучшим практикам SDD, обеспечивает чёткое разделение уровней абстракции и поддерживает эволюционное развитие спецификаций. Однако присутствуют области, которые можно улучшить для повышения удобства работы, автоматизации и снижения когнитивной нагрузки на AI‑агента. --- ## 2. Сильные стороны схемы - **Чёткое разделение артефактов** Каждый артефакт решает свою задачу: - `proposal` — *почему* и *что* (бизнес‑намерение); - `specs` — *какое наблюдаемое поведение* (контракт); - `design` — *как архитектурно* (решения); - `tasks` — *что конкретно сделать* (реализация). Это предотвращает смешивание уровней и упрощает коммуникацию между участниками. - **Поведенческий фокус в спецификациях** Требования формулируются с использованием `SHALL/MUST` и сопровождаются сценариями в формате **WHEN‑THEN**, что делает их проверяемыми и независимыми от реализации. - **Поддержка дельт** Операции `ADDED`, `MODIFIED`, `REMOVED` и `RENAMED` позволяют аккуратно эволюционировать существующие возможности, сохраняя историю изменений. - **Учёт архитектурных решений** В `design` присутствуют обязательные разделы: `Delivery Map` (привязка к областям), `Contract Gate Decision` (для API), `Solution Assessment` (для сравнения готовых решений). Это способствует принятию обоснованных технических решений. - **Практичные задачи** `tasks` разбиты на выполнимые шаги с указанием верификации (команды, наблюдаемые результаты). Задачи привязаны к областям из Delivery Map, что обеспечивает покрытие всех affected‑зон. - **Интеграция с `openspec`** Использование `store`, `planningHome.root`, флага `skip_specs` и явной инструкции по архивации показывает глубокое понимание инструмента и его особенностей. --- ## 3. Замечания и области для улучшения ### 3.1. Избыточная детализация инструкций Инструкции для каждого артефакта содержат много пояснений (повторяющиеся правила, подробное описание `planningHome.root`, форматирования). Это усложняет восприятие AI и увеличивает вероятность ошибок при генерации. **Риск:** AI может пропустить важное правило из‑за большого объёма текста. ### 3.2. Отсутствие машинной валидации формата Хотя инструкции описывают правильный синтаксис (например, ровно 4 `#` для сценариев), нет автоматической проверки на этапе генерации. AI может случайно отклониться от ожидаемого формата, и ошибка обнаружится только при валидации `openspec validate`. **Риск:** увеличение итераций на исправление. ### 3.3. Недостаточная поддержка многокомпонентных изменений В схеме не указано, как обрабатывать изменения, затрагивающие **несколько репозиториев** (например, синхронизация API‑контрактов между бэкендом и фронтендом). Упоминается только `Delivery Map` с областями, но нет явных разделов для координации версий, порядка деплоя или обратной совместимости. **Риск:** несогласованность при параллельной разработке. ### 3.4. Размытые критерии для `Solution Assessment` Требуется включать этот раздел, когда изменение вводит или существенно заменяет "дорогостоящее необратимое решение". Однако триггеры перечислены в скобках (auth, storage, external integration и т.п.), но они не формализованы. AI может пропустить необходимость анализа, если не распознает ситуацию. **Риск:** принятие неоптимальных технических решений без сравнения альтернатив. ### 3.5. Отсутствие явного этапа утверждения спецификаций После создания `specs` нет артефакта или флага, обозначающего их утверждение владельцем (например, `status: draft | approved`). В `proposal` требуется утверждение, но для `specs` – нет. Это может привести к тому, что `design` будет писаться по неутверждённым требованиям. **Риск:** переделки при изменении требований на поздних этапах. ### 3.6. Избыточность при модификации требований Инструкция требует копировать **полное** содержание существующего требования (включая все сценарии) в секцию `MODIFIED`. Это увеличивает объём дельты и риск рассинхронизации (например, если в исходном требовании позже появится изменение, а дельта этого не отразит). Хотя такой подход безопасен для архивации, он громоздкий. **Риск:** ошибки копирования и потери изменений. ### 3.7. Отсутствие примеров для сложных сценариев В инструкции приведён только простой пример для нового требования. Нет примеров для `MODIFIED` (с полным копированием), для `RENAMED`, для `design` с заполненным `Solution Assessment` или для `tasks` с перекрёстными зависимостями. **Риск:** AI может неправильно интерпретировать формат, особенно для модификаций. ### 3.8. Неполное описание процесса `apply` В секции `apply` указано "работать с pending tasks и отмечать выполненные", но не описаны завершающие шаги: проверка всех задач, запуск тестов, обновление документации, создание коммита/PR, архивация изменения в `openspec` store. Это оставляет пространство для неполного завершения. **Риск:** незавершённые изменения, потерянные артефакты. ### 3.9. Слабая трассируемость между артефактами Хотя в `tasks` сказано "ссылаться на specs и design", нет явного механизма привязки задач к конкретным требованиям или архитектурным решениям. Например, не указано, какая задача реализует какой requirement. **Риск:** сложно проверить полноту покрытия и проследить impact изменения. --- ## 4. Предложения по улучшению ### 4.1. Упростить инструкции, вынеся общие правила в отдельный файл - Создать `_rules.md` (или `.openspec-rules.md`) в корне проекта, где описать: - общие требования к форматированию; - правила работы с `planningHome.root`; - пояснения по `skip_specs` и дельта‑операциям. - В `schema.yaml` для каждого артефакта оставить только **специфичные** для него инструкции, ссылаясь на общие правила. **Плюсы:** уменьшение объёма инструкций, снижение когнитивной нагрузки на AI, централизованное обновление правил. ### 4.2. Добавить машинную валидацию формата при генерации - Интегрировать проверку сгенерированных файлов через `openspec validate --strict` (или внешний валидатор) перед сохранением. - В инструкции добавить шаг: "После генерации выполни `openspec validate --strict` и исправь ошибки". **Плюсы:** автоматическое обнаружение синтаксических ошибок, сокращение циклов доработки. ### 4.3. Явно определить процесс для кросс‑репозиторных изменений - В `design` добавить раздел **Cross‑repo Dependencies**, где перечислять: - затронутые репозитории и их версии; - необходимый порядок деплоя; - требования к обратной совместимости (если применимо). - При необходимости создать отдельный артефакт `integration-plan.md`, который включается в change. **Плюсы:** синхронизация разработки, снижение риска несовместимости. ### 4.4. Формализовать критерии для включения `Solution Assessment` - Сделать раздел обязательным для всех изменений, кроме тех, что помечены как `trivial` (например, исправление опечаток, рефакторинг без изменения поведения). - В инструкции перечислить **конкретные области**, требующие анализа, в виде чек‑листа: - [ ] Аутентификация/авторизация - [ ] Хранилище данных (схема, миграции) - [ ] Внешние интеграции (новые API, сторонние сервисы) - [ ] Кэширование - [ ] Конкурентность - [ ] Наблюдаемость (логи, метрики, трейсинг) - [ ] Инфраструктура (новые компоненты, изменение конфигурации) - Если ни один пункт не затронут, раздел можно пропустить с пометкой `N/A` и кратким обоснованием. **Плюсы:** единообразие, предотвращение пропусков. ### 4.5. Добавить этап утверждения спецификаций - Ввести артефакт `approval.md` или поле `status` в начале каждого `spec.md` (например, `## Status: Draft | Approved`). - В цепочке зависимостей указать, что `design` может начинаться только после того, как все дельта‑спецификации помечены как `Approved` (владельцем продукта или техническим лидом). - Это можно реализовать через ручную проверку или через CI‑шаг, требующий комментария. **Плюсы:** прозрачность, снижение риска переделок. ### 4.6. Оптимизировать модификацию требований (альтернатива копированию) - Вместо полного копирования разрешить указывать **изменения** в формате diff (например, с использованием маркеров `<<<` / `>>>` или просто явное описание изменений). - При архивации автоматически применять эти изменения к базовому `spec.md` с помощью скрипта слияния. - Однако это требует более сложной обработки. Если такой возможности нет, то сохранить текущий подход, но добавить рекомендацию использовать **внешние инструменты** для поиска и копирования (например, `openspec show`). **Плюсы:** уменьшение дублирования, снижение ошибок. ### 4.7. Добавить примеры для всех типов дельт и сложных ситуаций - В инструкцию или в отдельный файл `_examples.md` включить примеры: - **MODIFIED** с полным копированием существующего требования и его изменением. - **RENAMED** с указанием FROM/TO. - **REMOVED** с Reason и Migration. - **design** с заполненным `Solution Assessment` (например, выбор между готовым и кастомным решением). - **tasks** с перекрёстными зависимостями между репозиториями. **Плюсы:** уменьшение неоднозначности для AI, повышение качества генерируемых артефактов. ### 4.8. Дополнить процесс `apply` завершающими шагами - В секцию `apply` добавить: - После завершения всех задач: запустить полный набор тестов (CI‑пайплайн). - Проверить, что все артефакты соответствуют актуальному состоянию кода. - Создать коммит с изменениями в коде и обновлёнными спецификациями. - Выполнить `openspec archive ` для переноса дельт в основной `specs` store. - Удалить директорию изменения или обновить статус в системе отслеживания задач. **Плюсы:** гарантированное завершение, предотвращение потери изменений. ### 4.9. Ввести трассируемость через мета‑данные в задачах - Добавить в каждую задачу поля (в виде комментариев или меток), например: - `implements: ` – ссылка на конкретное требование. - `related-to: ` – ссылка на решение в design. - Это можно сделать через формат: `- [ ] 1.1 Implement export feature (implements: export-data, related: design#cache-decision)` - Или вынести в отдельную колонку, если используется система управления задачами. **Плюсы:** прослеживаемость, упрощение ревью и аудита. --- ## 5. Заключение Предоставленная схема является **надёжной и работоспособной** основой для SDD в pet‑проектах и даже в небольших командах. Она грамотно использует возможности `openspec` и обеспечивает дисциплину в разработке. Предложенные улучшения направлены на **снижение когнитивной нагрузки, повышение автоматизации и устранение потенциальных пробелов** при работе с несколькими репозиториями и сложными изменениями. Рекомендуется внедрять улучшения поэтапно, начиная с наиболее критичных (например, добавление валидации и формализация `Solution Assessment`), а затем дорабатывать процесс по мере накопления опыта. Данный анализ может быть использован как руководство по дальнейшему развитию вашей SDD‑системы.