179 lines
19 KiB
Markdown
179 lines
19 KiB
Markdown
# Анализ схемы 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 <change> --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 <change>` для переноса дельт в основной `specs` store.
|
||
- Удалить директорию изменения или обновить статус в системе отслеживания задач.
|
||
|
||
**Плюсы:** гарантированное завершение, предотвращение потери изменений.
|
||
|
||
### 4.9. Ввести трассируемость через мета‑данные в задачах
|
||
- Добавить в каждую задачу поля (в виде комментариев или меток), например:
|
||
- `implements: <requirement-id>` – ссылка на конкретное требование.
|
||
- `related-to: <decision-id>` – ссылка на решение в design.
|
||
- Это можно сделать через формат: `- [ ] 1.1 Implement export feature (implements: export-data, related: design#cache-decision)`
|
||
- Или вынести в отдельную колонку, если используется система управления задачами.
|
||
|
||
**Плюсы:** прослеживаемость, упрощение ревью и аудита.
|
||
|
||
---
|
||
|
||
## 5. Заключение
|
||
|
||
Предоставленная схема является **надёжной и работоспособной** основой для SDD в pet‑проектах и даже в небольших командах. Она грамотно использует возможности `openspec` и обеспечивает дисциплину в разработке. Предложенные улучшения направлены на **снижение когнитивной нагрузки, повышение автоматизации и устранение потенциальных пробелов** при работе с несколькими репозиториями и сложными изменениями.
|
||
|
||
Рекомендуется внедрять улучшения поэтапно, начиная с наиболее критичных (например, добавление валидации и формализация `Solution Assessment`), а затем дорабатывать процесс по мере накопления опыта.
|
||
|
||
Данный анализ может быть использован как руководство по дальнейшему развитию вашей SDD‑системы.
|