docs/audits/2026-08-26-wealth-ledger-sdd/deepseek-result.md

Анализ схемы 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‑системы.